Scalar, vector, and matrix helpers, including transcendental functions, interpolation, vector products, transposition, and determinant-based matrix operations.

Shape constructors and scalars

The module uses Lists as fixed-size vectors. A Matrix is an outer vector of row vectors: the first size is the column count and the second is the row count, so storage is row-major.

E

(-- value) Returns the known Real32 Euler constant.
  • The value is 2.7182818r32.

E64

(-- value) Returns the known Real64 Euler constant.
  • The value is 2.718281828459045r64.

PI

(-- value) Returns the known Real32 pi constant.
  • The value is 3.14159265r32.

PI64

(-- value) Returns the known Real64 pi constant.
  • The value is 3.141592653589793r64.

Contract for the transcendental functions: angular inputs and outputs are radians. acos, asin, exp, tan, atan, and atan2 return unknown values even for known inputs and retain the selected real schema. On 32-bit targets, Real32 wrappers convert through Real64 C calls and convert the result back to Real32.

count, colCount, and rowCount are nonnegative, known Int32 compile-time parameters. A positive count produces a List; count 0 produces the empty Tuple (), which no vector operation accepts. A Matrix with zero rows or columns does not satisfy matrix?.

Vector

(value count -- vector) For a positive count, creates a List of count items initialized from value (the builtin array).
  • The resulting fields are unnamed and have the supplied item schema.
  • The result is an ordinary object; pass it wherever an object of the vector schema is expected, for example as the target of cast: v 0.0r32 3 Vector cast.
  • The item must support the copies the constructor performs.

Matrix

(value colCount rowCount -- matrix) Creates rowCount rows of colCount items initialized from value, stored row by row.
  • The result is an ordinary object; pass it wherever an object of the matrix schema is expected.
  • For example, 0.0r32 2 3 Matrix has three rows of two Real32 items.

Vector delegates to array. For a positive count and a managed source, the first item is copied from an immutable view or moved from a mutable view, leaving a moved-from source freshly constructed; remaining items copy the first. Matrix applies Vector first for the columns and then for the rows, so it can move from a mutable managed source even when rowCount is zero.

acos

(value -- result) Applies arccosine to a Real32 or Real64 value.

asin

(value -- result) Applies arcsine to a Real32 or Real64 value.

exp

(value -- result) Applies the exponential function to a Real32 or Real64 value.

tan

(value -- result) Applies tangent to a Real32 or Real64 value.

atan

(value -- result) Applies arctangent to a Real32 or Real64 value.

atan2

(x y -- result) Returns atan2(y, x) in radians for two same-schema real values.

Target-conditional functions

All names in this section are Code bindings; the angular contract of the transcendental functions applies to them.

acosf

(value -- result) Calls the arccosine C function and returns an unknown Real32 result.
  • Requires Real32 input.
  • Available on 64-bit targets.

asinf

(value -- result) Calls the arcsine C function and returns an unknown Real32 result.
  • Requires Real32 input.
  • Available on 64-bit targets.

expf

(value -- result) Calls the exponential C function and returns an unknown Real32 result.
  • Requires Real32 input.
  • Available on 64-bit targets.

tanf

(value -- result) Calls the tangent C function and returns an unknown Real32 result.
  • Requires Real32 input.
  • Available on 64-bit targets.

atanf

(value -- result) Calls the arctangent C function and returns an unknown Real32 result.
  • Requires Real32 input.
  • Available on 64-bit targets.

atan2f

(x y -- result) Calls the atan2(y, x) C function and returns an unknown Real32 result.
  • Requires both x and y to be Real32.
  • Available on 64-bit targets.

acosFunc

(value -- result) Calls the arccosine C function and returns an unknown Real64 result.
  • Requires Real64 input.
  • Available on 32-bit targets.

asinFunc

(value -- result) Calls the arcsine C function and returns an unknown Real64 result.
  • Requires Real64 input.
  • Available on 32-bit targets.

expFunc

(value -- result) Calls the exponential C function and returns an unknown Real64 result.
  • Requires Real64 input.
  • Available on 32-bit targets.

tanFunc

(value -- result) Calls the tangent C function and returns an unknown Real64 result.
  • Requires Real64 input.
  • Available on 32-bit targets.

atanFunc

(value -- result) Calls the arctangent C function and returns an unknown Real64 result.
  • Requires Real64 input.
  • Available on 32-bit targets.

atan2Func

(x y -- result) Calls the atan2(y, x) C function and returns an unknown Real64 result.
  • Requires both x and y to be Real64.
  • Available on 32-bit targets.

Shape compatibility

vector?

(object -- cond) Returns TRUE for a Struct with at least one field whose first field is unnamed; returns FALSE otherwise.
  • Later field names, item schemas, and numeric suitability are not checked.

matrix?

(object -- cond) Returns TRUE for an object satisfying vector? whose rows also satisfy vector? and have equal field counts.
  • Empty outer collections and empty rows return FALSE. A nested Vector can be a matrix; neither predicate requires homogeneous numeric items.

getColCount

(matrix -- count) Returns the field count of the first matrix row.
  • The caller supplies a matrix that satisfies matrix?.

getRowCount

(matrix -- count) Returns the matrix outer field count.
  • The caller supplies a matrix that satisfies matrix?.

Value operations

angle

(vector -- value) Returns the angle in radians of the two-item vector (x, y), using item 0 as x and item 1 as y.
  • The vector must pass vector? and have field count 2.
  • Both items must be Real32 or both Real64.

cosSin

(angle -- pair) Returns a two-item List containing cos(angle) and sin(angle), in that order, with the input real schema; angle is in radians.
  • The input is passed to the scalar cos and sin operations.

-

(left right -- vector) Subtracts equal-sized vectors item by item.
  • Both operands must pass vector? and have equal field counts.
  • The result is a newly constructed object, not a reference to either input.
  • The selected - operation is applied to each item.

+

(left right -- vector) Adds equal-sized vectors item by item.
  • Both operands must pass vector? and have equal field counts.
  • The result is a newly constructed object, not a reference to either input.
  • The selected + operation is applied to each item.

=

(leftVector rightVector -- cond)
(vector oneRowMatrix --) Compares vector items in order, with one overload for a vector and a one-row matrix.
  • The vector overload requires equal field counts and compares every corresponding item.
  • The mixed overload requires a non-matrix vector and a matrix with one row and the same column count.

Known issue: the special vector/one-row-matrix equality overload currently returns no condition. It requires the vector on the left and one-row matrix on the right; compare the vector with row 0 explicitly as v 0 m @ =.

/

(vector value -- vector) Divides every vector item by one scalar value.
  • The vector must pass vector?; each item is divided by the scalar.
  • An unknown real zero can produce infinity or NaN at run time.

*

(left right -- result) Overloads scalar-vector, vector-scalar, matrix-matrix, and vector-matrix multiplication.
  • The * scalar overload lets a numeric scalar multiply a vector on either side and returns a newly constructed vector.
  • The * matrix overload requires the left column count to equal the right row count and returns a newly constructed matrix.
  • The vector-matrix overload requires the vector field count to equal the matrix row count and returns a newly constructed vector.

Known issue: the vector-matrix body indexes the vector with matrix column ordinals, so a non-square shape accepted by the check can fail at compile time with «@», First argument (key) is out of bounds; use square matrices for this overload.

  • Use dot, cross, or multiply for two vectors rather than the multiplication operator.

|

(left right -- result) Concatenates matrices vertically, or appends one vector as a matrix row.
  • A vector-passing right operand can be appended as one row. Otherwise matrix concatenation requires equal column counts and returns rows as new values.
  • Matrix-vector concatenation requires the vector field count to equal the matrix column count and returns the vector as one additional row.

Known issue: when the left column count equals the right operand's row count — always for two square matrices of one size — the matrix-row form is selected and the right matrix is appended as one nested row (((1 2) (3 4)) ((5 6) (7 8)) | gives ((1 2) (3 4) ((5 6) (7 8)))). Stacking works only when the counts differ, e.g. ((1 2 3) (4 5 6)) ((7 8 9)) |.

&

(left right -- result) Concatenates two vectors or concatenates matrix rows horizontally.
  • The & vector overload returns a new vector with both item sequences.
  • Equal-row-count matrices join corresponding rows horizontally; otherwise the vector overload concatenates outer item sequences, so unequal matrix row counts can produce nested or ragged results.

toColumn

(vector -- matrix) Converts a vector to a matrix with one item per row.
  • Each output row is a new one-item vector.

multiply

(left right -- vector) Returns the itemwise product of two equal-sized vectors.
  • Both operands must pass vector? and have equal field counts.
  • The result is freshly constructed.
  • multiply is the itemwise (Hadamard) vector product. Applied to two matrices it multiplies the rows with the multiplication operator, which rejects two vectors (the error names CAN_NOT_MUL_TWO_VECTORS_USE_DOT_OR_CROSS_OR_HADAMAR); use it for vectors only.

divide

(left right -- vector) Returns the itemwise quotient of two equal-sized vectors.
  • Both operands must pass vector? and have equal field counts.
  • An unknown real zero can produce infinity or NaN at run time.

trans

(object -- result) Converts a vector to a one-column matrix or transposes a matrix.
  • The vector overload returns a new one-item-row value for each vector item.
  • The matrix overload returns a new matrix whose row and column counts are exchanged.

lerp

(left right factor -- result) Linearly interpolates left toward right by factor.
  • The expression is right minus left, scaled by factor, then added to left.
  • Vector operands therefore need the same vector-operation shape and item schemas.

Vector-only operations

dot

(left right -- value) Returns the scalar dot product of equal-sized vectors.
  • Requires nonempty equal-length vectors whose item products can be added; returns their scalar dot product.

cross

(left right -- vector) Returns the three-dimensional cross product.
  • Both operands must have field count 3.
  • The result is a newly constructed three-item value.

squaredLength

(vector -- value) Returns the dot product of a vector with itself.
  • The vector must pass vector?.

length

(vector -- value) Returns the square root of squaredLength.
  • The vector must pass vector? and use one real item schema, Real32 or Real64.

unit

(vector -- vector) Divides a vector by its length.
  • The output has the same field count and real item schema.
  • An unknown real zero can produce NaN at run time.

unitChecked

(vector -- vector) Normalizes a vector or returns the first basis vector when its squared length is below the threshold.
  • The squared length is compared strictly with t*t, where t is 1.0e-6 cast to the vector item schema; equality takes the normalization path.
  • The fallback is (1 0 ... 0) with the vector field count and item schema.
  • For ordinary numeric normalization, use a nonempty vector of one real item schema, Real32 or Real64.

neg

(vector -- vector) Negates every vector item.
  • The result is freshly constructed and keeps the vector shape.

cast

(source target -- vector) Casts each source vector item to the item schema of a target vector.
  • Both operands must pass vector?. The target field count controls truncation.
  • The source must have at least as many fields as the target; extra source fields are omitted.
  • The output has the target vector field count and item schema; target item schemas may differ by ordinal.

Matrix-only operations

rotationMatrix

(angle -- matrix) Builds a 2×2 rotation matrix from one Real32 angle in radians.
  • The rows are (angle cos angle sin) and (angle sin neg angle cos), i.e. (cos θ, sin θ) and (−sin θ, cos θ).

det

(matrix -- value) Returns the determinant of a square matrix.
  • Separate overloads implement sizes 1, 2, 3, and 4.
  • A matrix of another size has no det overload.

Known issue: the 1x1 overload leaves 0 and a copy of the sole row instead of returning the scalar determinant; read element (0,0) directly.

adj

(matrix -- matrix) Returns the adjugate of a square matrix.
  • Separate overloads implement sizes 1, 2, 3, and 4.
  • The returned matrix is newly constructed; some entries can retain immutable reference views of source values.

Known issue: a direct 1x1 adj call fails with Name was not found; the 1x1 inv path fails with Second argument (divisor) is not Number.

inv

(matrix -- matrix) Divides each adjugate entry by the determinant using scalar division.
  • The matrix must be square and its selected det and adj overloads must exist. Integer item schemas use integer quotients, not a rational inverse.
  • An unknown real zero can produce infinity or NaN at run time.

Examples

Vector addition and dot product

"algebra" use
"control" use

{} () {} [
  v: (1i32 2i32 3i32);
  w: (4i32 5i32 6i32);
  v w + printStack _:;
  v w dot printStack _:;
] "main" exportFunction

Expected Output During Compilation

(5 7 9)
32

Matrix determinant

"algebra" use
"control" use

{} () {} [
  m: ((1i32 2i32) (3i32 4i32));
  m det printStack _:;
] "main" exportFunction

Expected Output During Compilation

-2

Runtime vector check

"String"  use
"algebra" use
"control" use

{} Int32 {} [
  v: (1i32 2i32 3i32);
  w: (4i32 5i32 6i32);
  sum: v w +;
  expected: (5i32 7i32 9i32);
  sum expected = print
  LF print
  v w dot 32 = print
  LF print
  0
] "main" exportFunction

Expected Output

TRUE
TRUE

See also