On this page:
Array
3.9.1 Array Creation Functions
array
array-of
build-array
array-from-list
3.9.2 Array Methods
.get-now
.set-now
.length
.to-list-now
3.9.3 Array Functions
array-get-now
array-set-now
array-to-list-now
array-length

3.9 arrays

An Array is a mutable, fixed-length collection indexed by non-negative intgers. These arrays are implemented using RawArray, but provide an easier-to-use, more Pyret-like API.

3.9.1 Array Creation Functions
[array: elt :: a, ...] -> Array<a>

Creates an Array with the given elements. Note that Arrays are mutable, so comparisons using == (the operator for equal-always) will only return true on Arrays when they are also identical, regardless of their contents. To compare the elements, use equal-now/=~, and test with is=~.

Examples:

check: a = [array: 1, 2, 3] a is a a is== a [array: 1, 2, 3] is=~ [array: 1, 2, 3] [array: 1, 2, 3] is-not== [array: 1, 2, 3] [array: 1, 2, 3] is-not [array: 1, 2, 3] end

array-of :: (elt :: a, count :: Number) -> Array<a>

Constructs an Array of length count, where every element is the value given as elt.

Note that value is not copied, so, the elements of Arrays created with array-of will always be identical.

Examples:

check: arr = array-of(true, 2) arr is=~ [array: true, true] arr is-not [array: true, true] array-get-now(arr, 0) is<=> array-get-now(arr, 1) array-set-now(arr, 1, false) arr is=~ [array: true, false] arr-of-arrs = array-of(arr, 3) arr-of-arrs is=~ [array: [array: true, false], [array: true, false], [array: true, false]] array-set-now(arr, 0, false) arr-of-arrs is=~ [array: [array: false, false], [array: false, false], [array: false, false]] end

To create an array of arrays where each array is new and independent, use build-array.

build-array :: (f :: (Number -> a), count :: Number) -> Array<a>

Takes a function (f) that creates a new element when given a number, and a number to count up to (count), and calls f on each number from 0 to count - 1, creating an array out of the results.

Examples:

check: fun build(n :: Number) -> Array<String>: array-of("_", 3) end a = build-array(build, 3) a is=~ [array: [array: "_", "_", "_"], [array: "_", "_", "_"], [array: "_", "_", "_"]] a.get-now(0).set-now(0, "X") a.get-now(1).set-now(1, "O") a is=~ [array: [array: "X", "_", "_"], [array: "_", "O", "_"], [array: "_", "_", "_"]] end

array-from-list :: (l :: List<a>) -> Array<a>

Converts a list of items into an array of items.

Examples:

check: array-from-list([list: 1, 2, 3]) is=~ [array: 1, 2, 3] end

3.9.2 Array Methods

.get-now :: (index :: Number) -> a

Returns the value at the given index. If the index is too large, is negative, or isn’t a whole number, an error is raised. This method has a -now suffix because its answer can change from one call to the next if, for example, .set-now is used.

Examples:

check: a = [array: "a", "b", "c"] a.get-now(0) is "a" a.get-now(1) is "b" end

.set-now :: (index :: Number, value :: a) -> Nothing

Updates the value at the given index, returning Nothing. The update is stateful, so all references to the array see the update. This also justifies the -now suffix; in the example below calling a.get-now() at two different points in the program produces two different results.

Examples:

check: a = [array: "a", "b", "c"] a.get-now(0) is "a" b = a a.set-now(0, "d") a is=~ [array: "d", "b", "c"] b is=~ [array: "d", "b", "c"] c = b.set-now(0, 'z') c is nothing end

.length :: () -> Number

Returns the length of the array. The length of an array is set when it is created and cannot be changed.

Examples:

check: a = [array: "a", "b"] a.length() is 2 b = [array:] b.length() is 0 end

.to-list-now :: () -> List<a>

Converts a Array to a List containing the same elements in the same order. This method has a -now suffix because its answer can change from one call to the next if, for example, .set-now is subsequently used.

Note that it does not recursively convert Arrays; only the top-level is converted.

Examples:

check: a = [array: 1, 2, 3] a.to-list-now() is [list: 1, 2, 3] a2 = array-of([array:], 3) a2.to-list-now() is=~ [list: [array:], [array:], [array:]] a2.to-list-now() is-not=~ [list: [list:], [list:], [list:]] end

3.9.3 Array Functions

array-get-now :: (array :: Array<a>, index :: Number) -> a

Equivalent to array.get-now(index)

Examples:

check: a = [array: 0, 1, 2] array-get-now(a, 1) is 1 end

array-set-now :: (
array :: Array<a>,
index :: Number,
value :: a
)
-> Nothing

Equivalent to array.set-now(index, value).

Examples:

check: a = array-of("a", 3) a is=~ [array: "a", "a", "a"] array-set-now(a, 1, "b") a is=~ [array: "a", "b", "a"] end

array-to-list-now :: (array :: Array<a>) -> List<a>

Equivalent to array.to-list-now().

Examples:

check: a = array-of("a", 3) a is=~ [array: "a", "a", "a"] array-set-now(a, 1, "b") a is=~ [array: "a", "b", "a"] l = array-to-list-now(a) l is [list: "a", "b", "a"] end

array-length :: (array :: Array<a>) -> Number

Equivalent to array.length()

Examples:

check: a = array-of("a", 3) a is=~ [array: "a", "a", "a"] array-length(a) is 3 end