(std array)

Reference

Overview

Whole-array operations on numbers, with the CPU’s vector instructions where it has them.

(import (std array))

(def xs (make-array 1000 #:fill 1.5))
(array-sum xs)                  ; 1500
(array-dot xs xs)               ; 2250
(array-scale! xs 2.0)           ; every element is now 3
(array-index-of xs 3.0)         ; 0

Each function is one loop in the runtime. When the element type is a primitive number (int, long, double, byte and the other fixed-size integers and floats), the loop uses System.Numerics.Vector: one instruction works on as many elements as a vector register holds. With AVX2 that is 4 doubles, 8 ints or 32 bytes. The elements that do not fill a whole register go through an ordinary loop at the end. Other numbers, such as BigInteger and decimal, go through the ordinary loop only.

Order of additions. array-sum and array-dot add lane by lane and add the lanes at the end. At an integer type the result is the same as a left fold, because addition wraps and the order does not matter. At double the order is different, so the last bits of the result can differ from (foldl + 0.0 xs).

Equality. array-count and array-index-of use the number’s ==, as = does. NaN matches nothing, and -0.0 matches 0.0.

Native AOT. An ahead-of-time build targets a baseline x86-64 CPU unless the project says otherwise, so a vector there has 128 bits. Set (aot-cpu "native") in the manifest to build for the CPU of the machine that builds.

See also: array-sum, array-dot, array-min, array-max, array-add!, array-scale!, array-count, array-index-of, array-fill!

Reference

Functions

Functions

array-sum

function ↑ Functions

(: array-sum (-> (Array %a) %a))
(array-sum a)

Returns the sum of the elements.

a
The array.
returns
The sum. Zero for an empty array.
(array-sum (make-array 4 #:fill 2))   ; 8

array-dot

function ↑ Functions

(: array-dot (-> (Array %a) (Array %a) %a))
(array-dot a b)

Returns the sum of the products of the elements at the same index.

a
The first array.
b
The second array. It must have the same length as a.
returns
The dot product. Zero for empty arrays.

Raises ArgumentException when the lengths differ.

array-min

function ↑ Functions

(: array-min (-> (Array %a) %a))
(array-min a)

Returns the least element.

a
The array. It must not be empty.
returns
The least element, as min picks it.

Raises InvalidOperationException for an empty array. At double a NaN anywhere gives NaN, and -0.0 is less than 0.0, as min says.

array-max

function ↑ Functions

(: array-max (-> (Array %a) %a))
(array-max a)

Returns the greatest element.

a
The array. It must not be empty.
returns
The greatest element, as max picks it.

Raises InvalidOperationException for an empty array. At double a NaN anywhere gives NaN.

array-add!

function ↑ Functions

(: array-add! (-> (Array %a) (Array %a) void))
(array-add! dst src)

Adds each element of src to the element of dst at the same index.

dst
The array to change.
src
The array to add. It must have the same length as dst.

Raises ArgumentException when the lengths differ. dst and src can be the same array, which doubles every element.

array-scale!

function ↑ Functions

(: array-scale! (-> (Array %a) %a void))
(array-scale! a k)

Multiplies each element by k.

a
The array to change.
k
The factor.

array-count

function ↑ Functions

(: array-count (-> (Array %a) %a int))
(array-count a x)

Returns how many elements are equal to x.

a
The array.
x
The value to count.
returns
The number of elements = to x.

array-index-of

function ↑ Functions

(: array-index-of (-> (Array %a) %a int))
(array-index-of a x)

Returns the index of the first element equal to x.

a
The array.
x
The value to find.
returns
The index, or -1 when no element is = to x.

array-fill!

function ↑ Functions

(: array-fill! (-> (Array %a) %a void))
(array-fill! a x)

Writes x to every element.

a
The array to change. Any element type.
x
The value to write.