These operations borrow their inputs and return independent results. Chapter 21 contains runnable examples. Ordinary INTEGER division and MOD truncate toward zero; choose the explicit coordinate helpers for other mathematical policies.
| Coordinate helper | Result and checked errors |
|---|---|
| FloorDiv(value, divisor) | INTEGER floor quotient; NumericError for zero or unrepresentable quotient |
| EuclideanMod(value, divisor) | Nonnegative INTEGER remainder below mathematical abs(divisor); NumericError for zero divisor |
| FloorToInteger(value) | DOUBLE floor converted to INTEGER; NumericError for nonfinite/out-of-range input |
For example FloorDiv(17,-16) is -2, while EuclideanMod(17,-16) is 1. With a negative divisor, these policies do not necessarily describe the same quotient/remainder pair. Minimum INTEGER divided by -1 is unrepresentable; its Euclidean remainder is zero. These helpers report recoverable NumericError rather than relying on fatal arithmetic traps.
Numeric sequences
Supported element types are DOUBLE, INTEGER, BYTE, UINT32 and UINT64. Operands are lists or rank-one arrays. Paired operands use the same element/container type; arrays with different lower bounds pair by position. Other ranks raise VectorRankError. There are no string or Boolean coercions.
| API | Result | Checked conditions |
|---|---|---|
| Dot(left, right) | DOUBLE, INTEGER, or UINT64 for unsigned inputs | Matching dimensions; integral arithmetic range |
| Norm(values) | DOUBLE Euclidean length | Valid array rank |
| Normalized(values) | LIST OF DOUBLE | Nonzero norm |
| Distance(left, right) | DOUBLE Euclidean distance | Matching dimensions |
| CosineSimilarity(left, right) | DOUBLE, rounded/clamped to [-1,1] | Matching dimensions and nonzero norms |
| VectorAdd/Subtract/Multiply/Divide | LIST with input element type | Matching dimensions; integral range/division |
| Scaled(values, factor) | LIST with input element type | Factor has the same scalar type; integral range |
VectorDimensionError carries LeftCount and RightCount. VectorRankError carries Rank. Empty dot, norm and distance are zero; elementwise empty results are empty. Normalized and cosine reject zero norms, including empty vectors, with ZeroVectorError. Shape validation precedes arithmetic. Recoverable failure preserves source values and an existing assignment destination.
BYTE/UINT32 dot products widen to UINT64 before multiplication. Other component operations keep their input width. Integral overflow/underflow or unrepresentable quotients raise NumericError code 2; integer division by zero is code 1. An earlier intermediate overflow fails even if later terms could cancel it.
Floating arithmetic retains IEEE NaN/infinity. DOUBLE dot starts at +0.0 and uses source-order multiplication/addition without reassociation or fused contraction. Integral norm/normalization/cosine coordinates convert to DOUBLE and can lose precision above 2^53. Integral distance first computes each exact difference magnitude, then converts it: adjacent large integers still have distance 1.
Norm/distance return NaN for a relevant NaN component/difference, otherwise infinity when any is infinite. Equal infinities have NaN distance. Normalization with infinite scale yields NaN for infinite components and signed zero for finite ones; NaN scale yields NaN components. Nonfinite cosine data yields NaN, but a zero vector still raises ZeroVectorError first. Use explicit finite validation where the application needs it. Value-returning operations produce new lists even for array inputs; use ToArray when an array is required. Large synchronous operations may delay scheduling and cancellation.