Arrays
An array is a creature from the early days of computing when everything was binary and the first counting number was zero, so a three by three array (two dimensions) would be set up as MAKE "A ARRAY [3 3], which would be sensibly numbered [1 1] through [3 3], but in fact the cells in the array are actually numbered as:
[0 0][0 1][0 2][1 0][1 1][1 2][2 0][2 1][2 2]
You would put “X” into the middle cell by ASET :A [1 1] "X (rather than the logical ASET :A [2 2] "X) which would result in:
[ ][ ][ ][ ][ X ][ ][ ][ ][ ]
Then someone would put “O” into the lower right cell by ASET :A [2 2] "O (rather than the equally logical ASET :A [3 3] "O) which would result in:
[ ][ ][ ][ ][ X ][ ][ ][ ][ O ]
…and so on. If an element has not been defined yet, it contains an empty list.
If you prefer to start array indexing from 1 on, you can change the PREFS property PREFS/ARRAYBASE to the value 1, as in PPROP "PREFS "ARRAYBASE 1 (or any other value that you prefer as the lowest index).
Access to elements of an array is much faster than access to elements of a list, because the location in the array can be pre-computed instead of having to walk through the list.
AGET
Reports the value of an array element; two inputs.
Syntax
AGET array number
AGET array list
Description
AGET reports the value in a specific location of an array as specified by its inputs. The first element of input is the array to be accessed, while the second element specifies the array element to be obtained. For one-dimensional arrays, the second element may be a number starting from 0; for multi-dimensional arrays, the input element is a list of numbers, where each number stands for one dimension. If no value is stored, arrays report an empty list [].
See also ARRAYDIMS, ARRAY, FILLARRAY, and ASET.
Examples
MAKE “A ARRAY [2 2] AGET :A [1 0] Result: [] ASET :A [1 1] [SQUARE 4] AGET :A [1 1] Result: [SQUARE 4]
ARRAY
Creates an array; expects between one input and two inputs, but parentheses are needed if not called with one input.
Syntax
ARRAY number
ARRAY list
ARRAY word
(ARRAY number list)
(ARRAY list list)
Description
ARRAY creates an array of the size specified by its input. If the input is a number, a one-dimensional array of the specified size is created. Its elements may be accessed by numbers between 0 and the input size less 1.
If the input to ARRAY is a list, the list describes the array. Each number in the list corresponds to the size of one dimension of the array. In order to access an element of a multi-dimensional array, a list of numbers must be supplied to the AGET and ASET primitives, where each number must be in the range from 0 to the number supplied for the corresponding dimension less 1.
If the input is a word, ARRAY creates a one-dimensional array and fills the array with each character of that word.
A list may be supplied as an optional second element if ARRAY and all its arguments are enclosed in parentheses. The contents of this list are the initial values of the array elements. For a description of the structure of the list, see FILLARRAY.
See also ARRAYDIMS, FILLARRAY, and LISTARRAY.
Examples
MAKE “A ARRAY [2 2] ASET :A [1 0] [HELLO WORLD] AGET :A [1 0] Result: [HELLO WORLD] AGET :A [0 0] Result: []
ARRAY?
Also: ARRAYP
Reports TRUE if the object is an array; one input.
Syntax
ARRAY? object
Description
ARRAY? reports TRUE if its input is an array, and FALSE otherwise.
Examples
MAKE “A ARRAY 2 ARRAY? :A Result: TRUE
ARRAYDIMS
Reports the structure of an array; one input.
Syntax
ARRAYDIMS array
Description
ARRAYDIMS reports a list of numbers describing the dimensions of the array named in its input. This list matches the input to the ARRAY command when the array was created. If the array has not been dimensioned yet because it has been created with the NEW command, ARRAYDIMS reports the empty list.
Examples
MAKE “A ARRAY [2 2] ARRAYDIMS :A Result: [2 2]
ASET
Sets the value of an array element; three inputs.
Syntax
ASET array number value
ASET array list value
Description
ASET stores a value into a specific element of an array. ASET requires three inputs: the first input is the name of the array, the second input describes the array element where the value is to be stored, and the third input is the value itself. For one-dimensional arrays, the second input must be a number. For multi-dimensional arrays, the second input is a list of numbers, where each number stands for one dimension.
See also ARRAYDIMS, ARRAY, FILLARRAY, and AGET.
Examples
MAKE “A ARRAY [2 2] ASET :A [1 0] [HELLO WORLD] AGET :A [1 0] Result: [HELLO WORLD] AGET :A [0 0] Result: []
FILLARRAY
Sets the values of an array; two inputs.
Syntax
FILLARRAY array list-or-word
Description
FILLARRAY initializes the array named in its first input with the data in the list given as its second input. If the list is non-structured, the array is filled sequentially regardless of its dimensions. If the list is structured, the array is filled according to the structure of the list and its dimensions.
If the input is a word, FILLARRAY initializes the array with each character of the word.
See also ARRAY, AGET, ASET, and AGET.
Examples
MAKE “A ARRAY [2 2] FILLARRAY :A [1 2 3 4] LISTARRAY :A Result: [[1 2][3 4]]
LISTARRAY
Reports the values of an array as a list; one input.
Syntax
LISTARRAY array
Description
LISTARRAY reports a list whose structure resembles the dimensional structure of the array named in its input.
See also ARRAY, AGET, ASET, and FILLARRAY.
Examples
MAKE “A ARRAY [2 2] ASET :A [0 1] 25 ASET :A [1 1] 50 LISTARRAY :A Result: [[[] 25][[] 50]]
SETARRAYDIMS
Sets the structure of an array; two inputs.
Syntax
SETARRAYDIMS array word
SETARRAYDIMS array list
Description
SETARRAYDIMS accepts a number or a list of numbers describing the dimensions of the array named in its first input. It sets up the structure of the array as requested. All data is released, and the array is empty afterwards.
See also ARRAY, ARRAYDIMS, and FILLARRAY.
Examples
MAKE “A ARRAY [2 2] SETARRAYDIMS :A [3 3] ARRAYDIMS :A
TEXTARRAY
Outputs the structure of an array as a word; one input.
Syntax
TEXTARRAY array
Description
TEXTARRAY converts the contents of an array into a Logo word. The array must only have a single dimension. If an element is a number, TEXTARRAY treats the number as a Unicode character code. The array elements are concatenated without spaces between them.
See also ARRAY, ARRAYDIMS, and FILLARRAY.
Examples
MAKE “A { H E LLO 32 20013 22269} TEXTARRAY :A Result: HELLO 中国