Skip to content

Numeric types, integers and conversions ​

Each numeric namespace uses its corresponding TypedArray and explicit conversion rules. Types never promote implicitly.

Types and storage ​

engine.f64/i8/u8/i16/u16/i32/u32 accept the corresponding standard TypedArrays. Arenas and synchronous scopes expose the same namespaces with alloc/from. Handles expose readonly dtype and length; from/set/toArray retain copy semantics. Each floating namespace now has 73 methods; each signed integer has 37 and each unsigned integer has 35. Unsigned integers have no neg/abs. Integers have no floating div, classification, sum/dot, scans or combination methods; integer division is divTrunc.

The default output is independent; right scalars broadcast where registered, and explicit out may exactly alias same-dtype inputs. Shift/rotate counts are scalar only. Numeric u8 and mask are distinct resident dtypes; array masks are canonical 0/1 Uint8Arrays. Uint8ClampedArray, BigInt arrays, shared/resizable/ detached backing memory and foreign-realm arrays are rejected.

Layouts come from the registry. Maximum byte length is 2^31 - 1; maximum element count is its floor quotient by element size. f64 allocations are eight-byte aligned. Wasm views are refreshed for each access so handles survive memory growth. Engine or arena disposal invalidates owned handles.

f64 behavior ​

Scalar arguments, storage, intermediate basic operations and results stay f64. They do not pass through Math.fround or a Wasm f32 argument. NaN, zero signs and rounding follow the floating-point contract. Scans remain sequential, initialized from the first element. Every multiply, add and subtract in combinations rounds separately; no implicit FMA is used.

Reductions use the fixed algorithms: compensated sum/dot, sequential product, scaled l2Norm and centered two-pass variance. The f64 accumulator does not widen. Each f64 dot product rounds before summation; no exact or correctly rounded total is promised. Intermediate overflow and underflow follow IEEE: the sum and mean of [MAX_VALUE, MAX_VALUE] may both be Infinity, and computing variance before its square root can overflow stddev. The scaled l2Norm avoids directly squaring extreme inputs.

Empty identities, NaN/infinity handling, ddof and first-extremum rules follow the reduction contract. Tests use exact per-step f64 references where appropriate, and finite-data tolerances plus cancellation, extreme norms and small-variance cases for statistics. These budgets are not whole-domain ULP guarantees.

Integer behavior ​

  • add/sub/mul/square/neg/abs wrap at the target width; abs(INT_MIN) is INT_MIN. General integer kernels use i128, avoiding a lossy JS floating intermediate for u32 multiplication.
  • addSaturating/subSaturating clamp to the dtype range for all six integer types.
  • divTrunc rounds toward zero. Zero divisors and signed INT_MIN / -1 fail before writing. remainder has the dividend's sign; INT_MIN % -1 is zero; a zero divisor fails.
  • Shift and rotation counts must be finite integers in 0 <= count < bitWidth. shiftRight is arithmetic for signed types and logical for unsigned types. shiftRightLogical zero-fills and returns the result in the original dtype.
  • mulHigh returns the high half of the signed or unsigned double-width product. popcount/clz/ctz return the input dtype; clz(0) and ctz(0) equal the bit width.
  • Scalars must be finite integers in the target range. JS implicit 32-bit coercion is not used. Clamp bounds are checked and lower must not exceed upper.
  • Extremum reductions return JS numbers. Empty reduceMin/reduceMax return the dtype maximum/minimum. argMin/argMax choose the first match, or -1 when empty.

Explicit conversions ​

Use engine.convert(input, targetType, { mode?, out? }) or its arena counterpart. Exactly 36 directed pairs are registered: f32↔f64, i32↔f32, u8↔f32 and the 30 nonidentity pairs among the six integer dtypes. Same-type copies, other floating pairs and mask/u8 conversion are unsupported. Types restrict targets and runtime validation repeats the check; Rust conversion pairs are generated from the registry.

ModeFloat to integerInteger to integerFloat target
checked (default)Truncate toward zero, then reject NaN/infinity/out-of-range resultsCheck rangeIEEE rounding
saturateTruncate and clamp; NaN → 0, infinities → endpointsClampIEEE rounding
wrapReject, including empty inputWrap to target widthReject

Floating conversions may lose precision. f64→f32 can overflow to infinity or underflow to signed zero; integer→f32 can round. Checked failures are found before changing output. Different-dtype input/output byte intervals must not overlap, even at the same starting address. This includes u8/mask comparisons and selection. Read-only inputs may overlap; partial output overlap is always rejected.

Backend checks ​

Typed/conversion channels use f64 scalars and separate status/result channels. Original f32 entry points continue rejecting wrong call families or dtypes. N-API validates actual array types, lengths and overlap; Wasm validates live allocations, dtype, length, scalar flags and operation signature. Kernels check scalars, shifts, division, masks, clamp, ddof and conversion policy. Integer division and checked conversion include a preflight traversal, including resident calls.

The added numeric types and conversions currently use scalar kernels. Use getCapability(operation, dtype) or getCapability('convert', source, target); simd: 'required' only constrains initialization. See support and compatibility for recorded backend coverage.

Released under the MIT License.