====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, [[harlowe:datamap|datamaps]],
are created with [[harlowe:dm|(dm:)]]. Generally, you want to use arrays when you're dealing with values that
directly correspond to //[[harlowe:number|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 [[harlowe:datatype|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 [[harlowe:range|(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 [[harlowe:either|(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%%''. |''%%(a:1,2) is (a:1,2)%%'' (is true)|
|''%%is not%%'' | Evaluates to''%%true%%'' if both sides differ in items or ordering. |''%%(a:4,5) is not (a:5,4)%%'' (is true)|
|''%%contains%%'' | Evaluates to''%%true%%'' 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 to''%%true%%'' 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 the''%%length%%'',''%%any%%'' or''%%all%%'' 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 the''%%length%%'',''%%any%%'' or''%%all%%'' 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%%''|