There are occasions when you may need to work with a whole sequence of values at once. For example, a sequence of adjectives (describing the player) that should be printed depending on what a numeric variable (such as a health point variable) currently is. You could create many, many variables to hold each value, but it is preferable to use an array containing these values.
Arrays are one of the two major “data structures” you can use in Harlowe. The other, datamaps, are created with (dm:). Generally, you want to use arrays when you're dealing with values that directly correspond to numbers, and whose order and position relative to each other matter. If you instead need to refer to values by a name, and don't care about their order, a datamap is best used.
You can refer to and extract data at certain positions inside arrays using
3rd, and so forth:
$array's 1st, also written as
1st of $array, refers to the value in the first position. Additionally, you can
last to refer to the last position,
2ndlast to refer to the second-last, and so forth. Arrays also have
$array's length tells you how many values are in it. If you don't know the exact position
to remove an item from, you can use an expression, in brackers, after it:
$array's ($pos - 3).
To see if arrays contain certain values, you can use the
is in operators like so:
$array contains 1
is true if it contains the number 1 anywhere, and false if it does not.
1 is in $array is another way to write that.
If you want to check if an array contains some, or all of the values, in another array, you can compare with a special
all name on the other array:
$array contains any of (a:2,4,6), and
$array contains all of (a:2,4,6)
will check if
$array contains some, or all, of the numbers 2, 4 and 6.
all can also be used with other operators, like
to compare every value in the array with a number or other value. For instance,
all of (a:2,4) >= 2 is true, as is
any of (a:2,4) >= 4.)
Arrays may be joined by adding them together:
(a: 1, 2) + (a: 3, 4) is the same as
(a: 1, 2, 3, 4).
You can only join arrays to other arrays. To add a bare value to the front or back of an array, you must
put it into an otherwise empty array using the (a:) macro:
$myArray + (a:5) will make an array that's just
$myArray with 5 added on the end, and
(a:0) + $myArray is $myArray with 0 at the start.
You can make a subarray by providing a range (an array of numbers, such as
those created with (range:)) as a reference -
$arr's (a:1,2) produces an array with only the first 2 values of $arr.
Additionally, you can subtract items from arrays (that is, create a copy of an array with certain values removed) using
(a:"B","C") - (a:"B") produces
(a:"C"). Note that multiple copies of a value in an array will all
be removed by doing this:
(a:"B","B","B","C") - (a:"B") also produces
You may note that certain macros, like (either:), accept sequences of values. A special operator,
..., exists which
can “spread out” the values inside an array, as if they were individually placed inside the macro call.
(either: ...$array) is a shorthand for
(either: $array's 1st, $array's 2nd, $array's 3rd), and so forth for as many
values as there are inside the $array. Note that you can still include values after the spread:
(either: 1, ...$array, 5)
is valid and works as expected.
To summarise, the following operators work on arrays:
| Evaluates to boolean||
| Evaluates to||
| Evaluates to||
| Evaluates to||
|Subtracts arrays, producing an array containing every value in the left side but not the right.||
|When used in a macro call, it separates each value in the right side.||
| Obtains the item at the right numeric position, or the||
| Obtains the item at the left numeric position, or the||