User Tools

Site Tools


Sidebar

Passage markup

basics

coding

extra

list

section

whitespace

Macros

basics

colour

data structure

date and time

game state

live

maths

number

revision

saving

showing and hiding

string

styling

url

deprecated

Types of data

Special keywords

Special passage tags

harlowe:array

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 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)
harlowe/array.txt · Last modified: 2017/10/10 00:39 (external edit)