(arrays were added in v1.1)
In addition to the basic types, any variable can also hold an array, which is an ordered list of other values. Values in an array are stored and retrieved by their index, an integer that specifies the value’s position in the array. These indexes are zero based- that is, the first value in an array has an index of 0, the second an index of 1, etc.
New arrays are created using an Array type command (see below for more), eg:
$fruits = Array.new('cherry', 'watermelon', 'lime')
To retrieve a single value already stored in an array you place the index inside square brackets after the variable name:
$firstFruit = $fruits[0]
To change a value stored in an array you simply assign a new value to the index expression:
$fruits[2] = 'peach'
Whenever you access or change a value in an array the index must be in-bounds, meaning the index must be less than the number of values in the array. For example, an array with three values has three valid indexes: 0, 1, and 2. An index of 3 (or greater) is not in-bounds. If you attempt to access an index that is out of bounds an error will be displayed.
Note: every array is an Array object. As an alternative to using the square bracket notation described above, you can also use the object commands and properties described here:
Value Semantics
By default arrays use value semantics, which means a copy of the array is made each time it is assigned. This ensures each variable is independent from one another. For example:
$original = Array.new(1,2,3)
$copy = $original # a copy of $original is implicitly made
$copy.appendValue('😱') # only modifies $copy, leaving $original intact
Prompt $original, $copy # shows two different arrays
If you need to use reference semantics, create a Ref object to the array.
Note: value semantics are not used when passing arrays as arguments to commands.
Array Type Commands
Array.new [firstValue], [secondValue] ... [lastValue] v1.1
Returns a new array containing all the arguments given to the command. If no arguments are given, an empty array is returned.
Array.newWithCount count, [value] v1.1
Returns a new array with count values, all set to the value provided. If no value is given, all values in the array will be the @undefined value.
Array Object Properties
.count v1.1
The number of values the array contains. If you set the count to be less than the current number of items, values are truncated from the end of the array. If the count is greater than the current number of items, then @undefined values are appended to the end of the array.
.firstValue v1.1
Returns the first value in the array (at index zero), or the @undefined value if empty. Read-only.
.lastValue v1.1
Returns the last value in the array (at the highest index), or the @undefined value if empty. Read-only.
Array Object Commands
.valueAtIndex index v1.1
Returns the value held at the given index in the array. The index must be in-bounds or an error will be displayed. This command is exactly the same as:
$value = $array[$index]
.setValueAtIndex value, index v1.1
Changes the value held at the given index in the array to the provided value. The index must be in-bounds or an error will be displayed. This command is exactly the same as:
$array[$index] = $value
.swapValuesAtIndexes index1, index2 v1.1
Exchanges the two values so that the value at index1 resides at index2, and vice versa. Both indexes must be in-bounds or an error will be displayed.
.appendValue value, [value2] ... [lastValue] v1.1
Appends all of the given values, in the order they are given, to the end of the array.
.appendValuesFromArray array v1.1
Appends all the values from the given array to the end of the array.
.prependValue value, [value2] ... [lastValue] v1.1
Inserts all of the given values, in the same order as the argument list, at the start of the array.
.prependValuesFromArray array v2.0.5
Inserts all the values from the given array at the start of the array.
.insertValueAtIndex value, index v1.1
Inserts a single value into the array so the value occupies the location specified by the given index. Any values that already existed at or after the given index are shifted to the next higher index. The given index must be in-bounds or exactly equal to the number of values in the array. In the latter case the value is appended to the end of the array.
.removeValueAtIndex index, [count] v1.1
Removes the value at the given index from the array. Any values that existed after the given index are shifted down to the next lower index. If provided the count specifies how many values to remove, default is one. All indexes must be in-bounds or an error will be displayed.
.removeValuesInRange rangeObject v1.1
Removes all values described by the given Range object from the array. Any values that existed after the given range are shifted down to the next lower index. All indexes in the range must be in-bounds or an error will be displayed.
.push value, [value2] ... [lastValue] v1.1
Appends all of the given values to the end of the array.
.pop v1.1
Removes the last value from the end (highest index) of the array and returns it. If the array is empty this return the @undefined value.
.enqueue value, [value2] ... [lastValue] v1.1
Appends all of the given values to the end of the array.
.dequeue v1.1
Removes the first value from the start (at index zero) of the array and returns it. If the array is empty this returns @undefined.
.containsValue value v2.0
Returns @true if the array contains a value equal to the given value, or @false if not.
.indexOfValue value, [searchRange] v1.1
Searches the array for the first value equal to the one given, and returns the index of that value. If no match is found, returns -1. Optionally a Range object may also be given to limit the portion of the array that is searched. If no range is provided, the entire array is searched.
.subarrayAtIndex firstIndex, count v1.1
Returns a new array containing a subset of the values in the original array. This new array contains count values from the original array, starting at index firstIndex. All indexes must be in-bounds or an error will be displayed.
.subarrayInRange rangeObject v1.1
Returns a new array containing the values described by the given Range object from the original array. All indexes in the range must be in-bounds or an error will be displayed.
.arrayByMakingValuesDoCommand commandName, [argument1] ... [argumentN] v2.0.5
Returns a new array that is formed by sending the given command to all values in this array and collecting the results. Optionally any given arguments are sent along to the command.
An example that forms joined text objects
$array = Array.new('a', 'b', 'c')
$joined = $array.arrayByMakingValuesDoCommand('textByAppending', 'x')
# joined is ('ax', 'bx', 'cx')
This command can also be used to collect object properties into a new array. An example that collects the length property of some text objects:
$array = Array.new('a', 'bb', 'ccc')
$lengths = $array.arrayByMakingValuesDoCommand('length')
# lengths is (1, 2, 3)
.join valueDelimiter v1.1
Returns a Text object of all values in the array, separated by the given delimiter.
$array = Array.new(1, 2, 3)
$string = $array.join('*') # string is '1*2*3'
.sort [options], [language] v1.1
Sorts the array so values are in order from smallest to largest.
The options argument is a string of letters that specifies how sorting of textual values should be handled. Please see the Text object’s compare command for a list of allowed options. In addition to the text comparison options, the ‘r’ option may also be given, which will sort the array in reverse (eg: from largest to smallest).
The optional language argument is a Language object that specifies what collation rules should be considered. The language only has any effect if the comparison mode is set to localized and the user is running on OSX 10.5 (Leopard) or later. This argument was added in v1.3.
.sortWithCommand command, [context] v3.0
Sorts the array using a custom command defined earlier via Define Command, allowing you to control exactly how sorting occurs. Your custom command must accept at least two values to compare. Your command’s return value should follow these guidelines:
|
Return Value |
Meaning |
|
Less than zero |
The first value is smaller (values are ascending) |
|
Zero |
The values are equal. |
|
Greater than zero |
The first value is larger (values are descending) |
Your command may optionally accept a 3rd argument, which is the context value as given to sortWithCommand.
Here’s an example that sorts a list of numbers, but places a single number first regardless of its value:
Define Command MySort( $a, $b, $topmost )
If $a == $topmost
Return -1
ElseIf $b == $topmost
Return 1
End
Return $a - $b
End
$numbers = Array.new(5, 1, 8, 99, 32)
$numbers.sortWithCommand( @command(MySort), 8 )
Prompt $numbers
.randomize v1.1
Randomizes the order of the values in the array.
Array Object Examples
Creating a new array:
$array = Array.new('Jack', 'Kate', 'Lock')
Inspecting values:
$name = $array[2] # name is 'Lock'
$name = $array.valueAtIndex(0) # name is 'Jack'
Adding values:
$array.appendValue('Sayid')
$array.insertValueAtIndex('Boon', 2)
# array is now ('Jack', 'Kate', 'Boon', 'Lock', 'Sayid')
Removing values:
$array.removeValueAtIndex(2)
# array is now ('Jack', 'Kate', 'Lock', 'Sayid')
Partial (sub) arrays:
$halfArray = $array.subarrayAtIndex(0, 2)
# half array is ('Jack', 'Kate')
Finding values:
$index = $array.indexOfValue('Lock') # index is 2
Finding a value in only the first half of the array:
$halfCount = $array.count / 2
$searchRange = Range.new(0, $halfCount)
$index = $array.indexOfValue('Sayid', $searchRange) # index is -1
| Previous Chapter Collection Objects |
<< index >> |
Next Chapter Hashes |