3.9 arrays

The type of Array values. Arrays are a mutable, fixed-length collection indexed by non-negative integers.

3.9.1 Array Constructor

Creates an Array with the given elts.

a :: Array<String> = [array: "a", "b"]

3.9.2 Other Ways to Build Arrays

Constructs an array of length count, where every element is the value given as elt. Note the use of is=~ below, which is necessary because arrays are mutable and only compare their contents when using equal-now.

check:
  a = array-of(true, 5)
  a is=~ [array: true, true, true, true, true]
end

Note that the value is not copied, so if you construct an array of arrays with array-of, all the elements will share updates.

check:
  a1 = [array: "a1"]
  a2 = array-of(a1, 3)
  a2 is=~ [array: [array: "a1"], [array: "a1"], [array: "a1"]]

  a1.set-now(0, "b1")
  a2 is=~ [array: [array: "b1"], [array: "b1"], [array: "b1"]]
end

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

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.

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

3.9.3 Array Methods

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

check:
  a = [array: "a", "b", "c"]
  a.get-now(0) is "a"
  a.get-now(1) is "b"
  a.get-now(2) is "c"
  a.get-now(3) raises "index too large"
end

Returns a List containing the same elements as this array 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 used.

check:
  a = [array: "a", "b", "c"]
  a.to-list-now() is [list: "a", "b", "c"]
end

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() and a.to-list-now() at two different points in the program produces two different results.

check:
  a = [array: "a", "b", "c"]

  a.get-now(0) is "a"
  a.to-list-now() is [list: "a", "b", "c"]

  b = a

  a.set-now(0, "d")

  a.get-now(0) is "d"
  a.to-list-now() is [list: "d", "b", "c"]

  b.get-now(0) is "d"
end

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

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

  b = [array:]
  b.length() is 0
end

3.9.4 Array Functions

Equivalent to array.get-now(index) (function examples below).

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

Equivalent to array.to-list-now() (function examples below).

Equivalent to array.length() (function examples below).

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

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

  array-get-now(a, 1) is "b"

  array-length(a) is 3
  l = array-to-list-now(a)
  l is [list: "a", "b", "a"]

  # Updating doesn't change the old to-list value
  array-set-now(a, 2, "c")
  l is [list: "a", "b", "a"]
  l2 = array-to-list-now(a)
  l2 is [list: "a", "b", "c"]
end