User Tools

Site Tools


Passage markup










data structure

date and time

game state






showing and hiding





Types of data

Special keywords

Special passage tags


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 (without needing to be in the same order), 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.)

For a more thorough check of the contents of an array, you can use matches and a datatype pattern. For instance, $array matches (a: num, num) lets you check that $array contains exactly two numbers, and $array matches (a: 2, num) lets you check that $array contains only 2 followed by another number. See the datatype article for more details.

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 booleantrue if both sides contain equal items in an equal order, otherwisefalse. (a:1,2) is (a:1,2) (is true)
is not Evaluates totrue if both sides differ in items or ordering. (a:4,5) is not (a:5,4) (is true)
contains Evaluates totrue if the left side contains the right side. (a:"Ape") contains "Ape",(a:(a:99)) contains (a:99),(a:1,2) contains any of (a:2,3),(a:1,2) contains all of (a:2,1)
is in Evaluates totrue if the right side contains the left side. "Ape" is in (a:"Ape"),(a:99) is in (a:(a:99)),any of (a:2,3) is in (a:1,2),all of (a:2,1) is in (a:1,2)
+ Joins arrays. (a:1,2) + (a:1,2) (is(a:1,2,1,2))
- Subtracts arrays, producing an array containing every value in the left side but not the right. (a:1,1,2,3,4,5) - (a:1,2) (is(a:3,4,5))
... When used in a macro call, it separates each value in the right side. (a: 0, ...(a:1,2,3,4), 5) (is(a:0,1,2,3,4,5))
's Obtains the item at the right numeric position, or thelength,any orall values. (a:"Y","Z")'s 1st (is “Y”),(a:4,5)'s (2) (is 5),(a:5,5,5)'s length (is 3)
of Obtains the item at the left numeric position, or thelength,any orall values. 1st of (a:"Y","O") (is “Y”),(2) of (a:"P","S") (is “S”),length of (a:5,5,5) (is 3)
matches Evaluates to boolean true if the array on one side matches the pattern on the other. (a:2,3) matches (a: num, num), (a: array) matches (a:[[harlowe:a|(a:)]])
is a, is an Evaluates to boolean true` if the right side is array and the left side is an array. (a:2,3) is an array
harlowe/array.txt · Last modified: 2019/04/16 03:52 by l