Array

is the indexable collection data structure.

Its literal uses brackets, so an array of integers would look like this: [1 2 3]. It provides both a functional and an imperative API, and is one of the core data structures of Carp. It is heap-allocated, for a stack-allocated variant you might want to check out StaticArray.

=

defn

(Fn [(Ref (Array a) b), (Ref (Array a) b)] Bool) 

                        (= a b)

compares two arrays.

all?

defn

(Fn [(Ref (Fn [(Ref a b)] Bool c) d), (Ref (Array a) b)] Bool) 

                        (all? f a)

checks whether all of the elements in a match the function f.

allocate

template

(Fn [Int] (Array a))

allocates an uninitialized array. You can initialize members using aset-uninitialized.

any?

defn

(Fn [(Ref (Fn [(Ref a b)] Bool c) d), (Ref (Array a) b)] Bool) 

                        (any? f a)

checks whether any of the elements in a match the function f.

aset

template

(Fn [(Array a), Int, a] (Array a))

sets an array element at the index n to a new value.

aset!

template

(Fn [(Ref (Array a) b), Int, a] ())

sets an array element at the index n to a new value in place.

aset-uninitialized!

template

(Fn [(Ref (Array a) b), Int, a] ())

sets an uninitialized array member. The old member will not be deleted.

aupdate

defn

(Fn [(Array a), Int, (Ref (Fn [a] a b) c)] (Array a)) 

                        (aupdate a i f)

transmutes (i.e. updates) the element at index i of an array a using the function f.

aupdate!

defn

(Fn [(Ref (Array a) b), Int, (Ref (Fn [a] a c) d)] ()) 

                        (aupdate! a i f)

transmutes (i.e. updates) the element at index i of an array a using the function f in place.

concat

defn

(Fn [(Ref (Array (Array a)) b)] (Array a)) 

                        (concat xs)

returns a new array which is the concatenation of the provided nested array xs.

contains?

defn

(Fn [(Ref (Array a) b), (Ref a b)] Bool) 

                        (contains? arr el)

checks wether an element exists in the array.

copy

template

(Fn [(Ref (Array a) b)] (Array a))

copies an array.

copy-filter

defn

(Fn [(Ref (Fn [(Ref a b)] Bool c) d), (Ref (Array a) e)] (Array a)) 

                        (copy-filter f a)

filters the elements in an array.

It will create a copy. If you want to avoid that, consider using endo-filter instead.

copy-map

defn

(Fn [(Ref (Fn [(Ref a b)] c d) e), (Ref (Array a) b)] (Array c)) 

                        (copy-map f a)

maps over an array a using the function f.

This function copies the array. If you don’t want that, use endo-map.

delete

template

(Fn [(Array a)] ())

deletes an array. This function should usually not be called manually.

element-count

defn

(Fn [(Ref (Array a) b), (Ref a b)] Int) 

                        (element-count a e)

counts the occurrences of element e in an array.

empty?

defn

(Fn [(Ref (Array a) b)] Bool) 

                        (empty? a)

checks whether the array a is empty.

endo-filter

template

(Fn [(Ref (Fn [(Ref a b)] Bool c) d), (Array a)] (Array a))

filters array members using a function. This function takes ownership.

endo-map

template

(Fn [(Ref (Fn [a] a b) c), (Array a)] (Array a))

applies a function f to an array a. The type of the elements cannot change.

endo-scan

defn

(Fn [(Ref (Fn [(Ref a b), (Ref a c)] a d) e), (Array a)] (Array a)) 

                        (endo-scan f xs)

Like Array.scan, but uses the first element of the array as the starting value. Also does not create a new array, but reuses the initial one instead (by taking ownership over xs.)

For example, an endo-scan using Int.+ over the array [1 1 1 1 1] will return [1 2 3 4 5]

enumerated

defn

(Fn [(Ref (Array a) b)] (Array (Pair Int a))) 

                        (enumerated xs)

creates a new array of Pairs where the first position is the index and the second position is the element from the original array xs.

find

defn

(Fn [(Ref (Fn [(Ref a b)] Bool c) d), (Ref (Array a) b)] (Maybe a)) 

                        (find f a)

finds an element in a that matches the function f and wraps it in a Just.

If it doesn’t find an element, Nothing will be returned.

find-index

defn

(Fn [(Ref (Fn [(Ref a b)] Bool c) d), (Ref (Array a) b)] (Maybe Int)) 

                        (find-index f a)

finds the index of the first element in a that matches the function f and wraps it in a Just.

If it doesn’t find an index, Nothing will be returned.

first

defn

(Fn [(Ref (Array a) b)] (Maybe a)) 

                        (first a)

takes the first element of an array and returns a Just.

Returns Nothing if the array is empty.

from-static

defn

(Fn [(Ref (StaticArray a) b)] (Array a)) 

                        (from-static sarr)

Turns a StaticArray into an Array. Copies elements.

index-of

defn

(Fn [(Ref (Array a) b), (Ref a b)] (Maybe Int)) 

                        (index-of a e)

gets the index of element e in an array and wraps it on a Just.

If the element is not found, returns Nothing

last

defn

(Fn [(Ref (Array a) b)] (Maybe a)) 

                        (last a)

takes the last element of an array and returns a Just.

Returns Nothing if the array is empty.

length

template

(Fn [(Ref (Array a) b)] Int)

gets the length of the array.

map-reduce

defn

(Fn [(Ref (Fn [(Ref a b), (Ref c d)] (Pair a e) f) g), a, (Ref (Array c) d)] (Pair a (Array e))) 

                        (map-reduce f acc a)

reduces an array a by invoking the function f on each element, while keeping an accumulator and a list.

Returns a Pair where the first element is the mapped array and the second one is the final accumulator.

The function f receives two arguments: the first one is the accumulator, and the second one is the element. f must return (Pair accumulator result).

Example:

(map-reduce &(fn [acc x] (Pair.init (+ @x @acc) (* @x 2))) 0 &[1 2 3])
; => (Pair 6 [2 4 6])

maximum

defn

(Fn [(Ref (Array a) b)] (Maybe a)) 

                        (maximum xs)

gets the maximum in an array (elements must support <) and wraps it in a Just.

If the array is empty, it returns Nothing.

minimum

defn

(Fn [(Ref (Array a) b)] (Maybe a)) 

                        (minimum xs)

gets the minimum in an array (elements must support >) and wraps it in a Just.

If the array is empty, returns Nothing

nth

defn

(Fn [(Ref (Array a) b), Int] (Maybe a)) 

                        (nth xs index)

gets a reference to the nth element from an array arr wrapped on a Maybe.

If the index is out of bounds, return Maybe.Nothing

partition

defn

(Fn [(Ref (Array a) b), Int] (Array (Array a))) 

                        (partition arr n)

Partitions an array arr into an array of arrays of length n sequentially filled with the arr's original values.

This function will fill partitions until `arr` is exhuasted.

If `n` is greater than or equal to the length of `arr`, the result of this
function is an array containing a single array of length `n`.

For example:

```clojure
(Array.partition &[1 2 3 4] 2)
=> [[1 2] [3 4]]
(Array.partition &[1 2 3 4] 3)
=> [[1 2 3] [4]]
(Array.partition &[1 2 3 4] 6)
=> [[1 2 3 4]]
```

pop-back

template

(Fn [(Array a)] (Array a))

removes the last element of an array and returns the new array.

pop-back!

template

(Fn [(Ref (Array a) b)] a)

removes an element value from the end of an array a in-place and returns it.

predicate-count

defn

(Fn [(Ref (Array a) b), (Ref (Fn [(Ref a b)] Bool c) d)] Int) 

                        (predicate-count a pred)

counts the number of elements satisfying the predicate function pred in an array.

prefix

defn

(Fn [(Ref a b), Int] a) 

                        (prefix xs end-index)

gets a prefix array to end-index.

prn

defn

(Fn [(Ref (Array a) b)] String) 

                        (prn x)

push-back

template

(Fn [(Array a), a] (Array a))

adds an element value to the end of an array a.

push-back!

template

(Fn [(Ref (Array a) b), a] ())

adds an element value to the end of an array a in-place.

range

defn

(Fn [a, a, a] (Result (Array a) String)) 

                        (range start end step)

creates an array from start to end with step between them (the elements must support <, <=, >=, and to-int).

It returns a Result.Success if the input was right, and a Result.Error if the input given was wrong, containing an error message.

range-or-default

defn

(Fn [a, a, a] (Array a)) 

                        (range-or-default start end step)

is a version of range that returns an empty array on failure.

raw

template

(Fn [(Array a)] (Ptr a))

returns an array a as a raw pointer—useful for interacting with C.

reduce

defn

(Fn [(Ref (Fn [a, (Ref b c)] a d) e), a, (Ref (Array b) c)] a) 

                        (reduce f x xs)

will reduce an array xs into a single value using a function f that takes the reduction thus far and the next value. The initial reduction value is x.

As an example, consider this definition of sum based on reduce:

(defn sum [x]
  (reduce &(fn [x y] (+ x @y)) 0 x))

It will sum the previous sum with each new value, starting at 0.

remove

defn

(Fn [(Ref a b), (Array a)] (Array a)) 

                        (remove el arr)

removes all occurrences of the element el in the array arr, in place.

remove-nth

defn

(Fn [Int, (Array a)] (Array a)) 

                        (remove-nth i arr)

removes element at index idx from the array arr.

repeat

defn

(Fn [Int, (Ref (Fn [] a b) c)] (Array a)) 

                        (repeat n f)

repeats the function f n times and stores the results in an array.

repeat-indexed

defn

(Fn [Int, (Fn [Int] a b)] (Array a)) 

                        (repeat-indexed n f)

repeats function f n times and stores the results in an array.

This is similar to repeat, but the function f will be supplied with the index of the element.

replicate

defn

(Fn [Int, (Ref a b)] (Array a)) 

                        (replicate n e)

repeats element e n times and stores the results in an array.

rest

defn

(Fn [(Ref (Array a) b)] (Array a)) 

                        (rest xs)

gets all but the first element from the array.

reverse

defn

(Fn [(Array a)] (Array a)) 

                        (reverse a)

reverses an array.

scan

defn

(Fn [(Ref (Fn [(Ref a b), (Ref c d)] a e) f), a, (Ref (Array c) d)] (Array a)) 

                        (scan f x xs)

Similar to Array.reduce, but instead returns an array with the starting element, and then all intermediate values.

For example, a scan using Int.+ over the array [1 1 1 1 1] (starting at 0) will return [0 1 2 3 4 5].

slice

defn

(Fn [(Ref (Array a) b), Int, Int] (Array a)) 

                        (slice xs start-index end-index)

gets a subarray from start-index to end-index.

sort

defn

(Fn [(Array a)] (Array a)) 

                        (sort arr)

Perform an in-place heapsort of a given owned array.

sort!

defn

(Fn [(Ref (Array a) b)] ()) 

                        (sort! arr)

Perform an in-place heapsort of a given array.

sort-by

defn

(Fn [(Array a), (Ref (Fn [(Ref a b), (Ref a b)] Bool c) d)] (Array a)) 

                        (sort-by arr f)

Perform an in-place heapsort of a given owned array by a comparison function.

sort-by!

defn

(Fn [(Ref (Array a) b), (Ref (Fn [(Ref a b), (Ref a b)] Bool c) d)] ()) 

                        (sort-by! arr f)

Perform an in-place heapsort of a given array by a comparison function.

sorted

defn

(Fn [(Ref (Array a) b)] (Array a)) 

                        (sorted arr)

Perform a heapsort in a new copy of given array.

sorted-by

defn

(Fn [(Ref (Array a) b), (Ref (Fn [(Ref a c), (Ref a c)] Bool d) e)] (Array a)) 

                        (sorted-by arr f)

Perform a heapsort in a new copy of given array by a comparison function.

str

template

(Fn [(Ref (Array a) b)] String)

converts an array to a string.

suffix

defn

(Fn [(Ref (Array a) b), Int] (Array a)) 

                        (suffix xs start-index)

gets a suffix array from start-index.

sum

defn

(Fn [(Ref (Array a) b)] a) 

                        (sum xs)

sums an array (elements must support + and zero).

sum-length

defn

(Fn [(Ref (Array (Array a)) b)] Int) 

                        (sum-length xs)

returns the sum of lengths from a nested array xs.

swap

defn

(Fn [(Array a), Int, Int] (Array a)) 

                        (swap a i j)

swaps the indices i and j of an array a.

swap!

defn

(Fn [(Ref (Array a) b), Int, Int] ()) 

                        (swap! a i j)

swaps the indices i and j of an array a in place.

unreduce

defn

(Fn [a, (Ref (Fn [a] Bool b) c), (Ref (Fn [a] a b) d)] (Array a)) 

                        (unreduce start test step)

creates an array by producing values using step until they no longer satisfy test. The initial value is start.

Example:

; if we didn’t have Array.range, we could define it like this:
(defn range [start end step]
  (unreduce start &(fn [x] (< x (+ step end))) &(fn [x] (+ x step)))
)

unsafe-first

defn

(Fn [(Ref (Array a) b)] (Ref a b)) 

                        (unsafe-first a)

takes the first element of an array.

Generates a runtime error if the array is empty.

unsafe-last

defn

(Fn [(Ref (Array a) b)] (Ref a b)) 

                        (unsafe-last a)

takes the last element of an array.

Generates a runtime error if the array is empty.

unsafe-nth

template

(Fn [(Ref (Array a) b), Int] (Ref a b))

gets a reference to the nth element from an array a.

unsafe-nth-value

template

(Fn [(Ref (Array a) b), Int] a)

returns the value at index i of an array a (just like unsafe-nth) but does not take its reference, and does not copy the value. Should only be used for optimizations and when you know what you're doing, circumvents the borrow checker!

unsafe-raw

template

(Fn [(Ref (Array a) b)] (Ptr a))

returns an array a as a raw pointer—useful for interacting with C.

zero

defn

(Fn [] (Array a)) 

                        (zero)

returns the empty array.

zip

defn

(Fn [(Ref (Fn [(Ref a b), (Ref c d)] e f) g), (Ref (Array a) b), (Ref (Array c) d)] (Array e)) 

                        (zip f a b)

maps over two arrays using a function f that takes two arguments. It will produces a new array with the length of the shorter input.

The trailing elements of the longer array will be discarded.