User Tools

Site Tools


harlowe:array

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
harlowe:array [2017/06/19 01:03]
l created
harlowe:array [2019/04/16 03:52] (current)
l
Line 1: Line 1:
-**(a: // <span class=parameter_optional>​[</​span>​...Any<​span class=parameter_optional>​]</​span>//​) -> //​[[harlowe:​Array|array]]//​** +====Array data====
- +
-Also known as: [[harlowe:​array|(array:​)]] +
- +
-Creates an [[harlowe:​array|array]],​ which is an ordered collection of values. +
- +
-=== Example usage: === +
- +
-''​%%(a:​)%%''​ creates an empty array, which could be filled with other values later. +
-''​%%(a:​ "​gold",​ "​frankincense",​ "​myrrh"​)%%''​ creates an array with three [[harlowe:​string|string]]. +
-This is also a valid array, but with its elements spaced in a way that makes them more readable: +
- +
-<​code>​ +
-(a: +
-"You didn't sleep in the tiniest bed",​ +
-"You never ate the just-right porridge",​ +
-"You never sat in the smallest chair",​ +
-+
-</​code>​ +
-=== Rationale: ​=== +
 There are occasions when you may need to work with a whole sequence of values at once. 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 For example, a sequence of adjectives (describing the player) that should be printed depending
Line 26: Line 6:
 use an array containing these values. use an array containing these values.
  
-Arrays are one of the two major "data structures"​ you can use in Harlowe. The other, [[harlowe:​datamap|datamap]],+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 are created with [[harlowe:​dm|(dm:​)]]. Generally, you want to use arrays when you're dealing with values that
-directly correspond to //​[[harlowe:​number|number]]//, and whose //order// and //​position//​ relative to each other matter.+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. If you instead need to refer to values by a name, and don't care about their order, a datamap is best used.
  
Line 37: Line 17:
 to remove an item from, you can use an expression, in brackers, after it: ''​%%$array'​s ($pos - 3)%%''​. 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%%''​ +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. 
-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.
-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 ''​%%<​=%%'',​ (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 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%%''​.) ''​%%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)%%''​. 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 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 [[harlowe:​a|(a:)]] macro: ''​%%$myArray + (a:​5)%%''​ will make an array that's just+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. $myArray with 5 added on the end, and ''​%%(a:​0) + $myArray%%''​ is $myArray with 0 at the start.
  
Line 67: Line 46:
  
 ^ Operator ^ Purpose ^ Example ^ ^ Operator ^ Purpose ^ Example ^
-`is| Evaluates to boolean ​`trueif both sides contain equal items in an equal order, otherwise ​`false`. | `(a:1,2) is (a:1,2)(is true) +|''​%%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 `trueif both sides differ in items or ordering. | `(a:4,5) is not (a:5,4)(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 `trueif 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)` +|''​%%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 `trueif 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)` +|''​%%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)`+|''​%%+%%'' ​| 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)`+|''​%%-%%'' ​| 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)`+|''​%%...%%'' ​| 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``anyor `allvalues. | `(a:"​Y","​Z"​)'​s 1st(is "​Y"​), ​`(a:​4,​5)'​s (2)(is 5), `(a:​5,​5,​5)'​s length(is 3) +|''​%%'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``anyor `allvalues. | `1st of (a:"​Y","​O"​)(is "​Y"​), ​`(2) of (a:"​P","​S"​)(is "​S"​), ​`length of (a:5,5,5)(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,3is an array%%''​|
-=== Details: === +
- +
-Note that due to the way the spread ​''​%%...%%'' ​operator works, spreading an array into +
-the (a:) macro will accomplish nothing: ​''​%%(a: ​...$array)%%'' ​is the same as just the ''​%%$array%%''​. +
- +
-=== See also=== +
- +
-[[harlowe:dm|(dm:)]], [[harlowe:​ds|(ds:)]] +
harlowe/array.1497848624.txt.gz · Last modified: 2017/10/09 20:37 (external edit)