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

contents ← prev up next →

1	Getting Started
2	Language Concepts
3	Builtins and Libraries
4	Pyret Style Guide
5	Internals
6	Glossary

3.1	Global Utilities
3.2	Numbers
3.3	Strings
3.4	Booleans
3.5	Raw Array
3.6	Tables
3.7	lists
3.8	sets
3.9	arrays
3.10	string-dict
3.11	option
3.12	pick
3.13	either
3.14	srcloc
3.15	pprint
3.16	s-exp
3.17	s-exp-structs
3.18	color
3.19	image-structs
3.20	The image libraries
3.21	world
3.22	gdrive-sheets
3.23	data-source
3.24	reactors
3.25	chart
3.26	plot
3.27	statistics
3.28	math

3.9.1	Array Creation Functions
3.9.2	Array Methods
3.9.3	Array Functions