Array Module

(array/clear arr)

Empties an array `arr`, setting its count to 0 but does not free the backing capacity. Returns `arr`.

(array/concat arr & parts)

Concatenates `parts`, a variable number of arrays and tuples, into the first argument `arr` which must be an array. If any of `parts` are arrays or tuples, their values are inserted into `arr`. Otherwise, each value in `parts` will be appended to `arr` in order. Returns `arr`.

(array/ensure arr capacity growth)

Ensures that the memory backing the array `arr` is large enough for `capacity` items at the given rate `growth`. `capacity` and `growth` must be integers. If the backing capacity is already enough, then there is no change. Otherwise, the backing memory will be reallocated so that there is enough space. Returns `arr`.

(array/fill arr &opt val)

Replace all values of an array `arr` with `val` (defaulting to nil) without changing the length of `arr`. Returns `arr`.

(array/insert arr at & xs)

Insert all `xs` into array `arr` at index `at`. `at` can be an integer between 0 and the length of `arr`. If `at` is negative, will index backwards from the end of `arr`, inserting after the index such that inserting at -1 appends to `arr`. Returns `arr`.

(array/join arr & parts)

Join `parts`, a variable number of arrays and tuples, into the first argument `arr` which must be an array. Returns `arr`.

(array/new capacity)

Creates and returns a new empty array with a pre-allocated capacity. The same as `array` but can be more efficient if the maximum size is known.

(def arr (array/new 100)) # -> @[]

# Now we can fill up the array without triggering a resize
(for i 0 100
  (put arr i i))

(array/new-filled n &opt val)

Creates and returns a new array of `n` values, all set to `val`, which defaults to nil.

(array/peek arr)

Returns the last value of an array `arr`. Does not modify `arr`.

(array/pop arr)

Remove and return the last value of an array `arr`. If `arr` is empty, returns nil. Modifies `arr`.

(array/push arr & xs)

Push all the values of `xs` to the end of an array `arr`. Returns `arr`.

(array/remove arr at &opt n)

Remove up to `n` values starting at index `at` in array `arr`. `at` can index from the end of the array with a negative index, and `n` must be a non-negative integer. By default `n` is 1. Returns `arr`.

(array/slice ind &opt start end)

Same as `tuple/slice`, but returns an array.

# using non-negative `start` and `end` arguments
(array/slice @[:a :b :c] 0 2) # -> @[:a :b]
(array/slice @[:a :b :c] 1 3) # -> @[:b :c]

# only non-negative `start` argument
(array/slice @[:a :b :c] 0) # -> @[:a :b :c]
(array/slice @[:a :b :c] 1) # -> @[:b :c]
(array/slice @[:a :b :c] 3) # -> @[]

# errors since `start` is out of bounds
(array/slice @[:a :b :c] 4)

# not using `start` / `end` duplicates array
(array/slice @[:a :b :c]) # -> @[:a :b :c]

# only negative `start` argument
(array/slice @[:a :b :c] -1) # -> @[]
(array/slice @[:a :b :c] -2) # -> @[:c]
(array/slice @[:a :b :c] -4) # -> @[:a :b :c]

# errors since `start` is out of bounds
(array/slice @[:a :b :c] -5)

# both `start` and `end` negative
(array/slice @[:a :b :c] -4 -1) # -> @[:a :b :c]
(array/slice @[:a :b :c] -4 -3) # -> @[:a]
(array/slice @[:a :b :c] -4 -4) # -> @[]

# errors since `end` is out of bounds
(array/slice @[:a :b :c] -4 -5)

(array/trim arr)

Set the backing capacity of an array `arr` to its current length. Returns `arr`.

(array/weak capacity)

Creates and returns a new empty array with a pre-allocated capacity and support for weak references. Similar to `array/new`.