# Arrays

Create and manipulate 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 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.

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.

A bytearray is a special form of an array that contains byte values in the range between 0 and 255. These arrays are convenient to handle byte data, and they can be converted to a Logo word. If an element has not been defined yet, it contains the value 0.

## AGET

Reports the value of an array element.

#### 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. Byte arrays always report numbers between 0 and 255 while other arrays report the value stored in the accessed element. If no value is stored, byte arrays report 0 while other arrays report an empty list [].

See also `ARRAYDIMS`, `ARRAY`, `FILLARRAY`, and `ASET`.

#### Example

```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.

#### Syntax

```ARRAY number
ARRAY list
(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.

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`, `BYTEARRAY`, `FILLARRAY`, and `LISTARRAY`.

#### Example

```MAKE "A ARRAY [2 2]
ASET :A [1 0] [HELLO WORLD]
AGET :A [1 0]
Result: [HELLO WORLD]
AGET :A [0 0]
Result: []
```

## ARRAY? (ARRAYP)

Reports TRUE if the object is an array.

#### Syntax

`ARRAY? object`

#### Description

ARRAY? reports TRUE if its input is an array, and FALSE otherwise.

#### Example

```MAKE "A ARRAY 2
ARRAY? :A
Result: TRUE
```

## ARRAYDIMS

Reports the structure of an array.

#### 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` and `BYTEARRAY` primitives 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.

See also `ARRAY`, `BYTEARRAY`, and `FILLARRAY`.

#### Example

```MAKE "A ARRAY [2 2]
ARRAYDIMS :A
Result: [2 2]
```

## ASET

Sets the value of an array element.

#### Syntax

```ASET array number value
ASET array list value```

#### Description

ASET stores a value into a specific element of an array or bytearray. 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.

Byte arrays accept numbers between 0 and 255 as values, while arrays accept any Logo value as values.

See also `ARRAYDIMS`, `ARRAY`, `FILLARRAY`, and `AGET`.

#### Example

```MAKE "A ARRAY [2 2]
ASET :A [1 0] [HELLO WORLD]
AGET :A [1 0]
Result: [HELLO WORLD]
AGET :A [0 0]
Result: []
```

## BYTEARRAY

Creates an array of byte values.

#### Syntax

```BYTEARRAY number
BYTEARRAY list
(BYTEARRAY number word-or-list)
(BYTEARRAY list word-or-list)```

#### Description

BYTEARRAY creates a byte array, a special array in which numbers between 0 and 255 can be stored. If BYTEARRAY has a number as an input, a one-dimensional array of the specified size is created. The elements of the array may be accessed by numbers between 0 and the specified size less 1. Each element of a one-dimensional byte array corresponds to one byte in memory. The `TEXTARRAY` command can be used to convert the contents of a one-dimensional byte array to a Logo word.

If BYTEARRAY has a list of numbers as input, each number in the list corresponds to the size of one dimension of the array. To access an element of a multi-dimensional byte array, a list of numbers must be supplied to the `AGET` and `ASET` primitives with each number in the range from 0 to the number supplied for the corresponding dimension less 1.

A word or a list may be supplied as an optional second element if BYTEARRAY and all its arguments are enclosed in parentheses. The contents of this word or list are the initial values of the array elements. If a word is used, each byte of the word corresponds to one byte of the array.

For a description of the structure of a list, see `FILLARRAY`.

See also `ARRAYDIMS`, `ARRAY`, `FILLARRAY`, and `LISTARRAY`.

#### Example

```MAKE "A BYTEARRAY 2
FILLARRAY :A "HELLO
AGET :A 0
Result: 72
TEXTARRAY :A
Result: HELLO
ASET :A 1 ASCII "I
Result: HILLO
TEXTARRAY :A
Result: HILLO
```

## BYTEARRAY? (BYTEARRAYP)

Reports TRUE if the object is a bytearray.

#### Syntax

`BYTEARRAY? object`

#### Description

BYTEARRAY? reports TRUE if its input is a byte array, and FALSE otherwise.

#### Example

```MAKE "A BYTEARRAY 2
BYTEARRAY? :A
Result: TRUE
```

## FILLARRAY

Sets the values of an array.

#### Syntax

`FILLARRAY array list or word`

#### Description

FILLARRAY initializes the array or byte 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 array has not been dimensioned yet because it has been created with the `NEW` command, FILLARRAY examines the structure of a list and dimensions the array in the same structure.

BYTEARRAYs may be filled by supplying a word as input. The characters of this word are stored into the `BYTEARRAY`, one byte per character.

Byte arrays accept numbers between 0 and 255 as values, while arrays accept any Logo value as values.

See also `ARRAY`, `AGET`, `ASET`, and `AGET`.

#### Example

```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.

#### Syntax

`LISTARRAY array`

#### Description

LISTARRAY reports a list whose structure resembles the dimensional structure of the array or byte array named in its input.

See also `ARRAY`, `AGET`, `ASET`, and `FILLARRAY`.

#### Example

```MAKE "A BYTEARRAY [2 2]
ASET :A [0 1] 25
ASET :A [1 1] 50
LISTARRAY :A
Result: [[0 25][0 50]]
```

## TEXTARRAY

Sets the structure of an array.

#### Syntax

`TEXTARRAY array`

#### Description

TEXTARRAY converts the contents of a bytearray into a Logo word. The bytearray must only contain readable characters. The conversion stops when Logo detects a byte with a zero value, which is an empty byte.

See also `ARRAY`, `BYTEARRAY`, `ARRAYDIMS`, and `FILLARRAY`.

#### Example

```MAKE "A BYTEARRAY 2
ASET :A 0 72
ASET :A 1 73
TEXTARRAY :A
Result: HI
```

### Page Tools 