tur/numvec

(defopaque ^affine F64Vec : int)

a fixed-length, unboxed array of 64-bit floats (float).

Opaque handle to a struct { int64_t len; double *data; void *raw; }. ^affine: freed at scope exit by its Drop instance. Use f64vec-new or f64vec-of to make one.

Since: Phase N0

(defopaque F64View : int)

a view of a F64Vec's elements: the data pointer, for a store loop.

Made by f64vec-view, read and written by f64vec-view-ref / f64vec-view-set!. Not owned and not affine: it frees nothing, and it is valid exactly as long as the array it came from (an array never resizes, so its data never moves).

Since: Phase N2

(f64vec-new [n : int init : float])

allocate a F64Vec of n elements, every one init.

(let [v (f64vec-new 4 7.1)]
  (f64vec-ref v 2))   ; => 7.1

Since: Phase N0

(f64vec-of [& xs])

a F64Vec holding the given elements, in order.

(let [v (f64vec-of 1.5 2.5)]
  (f64vec-len v))   ; => 2

Since: Phase N0

(f64vec-free [v : F64Vec])

release a F64Vec now, consuming it.

Rarely needed: a let-bound F64Vec is freed at scope exit. Call it to release a large array before the scope ends.

(f64vec-free v)

Since: Phase N0

(definstance Drop [F64Vec])

free the array when a bound F64Vec dies unmoved.

(f64vec-len [^borrow v : F64Vec])

the element count of a F64Vec.

(let [v (f64vec-new 8 7.1)]
  (f64vec-len v))   ; => 8

Since: Phase N0

(f64vec-ref [^borrow v : F64Vec i : int])

the element at index i (bounds-checked).

(let [v (f64vec-of 1.5 2.5)]
  (f64vec-ref v 1))   ; => 2.5

Since: Phase N0

(f64vec-set! [^borrow v : F64Vec i : int x : float])

store x at index i (bounds-checked).

(f64vec-set! v 0 7.1)

Since: Phase N0

(f64vec-copy [^borrow v : F64Vec])

a fresh F64Vec with the same elements.

(let [c (f64vec-copy v)] (f64vec-set! c 0 7.1))   ; v is unchanged

Since: Phase N0

(f64vec->vec-go__ [^borrow v : F64Vec out : (Vec float) i : int n : int] : (Vec float))

internal: push v[i..n) onto out.

(f64vec->vec [^borrow v : F64Vec] : (Vec float))

copy a F64Vec into a fresh (Vec float).

(let [a (f64vec-of 1.5 2.5)
      v (f64vec->vec a)]
  (vec-len v))   ; => 2

Since: Phase N0

(vec->f64vec-go__ [^borrow out : F64Vec ^borrow src : (Vec float) i : int n : int] : nil)

internal: store src[i..n) into out.

(vec->f64vec [^borrow src : (Vec float)] : F64Vec)

copy a (Vec float) into a fresh F64Vec.

(let [v (vec-of 1.5 2.5)
      a (vec->f64vec v)]
  (f64vec-len a))   ; => 2

Since: Phase N0

(f64vec-show-loop__ [^borrow v : F64Vec i : int n : int b : StringBuilder] : StringBuilder)

internal: push "e0 e1 ..." onto the builder.

(f64vec-show [^borrow v : F64Vec] : String)

render a F64Vec as an owned "#f64vec[a b c]" String.

(let [v (f64vec-of 1.5 2.5)]
  (f64vec-show v))   ; => String "#f64vec[1.5 2.5]"

Since: Phase N0

(f64vec-fill! [^borrow v : F64Vec x : float])

store x in every slot.

(f64vec-fill! v 1.5)

Since: Phase N1

(f64vec-copy! [^borrow dst : F64Vec ^borrow src : F64Vec])

copy src's elements into dst (same length, or a panic).

(f64vec-copy! dst src)

Since: Phase N1

(f64vec-scale! [^borrow v : F64Vec s : float])

multiply every element by s, in place.

Integer arithmetic wraps.

(f64vec-scale! v 2.5)

Since: Phase N1

(f64vec-add! [^borrow dst : F64Vec ^borrow src : F64Vec])

dst[i] += src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(f64vec-add! y x)

Since: Phase N1

(f64vec-axpy! [^borrow dst : F64Vec s : float ^borrow src : F64Vec])

dst[i] += s * src[i] for every i (same length, or a panic).

Integer arithmetic wraps; the multiply and the add are not fused.

(f64vec-axpy! y 2.5 x)

Since: Phase N1

(f64vec-sub! [^borrow dst : F64Vec ^borrow src : F64Vec])

dst[i] -= src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(f64vec-sub! y x)

Since: Phase N1

(f64vec-mul! [^borrow dst : F64Vec ^borrow src : F64Vec])

dst[i] *= src[i] for every i (same length, or a panic).

Element-wise, not a dot product. Integer arithmetic wraps; dst and src may be the same array.

(f64vec-mul! y x)

Since: Phase N1

(f64vec-add-scalar! [^borrow v : F64Vec s : float])

add s to every element, in place.

Integer arithmetic wraps.

(f64vec-add-scalar! v 2.5)

Since: Phase N1

(f64vec-sum [^borrow v : F64Vec])

the sum of the elements.

A float sum is computed in eight interleaved partial sums (lane k takes the elements i with i mod 8 = k), combined in one fixed tree: the same answer on every engine and machine, and vectorizable without -ffast-math. It can differ in the last bits from -sum-ordered, the left-to-right sum. An integer sum wraps modulo 2^64; a narrow element is widened to int first.

(let [v (f64vec-of 1.5 2.5)] (f64vec-sum v))

Since: Phase N1

(f64vec-sum-ordered [^borrow v : F64Vec])

the strict left-to-right sum of the elements.

(let [v (f64vec-of 1.5 2.5)] (f64vec-sum-ordered v))

Since: Phase N1

(f64vec-dot [^borrow a : F64Vec ^borrow b : F64Vec])

the dot product of two arrays (same length, or a panic).

Floats use the same eight-lane order as -sum. Integers wrap modulo 2^64; an int32 product is formed in 64 bits.

(let [a (f64vec-of 1.5 2.5) b (f64vec-of 2.5 1.5)] (f64vec-dot a b))

Since: Phase N1

(f64vec-min [^borrow v : F64Vec])

the smallest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (f64vec-of 1.5 2.5)] (f64vec-min v))   ; => 1.5

Since: Phase N1

(f64vec-max [^borrow v : F64Vec])

the largest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (f64vec-of 1.5 2.5)] (f64vec-max v))   ; => 2.5

Since: Phase N1

(f64vec-ref-unchecked [^borrow v : F64Vec i : int])

the element at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The loop macros (-for, -fold, ...) use it where they have already checked the index. Its body calls nothing, so a call to it carries no panic check, and a loop of such calls can vectorize.

(unsafe (f64vec-ref-unchecked v 0))

Since: Phase N2

(f64vec-set-unchecked! [^borrow v : F64Vec i : int x : float])

store x at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE (see the module header).

(unsafe (f64vec-set-unchecked! v 0 1.5))

Since: Phase N2

(f64vec-view [^borrow v : F64Vec])

a view of v's elements, for a loop that stores into it.

#fx{Unsafe}: nothing ties the view to the array, so a view used after the array is freed reads freed memory. Why it exists: a store through the array (-set-unchecked!) re-reads the header's data pointer, which the store might have overwritten as far as the C compiler knows, so the loop does not vectorize; a view is that pointer, read once. -build and -map! store through one; reach for it directly only for a store loop they do not cover.

(let [v (f64vec-of 1.5 2.5) w (unsafe (f64vec-view v))] (unsafe (f64vec-view-ref w 1)))   ; => 2.5

Since: Phase N2

(f64vec-view-ref [w : F64View i : int])

the element at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The interpreter checks the index anyway, as it does for -ref-unchecked.

(unsafe (f64vec-view-ref w 0))

Since: Phase N2

(f64vec-view-set! [w : F64View i : int x : float])

store x at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE. The interpreter checks the index anyway.

(unsafe (f64vec-view-set! w 0 1.5))

Since: Phase N2

(f64vec-for [bv & body])

run body once per element of one or two F64Vecs.

(for [x v] body...) binds x to each element of v in order; (for [x v y w] body...) walks v and w together (same length, or a panic before the first pass). No index is in scope, so none can be wrong: the reads are f64vec-ref-unchecked, the body sees plain elements, and the loop carries no bounds check or panic test -- gcc can vectorize it at -O3. An array argument that is not a name is evaluated once, and freed after.

(let [v (f64vec-of 1.5 2.5)] (f64vec-for [x v] (println x)))

Since: Phase N2

(f64vec-for-index [bv & body])

run body once per element, with its index.

(for-index [i x v] body...) binds i (read-only) and x = v[i].

(let [v (f64vec-of 1.5 2.5)] (f64vec-for-index [i x v] (println i)))

Since: Phase N2

(f64vec-fold [bv body])

fold the elements of a F64Vec into an accumulator.

(fold [acc init x v] body): acc starts at init, and for each element x in order becomes the value of body (which sees acc and x). The result is the final acc. A float sum written this way is the strict left fold, so gcc keeps it scalar; f64vec-sum is the vectorized one.

(let [v (f64vec-of 1.5 2.5)] (f64vec-fold [n 0 x v] (+ n 1)))   ; => 2

Since: Phase N2

(f64vec-build [n bv expr])

a fresh F64Vec of n elements, element i the value of expr.

(build n [i] expr), after Racket's for/flvector: i is bound to each index in turn, and expr runs outside any unsafe. The stores go through a view (f64vec-view), so the loop vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc.

(let [v (f64vec-build 3 [i] 1.5)] (f64vec-len v))   ; => 3

Since: Phase N2

(f64vec-map! [dst bv expr])

store expr into dst[i] for every i, x bound to src[i].

(map! dst [x src] expr) stores into each slot of dst the value of expr with x bound to the element of src at the same index; (map! dst [x a y b] expr) walks two sources together. dst may be one of the sources: (map! v [x v] {x * 2}) maps in place. Every array has the same length, or a panic before the first element. The loop reads and stores through views (f64vec-view), so it vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc. expr runs outside any unsafe; an array argument that is not a name is evaluated once, and freed after the loop.

(let [v (f64vec-of 1.5 2.5)] (f64vec-map! v [x v] x) (f64vec-ref v 1))   ; => 2.5

Since: Phase N2

(f64vec-same-len__ [^borrow a : F64Vec ^borrow b : F64Vec])

internal: the common length of two arrays, or a panic.

(defopaque ^affine F32Vec : int)

a fixed-length, unboxed array of 32-bit floats (float32).

Opaque handle to a struct { int64_t len; float *data; void *raw; }. ^affine: freed at scope exit by its Drop instance. Use f32vec-new or f32vec-of to make one.

Since: Phase N0

(defopaque F32View : int)

a view of a F32Vec's elements: the data pointer, for a store loop.

Made by f32vec-view, read and written by f32vec-view-ref / f32vec-view-set!. Not owned and not affine: it frees nothing, and it is valid exactly as long as the array it came from (an array never resizes, so its data never moves).

Since: Phase N2

(f32vec-new [n : int init : float32])

allocate a F32Vec of n elements, every one init.

(let [v (f32vec-new 4 (:: 3.25 float32))]
  (f32vec-ref v 2))   ; => (:: 3.25 float32)

Since: Phase N0

(f32vec-of [& xs])

a F32Vec holding the given elements, in order.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))]
  (f32vec-len v))   ; => 2

Since: Phase N0

(f32vec-free [v : F32Vec])

release a F32Vec now, consuming it.

Rarely needed: a let-bound F32Vec is freed at scope exit. Call it to release a large array before the scope ends.

(f32vec-free v)

Since: Phase N0

(definstance Drop [F32Vec])

free the array when a bound F32Vec dies unmoved.

(f32vec-len [^borrow v : F32Vec])

the element count of a F32Vec.

(let [v (f32vec-new 8 (:: 3.25 float32))]
  (f32vec-len v))   ; => 8

Since: Phase N0

(f32vec-ref [^borrow v : F32Vec i : int])

the element at index i (bounds-checked).

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))]
  (f32vec-ref v 1))   ; => (:: 2.5 float32)

Since: Phase N0

(f32vec-set! [^borrow v : F32Vec i : int x : float32])

store x at index i (bounds-checked).

(f32vec-set! v 0 (:: 3.25 float32))

Since: Phase N0

(f32vec-copy [^borrow v : F32Vec])

a fresh F32Vec with the same elements.

(let [c (f32vec-copy v)] (f32vec-set! c 0 (:: 3.25 float32)))   ; v is unchanged

Since: Phase N0

(f32vec->vec-go__ [^borrow v : F32Vec out : (Vec float32) i : int n : int] : (Vec float32))

internal: push v[i..n) onto out.

(f32vec->vec [^borrow v : F32Vec] : (Vec float32))

copy a F32Vec into a fresh (Vec float32).

(let [a (f32vec-of (:: 1.5 float32) (:: 2.5 float32))
      v (f32vec->vec a)]
  (vec-len v))   ; => 2

Since: Phase N0

(vec->f32vec-go__ [^borrow out : F32Vec ^borrow src : (Vec float32) i : int n : int] : nil)

internal: store src[i..n) into out.

(vec->f32vec [^borrow src : (Vec float32)] : F32Vec)

copy a (Vec float32) into a fresh F32Vec.

(let [v (vec-of (:: 1.5 float32) (:: 2.5 float32))
      a (vec->f32vec v)]
  (f32vec-len a))   ; => 2

Since: Phase N0

(f32vec-show-loop__ [^borrow v : F32Vec i : int n : int b : StringBuilder] : StringBuilder)

internal: push "e0 e1 ..." onto the builder.

(f32vec-show [^borrow v : F32Vec] : String)

render a F32Vec as an owned "#f32vec[a b c]" String.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))]
  (f32vec-show v))   ; => String "#f32vec[1.5 2.5]"

Since: Phase N0

(f32vec-fill! [^borrow v : F32Vec x : float32])

store x in every slot.

(f32vec-fill! v (:: 1.5 float32))

Since: Phase N1

(f32vec-copy! [^borrow dst : F32Vec ^borrow src : F32Vec])

copy src's elements into dst (same length, or a panic).

(f32vec-copy! dst src)

Since: Phase N1

(f32vec-scale! [^borrow v : F32Vec s : float32])

multiply every element by s, in place.

Integer arithmetic wraps.

(f32vec-scale! v (:: 2.5 float32))

Since: Phase N1

(f32vec-add! [^borrow dst : F32Vec ^borrow src : F32Vec])

dst[i] += src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(f32vec-add! y x)

Since: Phase N1

(f32vec-axpy! [^borrow dst : F32Vec s : float32 ^borrow src : F32Vec])

dst[i] += s * src[i] for every i (same length, or a panic).

Integer arithmetic wraps; the multiply and the add are not fused.

(f32vec-axpy! y (:: 2.5 float32) x)

Since: Phase N1

(f32vec-sub! [^borrow dst : F32Vec ^borrow src : F32Vec])

dst[i] -= src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(f32vec-sub! y x)

Since: Phase N1

(f32vec-mul! [^borrow dst : F32Vec ^borrow src : F32Vec])

dst[i] *= src[i] for every i (same length, or a panic).

Element-wise, not a dot product. Integer arithmetic wraps; dst and src may be the same array.

(f32vec-mul! y x)

Since: Phase N1

(f32vec-add-scalar! [^borrow v : F32Vec s : float32])

add s to every element, in place.

Integer arithmetic wraps.

(f32vec-add-scalar! v (:: 2.5 float32))

Since: Phase N1

(f32vec-sum [^borrow v : F32Vec])

the sum of the elements.

A float sum is computed in eight interleaved partial sums (lane k takes the elements i with i mod 8 = k), combined in one fixed tree: the same answer on every engine and machine, and vectorizable without -ffast-math. It can differ in the last bits from -sum-ordered, the left-to-right sum. An integer sum wraps modulo 2^64; a narrow element is widened to int first.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))] (f32vec-sum v))

Since: Phase N1

(f32vec-sum-ordered [^borrow v : F32Vec])

the strict left-to-right sum of the elements.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))] (f32vec-sum-ordered v))

Since: Phase N1

(f32vec-dot [^borrow a : F32Vec ^borrow b : F32Vec])

the dot product of two arrays (same length, or a panic).

Floats use the same eight-lane order as -sum. Integers wrap modulo 2^64; an int32 product is formed in 64 bits.

(let [a (f32vec-of (:: 1.5 float32) (:: 2.5 float32)) b (f32vec-of (:: 2.5 float32) (:: 1.5 float32))] (f32vec-dot a b))

Since: Phase N1

(f32vec-min [^borrow v : F32Vec])

the smallest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))] (f32vec-min v))   ; => (:: 1.5 float32)

Since: Phase N1

(f32vec-max [^borrow v : F32Vec])

the largest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))] (f32vec-max v))   ; => (:: 2.5 float32)

Since: Phase N1

(f32vec-ref-unchecked [^borrow v : F32Vec i : int])

the element at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The loop macros (-for, -fold, ...) use it where they have already checked the index. Its body calls nothing, so a call to it carries no panic check, and a loop of such calls can vectorize.

(unsafe (f32vec-ref-unchecked v 0))

Since: Phase N2

(f32vec-set-unchecked! [^borrow v : F32Vec i : int x : float32])

store x at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE (see the module header).

(unsafe (f32vec-set-unchecked! v 0 (:: 1.5 float32)))

Since: Phase N2

(f32vec-view [^borrow v : F32Vec])

a view of v's elements, for a loop that stores into it.

#fx{Unsafe}: nothing ties the view to the array, so a view used after the array is freed reads freed memory. Why it exists: a store through the array (-set-unchecked!) re-reads the header's data pointer, which the store might have overwritten as far as the C compiler knows, so the loop does not vectorize; a view is that pointer, read once. -build and -map! store through one; reach for it directly only for a store loop they do not cover.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32)) w (unsafe (f32vec-view v))] (unsafe (f32vec-view-ref w 1)))   ; => (:: 2.5 float32)

Since: Phase N2

(f32vec-view-ref [w : F32View i : int])

the element at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The interpreter checks the index anyway, as it does for -ref-unchecked.

(unsafe (f32vec-view-ref w 0))

Since: Phase N2

(f32vec-view-set! [w : F32View i : int x : float32])

store x at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE. The interpreter checks the index anyway.

(unsafe (f32vec-view-set! w 0 (:: 1.5 float32)))

Since: Phase N2

(f32vec-for [bv & body])

run body once per element of one or two F32Vecs.

(for [x v] body...) binds x to each element of v in order; (for [x v y w] body...) walks v and w together (same length, or a panic before the first pass). No index is in scope, so none can be wrong: the reads are f32vec-ref-unchecked, the body sees plain elements, and the loop carries no bounds check or panic test -- gcc can vectorize it at -O3. An array argument that is not a name is evaluated once, and freed after.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))] (f32vec-for [x v] (println x)))

Since: Phase N2

(f32vec-for-index [bv & body])

run body once per element, with its index.

(for-index [i x v] body...) binds i (read-only) and x = v[i].

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))] (f32vec-for-index [i x v] (println i)))

Since: Phase N2

(f32vec-fold [bv body])

fold the elements of a F32Vec into an accumulator.

(fold [acc init x v] body): acc starts at init, and for each element x in order becomes the value of body (which sees acc and x). The result is the final acc. A float sum written this way is the strict left fold, so gcc keeps it scalar; f32vec-sum is the vectorized one.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))] (f32vec-fold [n 0 x v] (+ n 1)))   ; => 2

Since: Phase N2

(f32vec-build [n bv expr])

a fresh F32Vec of n elements, element i the value of expr.

(build n [i] expr), after Racket's for/flvector: i is bound to each index in turn, and expr runs outside any unsafe. The stores go through a view (f32vec-view), so the loop vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc.

(let [v (f32vec-build 3 [i] (:: 1.5 float32))] (f32vec-len v))   ; => 3

Since: Phase N2

(f32vec-map! [dst bv expr])

store expr into dst[i] for every i, x bound to src[i].

(map! dst [x src] expr) stores into each slot of dst the value of expr with x bound to the element of src at the same index; (map! dst [x a y b] expr) walks two sources together. dst may be one of the sources: (map! v [x v] {x * 2}) maps in place. Every array has the same length, or a panic before the first element. The loop reads and stores through views (f32vec-view), so it vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc. expr runs outside any unsafe; an array argument that is not a name is evaluated once, and freed after the loop.

(let [v (f32vec-of (:: 1.5 float32) (:: 2.5 float32))] (f32vec-map! v [x v] x) (f32vec-ref v 1))   ; => (:: 2.5 float32)

Since: Phase N2

(f32vec-same-len__ [^borrow a : F32Vec ^borrow b : F32Vec])

internal: the common length of two arrays, or a panic.

(defopaque ^affine I64Vec : int)

a fixed-length, unboxed array of 64-bit integers (int).

Opaque handle to a struct { int64_t len; int64_t *data; void *raw; }. ^affine: freed at scope exit by its Drop instance. Use i64vec-new or i64vec-of to make one.

Since: Phase N0

(defopaque I64View : int)

a view of a I64Vec's elements: the data pointer, for a store loop.

Made by i64vec-view, read and written by i64vec-view-ref / i64vec-view-set!. Not owned and not affine: it frees nothing, and it is valid exactly as long as the array it came from (an array never resizes, so its data never moves).

Since: Phase N2

(i64vec-new [n : int init : int])

allocate a I64Vec of n elements, every one init.

(let [v (i64vec-new 4 7)]
  (i64vec-ref v 2))   ; => 7

Since: Phase N0

(i64vec-of [& xs])

a I64Vec holding the given elements, in order.

(let [v (i64vec-of 1 2)]
  (i64vec-len v))   ; => 2

Since: Phase N0

(i64vec-free [v : I64Vec])

release a I64Vec now, consuming it.

Rarely needed: a let-bound I64Vec is freed at scope exit. Call it to release a large array before the scope ends.

(i64vec-free v)

Since: Phase N0

(definstance Drop [I64Vec])

free the array when a bound I64Vec dies unmoved.

(i64vec-len [^borrow v : I64Vec])

the element count of a I64Vec.

(let [v (i64vec-new 8 7)]
  (i64vec-len v))   ; => 8

Since: Phase N0

(i64vec-ref [^borrow v : I64Vec i : int])

the element at index i (bounds-checked).

(let [v (i64vec-of 1 2)]
  (i64vec-ref v 1))   ; => 2

Since: Phase N0

(i64vec-set! [^borrow v : I64Vec i : int x : int])

store x at index i (bounds-checked).

(i64vec-set! v 0 7)

Since: Phase N0

(i64vec-copy [^borrow v : I64Vec])

a fresh I64Vec with the same elements.

(let [c (i64vec-copy v)] (i64vec-set! c 0 7))   ; v is unchanged

Since: Phase N0

(i64vec->vec-go__ [^borrow v : I64Vec out : (Vec int) i : int n : int] : (Vec int))

internal: push v[i..n) onto out.

(i64vec->vec [^borrow v : I64Vec] : (Vec int))

copy a I64Vec into a fresh (Vec int).

(let [a (i64vec-of 1 2)
      v (i64vec->vec a)]
  (vec-len v))   ; => 2

Since: Phase N0

(vec->i64vec-go__ [^borrow out : I64Vec ^borrow src : (Vec int) i : int n : int] : nil)

internal: store src[i..n) into out.

(vec->i64vec [^borrow src : (Vec int)] : I64Vec)

copy a (Vec int) into a fresh I64Vec.

(let [v (vec-of 1 2)
      a (vec->i64vec v)]
  (i64vec-len a))   ; => 2

Since: Phase N0

(i64vec-show-loop__ [^borrow v : I64Vec i : int n : int b : StringBuilder] : StringBuilder)

internal: push "e0 e1 ..." onto the builder.

(i64vec-show [^borrow v : I64Vec] : String)

render a I64Vec as an owned "#i64vec[a b c]" String.

(let [v (i64vec-of 1 2)]
  (i64vec-show v))   ; => String "#i64vec[1 2]"

Since: Phase N0

(i64vec-fill! [^borrow v : I64Vec x : int])

store x in every slot.

(i64vec-fill! v 1)

Since: Phase N1

(i64vec-copy! [^borrow dst : I64Vec ^borrow src : I64Vec])

copy src's elements into dst (same length, or a panic).

(i64vec-copy! dst src)

Since: Phase N1

(i64vec-scale! [^borrow v : I64Vec s : int])

multiply every element by s, in place.

Integer arithmetic wraps.

(i64vec-scale! v 2)

Since: Phase N1

(i64vec-add! [^borrow dst : I64Vec ^borrow src : I64Vec])

dst[i] += src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(i64vec-add! y x)

Since: Phase N1

(i64vec-axpy! [^borrow dst : I64Vec s : int ^borrow src : I64Vec])

dst[i] += s * src[i] for every i (same length, or a panic).

Integer arithmetic wraps; the multiply and the add are not fused.

(i64vec-axpy! y 2 x)

Since: Phase N1

(i64vec-sub! [^borrow dst : I64Vec ^borrow src : I64Vec])

dst[i] -= src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(i64vec-sub! y x)

Since: Phase N1

(i64vec-mul! [^borrow dst : I64Vec ^borrow src : I64Vec])

dst[i] *= src[i] for every i (same length, or a panic).

Element-wise, not a dot product. Integer arithmetic wraps; dst and src may be the same array.

(i64vec-mul! y x)

Since: Phase N1

(i64vec-add-scalar! [^borrow v : I64Vec s : int])

add s to every element, in place.

Integer arithmetic wraps.

(i64vec-add-scalar! v 2)

Since: Phase N1

(i64vec-sum [^borrow v : I64Vec])

the sum of the elements.

A float sum is computed in eight interleaved partial sums (lane k takes the elements i with i mod 8 = k), combined in one fixed tree: the same answer on every engine and machine, and vectorizable without -ffast-math. It can differ in the last bits from -sum-ordered, the left-to-right sum. An integer sum wraps modulo 2^64; a narrow element is widened to int first.

(let [v (i64vec-of 1 2)] (i64vec-sum v))

Since: Phase N1

(i64vec-dot [^borrow a : I64Vec ^borrow b : I64Vec])

the dot product of two arrays (same length, or a panic).

Floats use the same eight-lane order as -sum. Integers wrap modulo 2^64; an int32 product is formed in 64 bits.

(let [a (i64vec-of 1 2) b (i64vec-of 2 1)] (i64vec-dot a b))

Since: Phase N1

(i64vec-min [^borrow v : I64Vec])

the smallest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (i64vec-of 1 2)] (i64vec-min v))   ; => 1

Since: Phase N1

(i64vec-max [^borrow v : I64Vec])

the largest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (i64vec-of 1 2)] (i64vec-max v))   ; => 2

Since: Phase N1

(i64vec-ref-unchecked [^borrow v : I64Vec i : int])

the element at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The loop macros (-for, -fold, ...) use it where they have already checked the index. Its body calls nothing, so a call to it carries no panic check, and a loop of such calls can vectorize.

(unsafe (i64vec-ref-unchecked v 0))

Since: Phase N2

(i64vec-set-unchecked! [^borrow v : I64Vec i : int x : int])

store x at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE (see the module header).

(unsafe (i64vec-set-unchecked! v 0 1))

Since: Phase N2

(i64vec-view [^borrow v : I64Vec])

a view of v's elements, for a loop that stores into it.

#fx{Unsafe}: nothing ties the view to the array, so a view used after the array is freed reads freed memory. Why it exists: a store through the array (-set-unchecked!) re-reads the header's data pointer, which the store might have overwritten as far as the C compiler knows, so the loop does not vectorize; a view is that pointer, read once. -build and -map! store through one; reach for it directly only for a store loop they do not cover.

(let [v (i64vec-of 1 2) w (unsafe (i64vec-view v))] (unsafe (i64vec-view-ref w 1)))   ; => 2

Since: Phase N2

(i64vec-view-ref [w : I64View i : int])

the element at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The interpreter checks the index anyway, as it does for -ref-unchecked.

(unsafe (i64vec-view-ref w 0))

Since: Phase N2

(i64vec-view-set! [w : I64View i : int x : int])

store x at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE. The interpreter checks the index anyway.

(unsafe (i64vec-view-set! w 0 1))

Since: Phase N2

(i64vec-for [bv & body])

run body once per element of one or two I64Vecs.

(for [x v] body...) binds x to each element of v in order; (for [x v y w] body...) walks v and w together (same length, or a panic before the first pass). No index is in scope, so none can be wrong: the reads are i64vec-ref-unchecked, the body sees plain elements, and the loop carries no bounds check or panic test -- gcc can vectorize it at -O3. An array argument that is not a name is evaluated once, and freed after.

(let [v (i64vec-of 1 2)] (i64vec-for [x v] (println x)))

Since: Phase N2

(i64vec-for-index [bv & body])

run body once per element, with its index.

(for-index [i x v] body...) binds i (read-only) and x = v[i].

(let [v (i64vec-of 1 2)] (i64vec-for-index [i x v] (println i)))

Since: Phase N2

(i64vec-fold [bv body])

fold the elements of a I64Vec into an accumulator.

(fold [acc init x v] body): acc starts at init, and for each element x in order becomes the value of body (which sees acc and x). The result is the final acc. A float sum written this way is the strict left fold, so gcc keeps it scalar; i64vec-sum is the vectorized one.

(let [v (i64vec-of 1 2)] (i64vec-fold [n 0 x v] (+ n 1)))   ; => 2

Since: Phase N2

(i64vec-build [n bv expr])

a fresh I64Vec of n elements, element i the value of expr.

(build n [i] expr), after Racket's for/flvector: i is bound to each index in turn, and expr runs outside any unsafe. The stores go through a view (i64vec-view), so the loop vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc.

(let [v (i64vec-build 3 [i] 1)] (i64vec-len v))   ; => 3

Since: Phase N2

(i64vec-map! [dst bv expr])

store expr into dst[i] for every i, x bound to src[i].

(map! dst [x src] expr) stores into each slot of dst the value of expr with x bound to the element of src at the same index; (map! dst [x a y b] expr) walks two sources together. dst may be one of the sources: (map! v [x v] {x * 2}) maps in place. Every array has the same length, or a panic before the first element. The loop reads and stores through views (i64vec-view), so it vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc. expr runs outside any unsafe; an array argument that is not a name is evaluated once, and freed after the loop.

(let [v (i64vec-of 1 2)] (i64vec-map! v [x v] x) (i64vec-ref v 1))   ; => 2

Since: Phase N2

(i64vec-same-len__ [^borrow a : I64Vec ^borrow b : I64Vec])

internal: the common length of two arrays, or a panic.

(defopaque ^affine I32Vec : int)

a fixed-length, unboxed array of 32-bit integers (int32).

Opaque handle to a struct { int64_t len; int32_t *data; void *raw; }. ^affine: freed at scope exit by its Drop instance. Use i32vec-new or i32vec-of to make one.

Since: Phase N0

(defopaque I32View : int)

a view of a I32Vec's elements: the data pointer, for a store loop.

Made by i32vec-view, read and written by i32vec-view-ref / i32vec-view-set!. Not owned and not affine: it frees nothing, and it is valid exactly as long as the array it came from (an array never resizes, so its data never moves).

Since: Phase N2

(i32vec-new [n : int init : int32])

allocate a I32Vec of n elements, every one init.

(let [v (i32vec-new 4 (as int32 7))]
  (i32vec-ref v 2))   ; => (as int32 7)

Since: Phase N0

(i32vec-of [& xs])

a I32Vec holding the given elements, in order.

(let [v (i32vec-of (as int32 1) (as int32 2))]
  (i32vec-len v))   ; => 2

Since: Phase N0

(i32vec-free [v : I32Vec])

release a I32Vec now, consuming it.

Rarely needed: a let-bound I32Vec is freed at scope exit. Call it to release a large array before the scope ends.

(i32vec-free v)

Since: Phase N0

(definstance Drop [I32Vec])

free the array when a bound I32Vec dies unmoved.

(i32vec-len [^borrow v : I32Vec])

the element count of a I32Vec.

(let [v (i32vec-new 8 (as int32 7))]
  (i32vec-len v))   ; => 8

Since: Phase N0

(i32vec-ref [^borrow v : I32Vec i : int])

the element at index i (bounds-checked).

(let [v (i32vec-of (as int32 1) (as int32 2))]
  (i32vec-ref v 1))   ; => (as int32 2)

Since: Phase N0

(i32vec-set! [^borrow v : I32Vec i : int x : int32])

store x at index i (bounds-checked).

(i32vec-set! v 0 (as int32 7))

Since: Phase N0

(i32vec-copy [^borrow v : I32Vec])

a fresh I32Vec with the same elements.

(let [c (i32vec-copy v)] (i32vec-set! c 0 (as int32 7)))   ; v is unchanged

Since: Phase N0

(i32vec->vec-go__ [^borrow v : I32Vec out : (Vec int32) i : int n : int] : (Vec int32))

internal: push v[i..n) onto out.

(i32vec->vec [^borrow v : I32Vec] : (Vec int32))

copy a I32Vec into a fresh (Vec int32).

(let [a (i32vec-of (as int32 1) (as int32 2))
      v (i32vec->vec a)]
  (vec-len v))   ; => 2

Since: Phase N0

(vec->i32vec-go__ [^borrow out : I32Vec ^borrow src : (Vec int32) i : int n : int] : nil)

internal: store src[i..n) into out.

(vec->i32vec [^borrow src : (Vec int32)] : I32Vec)

copy a (Vec int32) into a fresh I32Vec.

(let [v (vec-of (as int32 1) (as int32 2))
      a (vec->i32vec v)]
  (i32vec-len a))   ; => 2

Since: Phase N0

(i32vec-show-loop__ [^borrow v : I32Vec i : int n : int b : StringBuilder] : StringBuilder)

internal: push "e0 e1 ..." onto the builder.

(i32vec-show [^borrow v : I32Vec] : String)

render a I32Vec as an owned "#i32vec[a b c]" String.

(let [v (i32vec-of (as int32 1) (as int32 2))]
  (i32vec-show v))   ; => String "#i32vec[1 2]"

Since: Phase N0

(i32vec-fill! [^borrow v : I32Vec x : int32])

store x in every slot.

(i32vec-fill! v (as int32 1))

Since: Phase N1

(i32vec-copy! [^borrow dst : I32Vec ^borrow src : I32Vec])

copy src's elements into dst (same length, or a panic).

(i32vec-copy! dst src)

Since: Phase N1

(i32vec-scale! [^borrow v : I32Vec s : int32])

multiply every element by s, in place.

Integer arithmetic wraps.

(i32vec-scale! v (as int32 2))

Since: Phase N1

(i32vec-add! [^borrow dst : I32Vec ^borrow src : I32Vec])

dst[i] += src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(i32vec-add! y x)

Since: Phase N1

(i32vec-axpy! [^borrow dst : I32Vec s : int32 ^borrow src : I32Vec])

dst[i] += s * src[i] for every i (same length, or a panic).

Integer arithmetic wraps; the multiply and the add are not fused.

(i32vec-axpy! y (as int32 2) x)

Since: Phase N1

(i32vec-sub! [^borrow dst : I32Vec ^borrow src : I32Vec])

dst[i] -= src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(i32vec-sub! y x)

Since: Phase N1

(i32vec-mul! [^borrow dst : I32Vec ^borrow src : I32Vec])

dst[i] *= src[i] for every i (same length, or a panic).

Element-wise, not a dot product. Integer arithmetic wraps; dst and src may be the same array.

(i32vec-mul! y x)

Since: Phase N1

(i32vec-add-scalar! [^borrow v : I32Vec s : int32])

add s to every element, in place.

Integer arithmetic wraps.

(i32vec-add-scalar! v (as int32 2))

Since: Phase N1

(i32vec-sum [^borrow v : I32Vec])

the sum of the elements.

A float sum is computed in eight interleaved partial sums (lane k takes the elements i with i mod 8 = k), combined in one fixed tree: the same answer on every engine and machine, and vectorizable without -ffast-math. It can differ in the last bits from -sum-ordered, the left-to-right sum. An integer sum wraps modulo 2^64; a narrow element is widened to int first.

(let [v (i32vec-of (as int32 1) (as int32 2))] (i32vec-sum v))

Since: Phase N1

(i32vec-dot [^borrow a : I32Vec ^borrow b : I32Vec])

the dot product of two arrays (same length, or a panic).

Floats use the same eight-lane order as -sum. Integers wrap modulo 2^64; an int32 product is formed in 64 bits.

(let [a (i32vec-of (as int32 1) (as int32 2)) b (i32vec-of (as int32 2) (as int32 1))] (i32vec-dot a b))

Since: Phase N1

(i32vec-min [^borrow v : I32Vec])

the smallest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (i32vec-of (as int32 1) (as int32 2))] (i32vec-min v))   ; => (as int32 1)

Since: Phase N1

(i32vec-max [^borrow v : I32Vec])

the largest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (i32vec-of (as int32 1) (as int32 2))] (i32vec-max v))   ; => (as int32 2)

Since: Phase N1

(i32vec-ref-unchecked [^borrow v : I32Vec i : int])

the element at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The loop macros (-for, -fold, ...) use it where they have already checked the index. Its body calls nothing, so a call to it carries no panic check, and a loop of such calls can vectorize.

(unsafe (i32vec-ref-unchecked v 0))

Since: Phase N2

(i32vec-set-unchecked! [^borrow v : I32Vec i : int x : int32])

store x at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE (see the module header).

(unsafe (i32vec-set-unchecked! v 0 (as int32 1)))

Since: Phase N2

(i32vec-view [^borrow v : I32Vec])

a view of v's elements, for a loop that stores into it.

#fx{Unsafe}: nothing ties the view to the array, so a view used after the array is freed reads freed memory. Why it exists: a store through the array (-set-unchecked!) re-reads the header's data pointer, which the store might have overwritten as far as the C compiler knows, so the loop does not vectorize; a view is that pointer, read once. -build and -map! store through one; reach for it directly only for a store loop they do not cover.

(let [v (i32vec-of (as int32 1) (as int32 2)) w (unsafe (i32vec-view v))] (unsafe (i32vec-view-ref w 1)))   ; => (as int32 2)

Since: Phase N2

(i32vec-view-ref [w : I32View i : int])

the element at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The interpreter checks the index anyway, as it does for -ref-unchecked.

(unsafe (i32vec-view-ref w 0))

Since: Phase N2

(i32vec-view-set! [w : I32View i : int x : int32])

store x at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE. The interpreter checks the index anyway.

(unsafe (i32vec-view-set! w 0 (as int32 1)))

Since: Phase N2

(i32vec-for [bv & body])

run body once per element of one or two I32Vecs.

(for [x v] body...) binds x to each element of v in order; (for [x v y w] body...) walks v and w together (same length, or a panic before the first pass). No index is in scope, so none can be wrong: the reads are i32vec-ref-unchecked, the body sees plain elements, and the loop carries no bounds check or panic test -- gcc can vectorize it at -O3. An array argument that is not a name is evaluated once, and freed after.

(let [v (i32vec-of (as int32 1) (as int32 2))] (i32vec-for [x v] (println x)))

Since: Phase N2

(i32vec-for-index [bv & body])

run body once per element, with its index.

(for-index [i x v] body...) binds i (read-only) and x = v[i].

(let [v (i32vec-of (as int32 1) (as int32 2))] (i32vec-for-index [i x v] (println i)))

Since: Phase N2

(i32vec-fold [bv body])

fold the elements of a I32Vec into an accumulator.

(fold [acc init x v] body): acc starts at init, and for each element x in order becomes the value of body (which sees acc and x). The result is the final acc. A float sum written this way is the strict left fold, so gcc keeps it scalar; i32vec-sum is the vectorized one.

(let [v (i32vec-of (as int32 1) (as int32 2))] (i32vec-fold [n 0 x v] (+ n 1)))   ; => 2

Since: Phase N2

(i32vec-build [n bv expr])

a fresh I32Vec of n elements, element i the value of expr.

(build n [i] expr), after Racket's for/flvector: i is bound to each index in turn, and expr runs outside any unsafe. The stores go through a view (i32vec-view), so the loop vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc.

(let [v (i32vec-build 3 [i] (as int32 1))] (i32vec-len v))   ; => 3

Since: Phase N2

(i32vec-map! [dst bv expr])

store expr into dst[i] for every i, x bound to src[i].

(map! dst [x src] expr) stores into each slot of dst the value of expr with x bound to the element of src at the same index; (map! dst [x a y b] expr) walks two sources together. dst may be one of the sources: (map! v [x v] {x * 2}) maps in place. Every array has the same length, or a panic before the first element. The loop reads and stores through views (i32vec-view), so it vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc. expr runs outside any unsafe; an array argument that is not a name is evaluated once, and freed after the loop.

(let [v (i32vec-of (as int32 1) (as int32 2))] (i32vec-map! v [x v] x) (i32vec-ref v 1))   ; => (as int32 2)

Since: Phase N2

(i32vec-same-len__ [^borrow a : I32Vec ^borrow b : I32Vec])

internal: the common length of two arrays, or a panic.

(defopaque ^affine U8Vec : int)

a fixed-length, unboxed array of bytes (uint8).

Opaque handle to a struct { int64_t len; uint8_t *data; void *raw; }. ^affine: freed at scope exit by its Drop instance. Use u8vec-new or u8vec-of to make one.

Since: Phase N0

(defopaque U8View : int)

a view of a U8Vec's elements: the data pointer, for a store loop.

Made by u8vec-view, read and written by u8vec-view-ref / u8vec-view-set!. Not owned and not affine: it frees nothing, and it is valid exactly as long as the array it came from (an array never resizes, so its data never moves).

Since: Phase N2

(u8vec-new [n : int init : uint8])

allocate a U8Vec of n elements, every one init.

(let [v (u8vec-new 4 (as uint8 200))]
  (u8vec-ref v 2))   ; => (as uint8 200)

Since: Phase N0

(u8vec-of [& xs])

a U8Vec holding the given elements, in order.

(let [v (u8vec-of (as uint8 1) (as uint8 2))]
  (u8vec-len v))   ; => 2

Since: Phase N0

(u8vec-free [v : U8Vec])

release a U8Vec now, consuming it.

Rarely needed: a let-bound U8Vec is freed at scope exit. Call it to release a large array before the scope ends.

(u8vec-free v)

Since: Phase N0

(definstance Drop [U8Vec])

free the array when a bound U8Vec dies unmoved.

(u8vec-len [^borrow v : U8Vec])

the element count of a U8Vec.

(let [v (u8vec-new 8 (as uint8 200))]
  (u8vec-len v))   ; => 8

Since: Phase N0

(u8vec-ref [^borrow v : U8Vec i : int])

the element at index i (bounds-checked).

(let [v (u8vec-of (as uint8 1) (as uint8 2))]
  (u8vec-ref v 1))   ; => (as uint8 2)

Since: Phase N0

(u8vec-set! [^borrow v : U8Vec i : int x : uint8])

store x at index i (bounds-checked).

(u8vec-set! v 0 (as uint8 200))

Since: Phase N0

(u8vec-copy [^borrow v : U8Vec])

a fresh U8Vec with the same elements.

(let [c (u8vec-copy v)] (u8vec-set! c 0 (as uint8 200)))   ; v is unchanged

Since: Phase N0

(u8vec->vec-go__ [^borrow v : U8Vec out : (Vec uint8) i : int n : int] : (Vec uint8))

internal: push v[i..n) onto out.

(u8vec->vec [^borrow v : U8Vec] : (Vec uint8))

copy a U8Vec into a fresh (Vec uint8).

(let [a (u8vec-of (as uint8 1) (as uint8 2))
      v (u8vec->vec a)]
  (vec-len v))   ; => 2

Since: Phase N0

(vec->u8vec-go__ [^borrow out : U8Vec ^borrow src : (Vec uint8) i : int n : int] : nil)

internal: store src[i..n) into out.

(vec->u8vec [^borrow src : (Vec uint8)] : U8Vec)

copy a (Vec uint8) into a fresh U8Vec.

(let [v (vec-of (as uint8 1) (as uint8 2))
      a (vec->u8vec v)]
  (u8vec-len a))   ; => 2

Since: Phase N0

(u8vec-show-loop__ [^borrow v : U8Vec i : int n : int b : StringBuilder] : StringBuilder)

internal: push "e0 e1 ..." onto the builder.

(u8vec-show [^borrow v : U8Vec] : String)

render a U8Vec as an owned "#u8vec[a b c]" String.

(let [v (u8vec-of (as uint8 1) (as uint8 2))]
  (u8vec-show v))   ; => String "#u8vec[1 2]"

Since: Phase N0

(u8vec-fill! [^borrow v : U8Vec x : uint8])

store x in every slot.

(u8vec-fill! v (as uint8 1))

Since: Phase N1

(u8vec-copy! [^borrow dst : U8Vec ^borrow src : U8Vec])

copy src's elements into dst (same length, or a panic).

(u8vec-copy! dst src)

Since: Phase N1

(u8vec-add! [^borrow dst : U8Vec ^borrow src : U8Vec])

dst[i] += src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(u8vec-add! y x)

Since: Phase N1

(u8vec-sub! [^borrow dst : U8Vec ^borrow src : U8Vec])

dst[i] -= src[i] for every i (same length, or a panic).

Integer arithmetic wraps; dst and src may be the same array.

(u8vec-sub! y x)

Since: Phase N1

(u8vec-add-scalar! [^borrow v : U8Vec s : uint8])

add s to every element, in place.

Integer arithmetic wraps.

(u8vec-add-scalar! v (as uint8 2))

Since: Phase N1

(u8vec-sum [^borrow v : U8Vec])

the sum of the elements.

A float sum is computed in eight interleaved partial sums (lane k takes the elements i with i mod 8 = k), combined in one fixed tree: the same answer on every engine and machine, and vectorizable without -ffast-math. It can differ in the last bits from -sum-ordered, the left-to-right sum. An integer sum wraps modulo 2^64; a narrow element is widened to int first.

(let [v (u8vec-of (as uint8 1) (as uint8 2))] (u8vec-sum v))

Since: Phase N1

(u8vec-min [^borrow v : U8Vec])

the smallest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (u8vec-of (as uint8 1) (as uint8 2))] (u8vec-min v))   ; => (as uint8 1)

Since: Phase N1

(u8vec-max [^borrow v : U8Vec])

the largest element (an empty array panics).

A NaN element makes the result NaN (the first NaN, by index). Which of two equal elements (0.0 and -0.0) is returned is fixed by the reduction order, the same on every engine.

(let [v (u8vec-of (as uint8 1) (as uint8 2))] (u8vec-max v))   ; => (as uint8 2)

Since: Phase N1

(u8vec-ref-unchecked [^borrow v : U8Vec i : int])

the element at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The loop macros (-for, -fold, ...) use it where they have already checked the index. Its body calls nothing, so a call to it carries no panic check, and a loop of such calls can vectorize.

(unsafe (u8vec-ref-unchecked v 0))

Since: Phase N2

(u8vec-set-unchecked! [^borrow v : U8Vec i : int x : uint8])

store x at index i, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE (see the module header).

(unsafe (u8vec-set-unchecked! v 0 (as uint8 1)))

Since: Phase N2

(u8vec-view [^borrow v : U8Vec])

a view of v's elements, for a loop that stores into it.

#fx{Unsafe}: nothing ties the view to the array, so a view used after the array is freed reads freed memory. Why it exists: a store through the array (-set-unchecked!) re-reads the header's data pointer, which the store might have overwritten as far as the C compiler knows, so the loop does not vectorize; a view is that pointer, read once. -build and -map! store through one; reach for it directly only for a store loop they do not cover.

(let [v (u8vec-of (as uint8 1) (as uint8 2)) w (unsafe (u8vec-view v))] (unsafe (u8vec-view-ref w 1)))   ; => (as uint8 2)

Since: Phase N2

(u8vec-view-ref [w : U8View i : int])

the element at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). The interpreter checks the index anyway, as it does for -ref-unchecked.

(unsafe (u8vec-view-ref w 0))

Since: Phase N2

(u8vec-view-set! [w : U8View i : int x : uint8])

store x at index i of a view, NOT bounds-checked.

#fx{Unsafe}: call it inside (unsafe ...). Stores a number: no TUR_REGION_NOTE. The interpreter checks the index anyway.

(unsafe (u8vec-view-set! w 0 (as uint8 1)))

Since: Phase N2

(u8vec-for [bv & body])

run body once per element of one or two U8Vecs.

(for [x v] body...) binds x to each element of v in order; (for [x v y w] body...) walks v and w together (same length, or a panic before the first pass). No index is in scope, so none can be wrong: the reads are u8vec-ref-unchecked, the body sees plain elements, and the loop carries no bounds check or panic test -- gcc can vectorize it at -O3. An array argument that is not a name is evaluated once, and freed after.

(let [v (u8vec-of (as uint8 1) (as uint8 2))] (u8vec-for [x v] (println x)))

Since: Phase N2

(u8vec-for-index [bv & body])

run body once per element, with its index.

(for-index [i x v] body...) binds i (read-only) and x = v[i].

(let [v (u8vec-of (as uint8 1) (as uint8 2))] (u8vec-for-index [i x v] (println i)))

Since: Phase N2

(u8vec-fold [bv body])

fold the elements of a U8Vec into an accumulator.

(fold [acc init x v] body): acc starts at init, and for each element x in order becomes the value of body (which sees acc and x). The result is the final acc. A float sum written this way is the strict left fold, so gcc keeps it scalar; u8vec-sum is the vectorized one.

(let [v (u8vec-of (as uint8 1) (as uint8 2))] (u8vec-fold [n 0 x v] (+ n 1)))   ; => 2

Since: Phase N2

(u8vec-build [n bv expr])

a fresh U8Vec of n elements, element i the value of expr.

(build n [i] expr), after Racket's for/flvector: i is bound to each index in turn, and expr runs outside any unsafe. The stores go through a view (u8vec-view), so the loop vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc.

(let [v (u8vec-build 3 [i] (as uint8 1))] (u8vec-len v))   ; => 3

Since: Phase N2

(u8vec-map! [dst bv expr])

store expr into dst[i] for every i, x bound to src[i].

(map! dst [x src] expr) stores into each slot of dst the value of expr with x bound to the element of src at the same index; (map! dst [x a y b] expr) walks two sources together. dst may be one of the sources: (map! v [x v] {x * 2}) maps in place. Every array has the same length, or a panic before the first element. The loop reads and stores through views (u8vec-view), so it vectorizes where expr allows: at -O2 under clang, at -O3 (--release) under gcc. expr runs outside any unsafe; an array argument that is not a name is evaluated once, and freed after the loop.

(let [v (u8vec-of (as uint8 1) (as uint8 2))] (u8vec-map! v [x v] x) (u8vec-ref v 1))   ; => (as uint8 2)

Since: Phase N2

(u8vec-same-len__ [^borrow a : U8Vec ^borrow b : U8Vec])

internal: the common length of two arrays, or a panic.

(defclass NumArray [v])

the operations every typed numeric array has, as one class.

Write a numeric algorithm once, over [V] [(NumArray V)], and it runs on F64Vec, F32Vec, I64Vec, I32Vec and U8Vec, each call going straight to that type's own function (one specialization per type, no runtime dispatch). The element type is the associated type Elem -- (Elem V) in a signature -- so a method returns the honest float32 or uint8, not a carrier word. Sum is what na-sum returns (int for the integer types, the element type for the floats) and View the type of na-view's result. Arithmetic on an element needs (Num (Elem V)), and a conversion or a constant (NumCast (Elem V)) (stdlib/typeclass.tur). Constructors stay per type (f64vec-new ...): a length alone cannot pick an instance. The loops na-for, na-fold and na-map! below work inside such a generic.

(type Elem : Type)
(type Sum : Type)
(type View : Type)

(defn mean [V] [(NumArray V) (NumCast (Sum V))] [^borrow a : V] : float
  {(to-float (na-sum a)) / (as float (na-len a))})
(mean (f64vec-of 1.5 2.5))   ; => 2.0

Since: Phase N2

(definstance NumArray [F64Vec])

delegates to the f64vec-* functions.

(definstance NumArray [F32Vec])

delegates to the f32vec-* functions.

(definstance NumArray [I64Vec])

delegates to the i64vec-* functions.

(definstance NumArray [I32Vec])

delegates to the i32vec-* functions.

(definstance NumArray [U8Vec])

delegates to the u8vec-* functions.

(na-same-len__ [V])

internal: the common length of two arrays, or a panic.

(na-for [bv & body])

run body once per element of one or two arrays, in a generic.

-for over the class: (na-for [x v] body...), or (na-for [x v y w] body...) to walk two together (same length, or a panic first). The enclosing function needs (NumArray V); x is an (Elem V).

(defn count-pos [V] [(NumArray V) (Ord (Elem V)) (NumCast (Elem V))]
  [^borrow a : V] : int
  (let [^mut n 0]
    (na-for [x a] (when (> x (:: (from-int 0) (Elem V))) (set! n {n + 1})))
    n))

Since: Phase N2

(na-fold [bv body])

fold the elements of an array into an accumulator, in a generic.

-fold over the class: (na-fold [acc init x v] body).

(na-fold [n 0 x a] {n + 1})   ; => the length, in a generic over a

Since: Phase N2

(na-map! [dst bv expr])

store expr into dst[i] for every i, in a generic.

-map! over the class: (na-map! dst [x src] expr) or (na-map! dst [x a y b] expr); dst may be a source. Stores through views.

(defn double! [V] [(NumArray V) (Num (Elem V))] [^borrow a : V] : nil
  (na-map! a [x a] {x + x}))

Since: Phase N2