3.3.1 RawArray

3.3.1 RawArray🔗

This is an internal library.
The arrays library provides the user-facing version of this library.
By default, Pyret users should use arrays instead. It is primarily designed to be user-facing. This library provides higher performance, but is instead primarily meant for internal use and for building other libaries. Only use this if Arrays are not sufficiently performant for your needs. This library may not provide all the same functionality as arrays, so you may need to modify your code to use it: i.e., you can’t simply replace an array with a RawArray and expect the program to continue to work.

A RawArray is a mutable, fixed-length collection indexed by non-negative intgers. Accessing and mutating a RawArray takes constant time in the size of the array.

3.3.1.1 RawArray Functions🔗

[raw-array: value :: a, ...] -> RawArray<a>

Constructs a RawArray array of length count, whose elements are the values specified in the construction expression.

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

Examples:

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

  a = [raw-array: 1, 2, 3]
  a is a
  a is== a
end

raw-array-of :: (value :: a, count :: Number) -> RawArray<a>

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

Note that value is not copied, so, the elements of RawArrays created with raw-array-of will always be identical (with the usual caveats if the value was a function or method).

Examples:

check:
  arr = raw-array-of(true, 2)
  arr is=~ [raw-array: true, true]
  arr is-not [raw-array: true, true]
  raw-array-get(arr, 0) is<=> raw-array-get(arr, 1)

  raw-array-set(arr, 1, false)
  arr is=~ [raw-array: true, false]

  arr-of-arrs = raw-array-of(arr, 3)
  arr-of-arrs is=~ [raw-array: [raw-array: true, false],
    [raw-array: true, false], [raw-array: true, false]]

  raw-array-set(arr, 0, false)
  arr-of-arrs is=~ [raw-array: [raw-array: false, false],
    [raw-array: false, false], [raw-array: false, false]]
end

raw-array-get :: (array :: RawArray<a>, index :: Number) -> a

Returns the value at the given index.

Using an index too large, negative, or not a whole number raises an error.

Examples:

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

raw-array-set :: (
array :: RawArray<a>,
index :: Number,
new-value :: a
)
-> RawArray<a>

Updates the value at the given index, returning the new value. The update is stateful, so all references to the RawArray see the update.

Using an index too large, negative, or not a whole number raises an error.

Examples:

check:
  a = [raw-array: "a", "b", "c"]
  raw-array-get(a, 0) is "a"

  b = a
  raw-array-set(a, 0, "d")
  a is=~ [raw-array: "d", "b", "c"]
  b is=~ [raw-array: "d", "b", "c"]

  c = raw-array-set(a, 0, "z")
  c is=~ [raw-array: "z", "b", "c"]
end

raw-array-length :: (array :: RawArray<a>) -> Number

Examples:

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

raw-array-to-list :: (array :: RawArray<a>) -> List<a>

Converts a RawArray to a List containing the same elements in the same order.

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

Examples:

check:
  a = [raw-array: 1, 2, 3]
  raw-array-to-list(a) is [list: 1, 2, 3]

  a2 = raw-array-of([raw-array:], 3)
  raw-array-to-list(a2) is=~ [list: [raw-array:], [raw-array:], [raw-array:]]
  raw-array-to-list(a2) is-not=~ [list: [list:], [list:], [list:]]
end

raw-array-from-list :: (lst :: List<a>) -> RawArray<a>

Converts a List to a RawArray containing the same elements in the same order.

Examples:

check:
  raw-array-from-list(empty) is=~ [raw-array: ]
  raw-array-from-list(empty) is-not [raw-array: ]

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

raw-array-build :: (f :: (Number -> a), size :: Number) -> RawArray<a>

Constructs an array of length size, and fills it with the result of calling the function f with each index from 0 to size - 1.

Examples:

check:
  fun sq(x): x * x end
  raw-array-build(sq, 4) is=~ [raw-array: sq(0), sq(1), sq(2), sq(3)]
end

raw-array-build-opt :: (f :: (Number -> Option<Any>), size :: Number) -> RawArray<Any>

Constructs an array based on the results of calling the function f with each index from 0 to size - 1. For each index, if the result of f is some(value), then value is included in the resulting array (it is not included for none). The size of the resulting array is equal to the number of some results.

Examples:

check:
  fun even(n):
    if num-modulo(n, 2) == 0: some(n)
    else: none
    end
  end
  raw-array-build-opt(even, 10) is=~ [raw-array: 0, 2, 4, 6, 8]
end

raw-array-map :: (f :: (a -> b), array :: RawArray<a>) -> RawArray<b>

Creates a new array by applying f to each element of the array. Similar to map. Has an argument order that works with for.

Examples:

check:
  a = [raw-array: "apple", "banana", "plum"]
  lengths = for raw-array-map(s from a):
    string-length(s)
  end
  lengths is=~ [raw-array: 5, 6, 4]
end

Note that the test uses is=~, because raw arrays are mutable and so the two values in the shown test are not equal-always, they are equal-now.

raw-array-filter :: (f :: (a -> Boolean), array :: RawArray<a>) -> RawArray<a>

Applies function f to each element of array from left to right, constructing a new RawArray out of the elements for which f returned true. Similar to filter. Has an argument order that works with for.

Examples:

check:
  a = [raw-array: "apple", "banana", "plum"]
  p-words = for raw-array-filter(s from a):
    string-contains(s, "p")
  end
  p-words is=~ [raw-array: "apple", "plum"]
end

raw-array-sort-nums :: (array :: RawArray<Number>, asc :: Boolean) -> RawArray<Number>

Sorts the given array in-place in ascending or descending order according to the asc parameter. Returns a reference to the original array, which will have its contents mutably updated.

Examples:

check:
  a = [raw-array: 3, 1, 4, 1, 5, 9, 2]

  asc = raw-array-sort-nums(a, true)
  asc is<=> a
  a is=~ [raw-array: 1, 1, 2, 3, 4, 5, 9]

  raw-array-sort-nums(a, false)
  a is=~ [raw-array: 9, 5, 4, 3, 2, 1, 1]
end

raw-array-sort-by :: (
array :: RawArray<a>,
key :: (a -> Number),
asc :: Boolean
)
-> RawArray<a>

Creates a new array containing the sorted contents of the given array. The sort order is determined by calling the key function on each element to get a number, and sorting the elements by their key value (in increasing key order if asc is true, decreasing if false). Ties are broken by the order in which the element is present in the initial array.

Examples:

check:
  a = [raw-array: "let", "us", "go", "then", "you", "and", "i"]

  asc = raw-array-sort-by(a, string-length, true)
  asc is=~ [raw-array: "i", "us", "go", "let", "you", "and", "then"]
  asc is-not=~ a

  desc = raw-array-sort-by(a, string-length, false)
  desc is=~ [raw-array: "then", "let", "you", "and", "us", "go", "i"]

  a is=~ [raw-array: "let", "us", "go", "then", "you", "and", "i"]
end

raw-array-fold :: (
f :: (b, a, Number -> b),
init :: b,
array :: RawArray<a>,
start-index :: Number
)
-> b

Combines the elements in the array with a function that accumulates each element with an intermediate result. The numeric argument to the accumulator is the index of the current element.

Similar to fold_n.

Examples:

check:
  a = [raw-array: "a", "b", "c"]
  str = for raw-array-fold(str from "", elt from a, i from 0):
    if i < (raw-array-length(a) - 1):
      str + elt + ": " + tostring(i) + ", "
    else:
      str + elt + ": " + tostring(i)
    end
  end
  str is "a: 0, b: 1, c: 2"
end

raw-array-concat :: (array1 :: RawArray<a>, array2 :: RawArray<a>) -> RawArray<a>

Creates a new array with all the elements of array1 followed by all the elements of array2.

Examples:

check:
  a1 = [raw-array: 5, 6, 7]
  a2 = [raw-array: 0, 3, 99, -1, 7]

  c = raw-array-concat(a1, a2)
  c is=~ [raw-array: 5, 6, 7, 0, 3, 99, -1, 7]

  a1 is=~ [raw-array: 5, 6, 7]
  a2 is=~ [raw-array: 0, 3, 99, -1, 7]
end

raw-array-duplicate :: (array :: RawArray<a>) -> RawArray<a>

Returns a copy of the given array, such that corresponding elements in the result are Identical to those in the source array.

Examples:

check:
  a = [raw-array: 1, 2, 3]
  b = raw-array-duplicate(a)
  a is=~ b
  b is=~ a

  a is<=> a
  a is-not<=> b
  b is-not<=> a
  b is<=> b

  raw-array-set(a, 1, 1)

  raw-array-get(a, 1) is 1
  raw-array-get(b, 1) is 2

  c = [raw-array: {1; 2}, {3; 4}]
  d = raw-array-duplicate(c)

  c is-not<=> d
  raw-array-get(c, 0) is<=> raw-array-get(d, 0)
  raw-array-get(c, 1) is<=> raw-array-get(d, 1)
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	General-Purpose Libraries
3.2	Archived Libraries
3.3	Internal Libraries

3.3.1	Raw Array
3.3.2	data-source
3.3.3	srcloc
3.3.4	pprint
3.3.5	s-exp
3.3.6	s-exp-structs