User Tools

Site Tools


Passage markup










data structure

date and time

game state






showing and hiding





Types of data

Special keywords

Special passage tags


This is an old revision of the document!

Array data

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 1st, 2nd, 3rd, and so forth: $array's 1st, also written as 1st of $array, refers to the value in the first position. Additionally, you can use last to refer to the last position, 2ndlast to refer to the second-last, and so forth. Arrays also have a length number: $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 contains and 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 any or 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.

(Incidentally, any and all can also be used with other operators, like is, is not, >, <, >=, and <=, 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 the - operator: (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 (a:"C").

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:

Operator Purpose Example
`is` Evaluates to boolean `true` if both sides contain equal items in an equal order, otherwise `false`.
`is not` Evaluates to `true` if both sides differ in items or ordering.
`contains` Evaluates to `true` if the left side contains the right side.
`is in` Evaluates to `true` if the right side contains the left side.
`+` Joins arrays.
`-` 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.
`'s` Obtains the item at the right numeric position, or the `length`, `any` or `all` values.
`of` Obtains the item at the left numeric position, or the `length`, `any` or `all` values.
harlowe/array.1497848782.txt.gz · Last modified: 2017/10/09 20:37 (external edit)