125 lines
2.4 KiB
Text
125 lines
2.4 KiB
Text
# 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 ;
|