Module v2_array_detect 

Runtime detection and uniform access for v2 typed arrays.

v2 typed arrays are heap-allocated TypedArray<T> instances, where the element type T is monomorphized at compile time. The bytecode compiler emits typed allocation/push opcodes (e.g. NewTypedArrayF64, TypedArrayPushF64) that create the right TypedArray<T> instantiation.

However, generic consumer-side opcodes (Length, GetProp, SetProp, IterNext) and generic method dispatch (.len(), .first(), .last(), .clone(), .sum(), .push(), .map(), .filter()) only have a runtime (bits, NativeKind) pair to inspect — they need to recognize the v2 typed array pointer and dispatch to a typed implementation based on the element type.

Element type encoding

The compile-time element type is preserved at runtime by stamping the _pad byte (offset 7) of the HeapHeader with an ElemType discriminant. This piggybacks on existing layout — no struct change required.

Allocation handlers in array.rs stamp the byte after allocating; consumer paths in this module read the byte to dispatch.

ADR-006 §2.7.7 / Wave 6.5 cluster D-v2-array-detect

API surface uses the kinded (u64, NativeKind) carrier shape. v2 typed array pointers flow through the VM stack as raw *mut TypedArray<T> bits tagged with NativeKind::UInt64 (no Arc, no refcount — see v2_handlers/array.rs). Detection rejects any other kind. Element reads return the element’s native bit pattern paired with the element’s NativeKind (Float64 / Int64 / Int32 / Bool). Writes accept the same pair, decode bits per kind, and reject incompatible kinds.

Structs

V2TypedArrayView

Enums

V2ElemType

Constants

ELEM_TYPE_BOOL

_pad-byte discriminant for TypedArray<u8> carrying bool elements.

ELEM_TYPE_CHAR

_pad-byte discriminant for TypedArray<char>.

ELEM_TYPE_DECIMAL

_pad-byte discriminant for TypedArray<*const DecimalObj>.

ELEM_TYPE_F32

_pad-byte discriminant for TypedArray<f32>.

ELEM_TYPE_F64

_pad-byte discriminant for TypedArray<f64>.

ELEM_TYPE_I8

_pad-byte discriminant for TypedArray<i8>.

ELEM_TYPE_I16

_pad-byte discriminant for TypedArray<i16>.

ELEM_TYPE_I32

_pad-byte discriminant for TypedArray<i32>.

ELEM_TYPE_I64

_pad-byte discriminant for TypedArray<i64>.

ELEM_TYPE_STRING

_pad-byte discriminant for TypedArray<*const StringObj>.

ELEM_TYPE_TYPED_OBJECT

_pad-byte discriminant for TypedArray<*const TypedObjectStorage>.

ELEM_TYPE_U8

_pad-byte discriminant for TypedArray<u8> carrying u8 elements.

ELEM_TYPE_U16

_pad-byte discriminant for TypedArray<u16>.

ELEM_TYPE_U32

_pad-byte discriminant for TypedArray<u32>.

ELEM_TYPE_UNKNOWN

_pad-byte discriminant for an unstamped / unknown element type.

Functions

all_elements

Check if all elements in a bool v2 typed array are true.

allocate_empty_typed_array

Allocate an empty TypedArray<T> for the given V2ElemType, initialised with capacity slots, length zero, and stamped with the matching element-type discriminant byte (§2.7.5 producer-side stamp). Returns the raw *mut u8 carrier pointer for wrapping into a Ptr(HeapKind::TypedArray) KindedSlot. Subsequent push_element calls grow the array.

any_elements

Check if any element in a bool v2 typed array is true.

as_v2_typed_array

Try to interpret a (bits, kind) pair as a v2 typed array pointer.

avg_elements

Compute the average (mean) of all elements of a numeric v2 typed array. Returns NaN for empty arrays. Returns (bits, NativeKind::Float64) always (mean of integer arrays is a float).

clone_array

Allocate a fresh v2 typed array, copy all elements from view, stamp elem_type, and return its raw pointer.

cmp_element_natural

Compare two elements of the SAME view by natural ordering.

concat_arrays

Concatenate two v2 typed arrays of the same element type. Returns the raw pointer to a freshly-allocated TypedArray<T> with a.len + b.len elements. Returns Err on element-type mismatch (per ADR-006 §2.7.5 stamp-at-compile-time: mixed-kind concat is structurally rejected, no coercion).

contains_element

Return true iff any element of view equals needle_bits under the element-type’s equality.

count_true_elements

Count true values in a bool v2 typed array. Returns (count, Int64).

diff_f64

Stride-1 consecutive differences (out[i] = src[i+1] - src[i]) over a v2 F64 typed array. Returns a fresh v2 TypedArray<f64> of length view.len - 1 (empty for len < 2). SIMD-accelerated via f64x4 for sufficiently large inputs (PC.2).

dot_elements

Compute the dot product of two float v2 typed arrays.

drop_array_n

arr.drop(n) — all elements except the first n. n clamped to [0, view.len]. Named drop_array_n to avoid collision with TypedArray::drop_array (the allocator destructor).

eq_element

Per-kind value equality for the (bits, kind) carrier shape.

max_elements

Compute the maximum element of a numeric v2 typed array.

min_elements

Compute the minimum element of a numeric v2 typed array.

native_kind_to_v2_elem_type

Map a NativeKind to its corresponding V2ElemType for HOF-builder output-array allocation. Returns None for kinds with no monomorphized TypedArray<T> carrier (e.g. Null, Ptr(Closure), generic Ptr(HeapKind::HashMap)). Pairs with allocate_empty_typed_array + push_element to build a result array element-by-element.

norm_elements

Compute the Euclidean norm of a float v2 typed array.

permute_array

Materialize a permutation of view into a fresh TypedArray<T> of the same element kind. indices[i] selects the source element at position i of the output. Indices out of range [0, view.len) are skipped (defensive — callers should validate up front; out-of-range indices indicate a sort comparator bug, not a user-input edge).

pop_element

Pop the last element from a v2 typed array, returning (bits, NativeKind).

position_of

Return the first index i where view[i] == needle under the element-type’s equality, or None if no element matches.

push_element

Append (bits, kind) to a v2 typed array.

read_element

Read element index from a v2 typed array, returning (bits, NativeKind).

reverse_array

Produce a reversed copy of view. Kind-generic over the 14 V2ElemType variants. For heap-element variants (String / Decimal / TypedObject) the new array’s pointers share the same heap targets as the source; each is retained per-element so both arrays own valid shares.

slice_array

arr.slice(start, end) — bounded copy of [start..end). start and end are clamped to [0, view.len]; if start >= end, the result is empty. Mirrors Rust’s slice::get(range) clamping behaviour.

stamp_elem_type^⚠

Stamp the element type byte (_pad at offset 7 of the HeapHeader) on a freshly-allocated v2 typed array.

std_elements

Compute the sample standard deviation of a float v2 typed array.

sum_elements

Sum all elements of a numeric (F64/I64/I32) v2 typed array.

take_array

arr.take(n) — first n elements. n clamped to [0, view.len].

unary_f64_transform

Apply a unary element-wise f64 transform to view, returning a newly allocated v2 TypedArray<f64> pointer with ELEM_TYPE_F64 stamped.

variance_elements

Compute the sample variance of a float v2 typed array. Returns NaN for arrays with fewer than 2 elements. Always returns Float64.

write_element

Write (bits, kind) to element index of a v2 typed array.