Working With Arrays

RETRO offers a number of words for operating on statically sized arrays.

Namespace

The words operating on arrays are kept in an a: namespace.

Creating Arrays

The easiest way to create an array is to wrap the values in a { and } pair:

```
{ #1 #2 #3 #4 }
{ 'this 'is 'an 'array 'of 'strings }
{ 'this 'is 'a 'mixed 'array #1 #2 #3 }
```

You can also make an array from a quotation which returns values and the number of values to store in the a:

```
[ #1 #2 #3  #3 ] a:counted-results
[ #1 #2 #3  #3 ] a:make
```

Accessing Elements

You can access a specific value with a:th and fetch or store:

```
{ #1 #2 #3 #4 } #3 a:th fetch
```

Find The Length

Use a:length to find the size of the array.

```
{ #1 #2 #3 #4 } a:length
```

Duplicate

Use a:dup to make a copy of an a:

```
{ #1 #2 #3 #4 } a:dup
```

Filtering

RETRO provides a:filter which extracts matching values from an array. This is used like:

```
{ #1 #2 #3 #4 #5 #6 #7 #8 } [ n:even? ] a:filter
```

The quote will be passed each value in the array and should return TRUE or FALSE. Values that lead to TRUE will be collected into a new array.

Mapping

a:map applies a quotation to each item in an array and constructs a new array from the returned values.

Example:

```
{ #1 #2 #3 } [ #10 * ] a:map
```

Reduce

a:reduce takes an array, a starting value, and a quote. It executes the quote once for each item in the array, passing the item and the value to the quote. The quote should consume both and return a new value.

```
{ #1 #2 #3 } #0 [ + ] a:reduce
```

Search

RETRO provides a:contains? and a:contains-string? to search an array for a value (either a number or string) and return either TRUE or FALSE.

```
#100  { #1 #2 #3 } a:contains?
'test { 'abc 'def 'test 'ghi } a:contains-string?
```

Implementation

In memory, an array is a count followed by the values. As an example, if you have an array:

{ #10 #20 #30 }

In memory this would be setup as:

| Offset | Value | | ------ | ----- | | 000    | 3     | | 001    | 10    | | 002    | 20    | | 003    | 30    |

You can construct one on the fly by keeping a pointer to here and using , to place the values. E.g.,

here [ #3 , #10 , #20 , #30 , ] dip

An example of this can be seen in this excerpt from an example (example/Primes.forth):

:create-set (-a)      here #3000 , #2 #3002 [ dup , n:inc ] times drop ;