Enum Value 

pub enum Value {
    Int(i64),
    Float(f64),
    Bool(bool),
    String(Rc<String>),
    Bytes(Rc<RefCell<Vec<u8>>>),
    ByteSlice(Rc<Vec<u8>>),
    StrView(Rc<Vec<u8>>),
    U8(u8),
    Tensor(Tensor),
    SparseTensor(SparseCsr),
    Map(Rc<RefCell<DetMap>>),
    Array(Rc<Vec<Value>>),
    Struct {
        name: String,
        fields: BTreeMap<String, Value>,
    },
    Tuple(Rc<Vec<Value>>),
    ClassRef(GcRef),
    Fn(FnValue),
    Closure {
        fn_name: String,
        env: Vec<Value>,
        arity: usize,
    },
    Enum {
        enum_name: String,
        variant: String,
        fields: Vec<Value>,
    },
    Regex {
        pattern: String,
        flags: String,
    },
    Bf16(Bf16),
    F16(F16),
    Complex(ComplexF64),
    Scratchpad(Rc<RefCell<Scratchpad>>),
    PagedKvCache(Rc<RefCell<PagedKvCache>>),
    AlignedBytes(AlignedByteSlice),
    GradGraph(Rc<RefCell<dyn Any>>),
    OptimizerState(Rc<RefCell<dyn Any>>),
    TidyView(Rc<dyn Any>),
    GroupedTidyView(Rc<dyn Any>),
    VizorPlot(Rc<dyn Any>),
    QuantumState(Rc<RefCell<dyn Any>>),
    Na,
    Void,
}

The universal value type for the CJC interpreter.

Every runtime value – from scalars to tensors to closures – is represented as a variant of this enum. Both the AST interpreter (cjc-eval) and the MIR executor (cjc-mir-exec) operate on Value.

Clone Semantics

Cloning a Value is cheap for heap-backed variants: String, Array, Tuple, Map, Bytes, ByteSlice, and Tensor all use Rc internally, so clone() increments a refcount without copying data. Mutation (e.g., array_push) returns a new Value (functional immutability), or triggers COW when the Rc refcount is 1.

Display

All variants implement fmt::Display for user-facing output. The format matches CJC’s print() builtin behavior.

Variants

Int(i64)

64-bit signed integer.

Float(f64)

64-bit IEEE 754 float.

Bool(bool)

Boolean value.

String(Rc<String>)

Heap-allocated string with COW sharing via Rc.

Bytes(Rc<RefCell<Vec<u8>>>)

Owning byte buffer.

ByteSlice(Rc<Vec<u8>>)

Non-owning byte slice view. In the interpreter this is an owning snapshot (Vec) since we can’t borrow across eval boundaries. The compiler/MIR path can use true zero-copy slices.

StrView(Rc<Vec<u8>>)

Validated UTF-8 string view (same representation as ByteSlice but guaranteed valid UTF-8).

U8(u8)

Single byte value (u8).

Tensor(Tensor)

N-dimensional tensor backed by Buffer<f64>.

SparseTensor(SparseCsr)

Sparse matrix in CSR (Compressed Sparse Row) format.

Map(Rc<RefCell<DetMap>>)

Deterministic hash map with interior mutability. Iteration order is fixed by DetMap’s MurmurHash3-based bucket ordering.

Array(Rc<Vec<Value>>)

Copy-on-write array. Rc provides O(1) clone; Rc::make_mut() triggers a deep copy only when the array is mutated and shared.

Struct

Named struct with ordered fields. Field order is deterministic because fields are stored in a BTreeMap.

Fields

name: String

The struct type name (e.g., "Point").

fields: BTreeMap<String, Value>

Field name -> value mapping, ordered alphabetically.

Tuple(Rc<Vec<Value>>)

Copy-on-write tuple. Same COW semantics as Array.

ClassRef(GcRef)

Reference to a GC-managed class instance in the GcHeap.

Fn(FnValue)

A named function reference (not a closure – no captured environment).

Closure

A closure: a function name + captured environment values.

Fields

fn_name: String

env: Vec<Value>

arity: usize

Arity of the original lambda params (not including captures).

Enum

Enum variant value: Some(42), None, Ok(v), Err(e)

Fields

enum_name: String

variant: String

fields: Vec<Value>

Regex

Compiled regex pattern: (pattern, flags)

Fields

pattern: String

flags: String

Bf16(Bf16)

bf16 brain-float: u16-backed, deterministic f32 conversions

F16(F16)

f16 half-precision: u16-backed IEEE 754 binary16

Complex(ComplexF64)

Complex f64: deterministic fixed-sequence arithmetic

Scratchpad(Rc<RefCell<Scratchpad>>)

Pre-allocated KV-cache scratchpad for zero-allocation inference.

Runtime-only: No corresponding Type::Scratchpad exists. Created via Scratchpad.new() builtin. Type-checking treats it as opaque.

PagedKvCache(Rc<RefCell<PagedKvCache>>)

Block-paged KV-cache (vLLM-style).

Runtime-only: No corresponding Type::PagedKvCache exists. Created via PagedKvCache.new() builtin. Type-checking treats it as opaque.

AlignedBytes(AlignedByteSlice)

Aligned byte slice with 16-byte alignment guarantee.

Runtime-only: No corresponding Type::AlignedBytes exists. Created via AlignedByteSlice.from_bytes() builtin. Type-checking treats it as opaque.

GradGraph(Rc<RefCell<dyn Any>>)

Type-erased reverse-mode AD graph. Concrete type: cjc_ad::GradGraph. Uses Rc<RefCell<dyn Any>> because cjc-runtime cannot depend on cjc-ad. Construction and method dispatch happen in cjc-eval and cjc-mir-exec.

OptimizerState(Rc<RefCell<dyn Any>>)

Type-erased optimizer state. Concrete types: AdamState or SgdState (from ml.rs). Uses Rc<RefCell<dyn Any>> for interior mutability (step updates internal state).

TidyView(Rc<dyn Any>)

Type-erased tidy data view. Concrete type is cjc_data::TidyView. Wrapped in Rc<dyn Any> for cheap cloning without circular deps (cjc-runtime cannot depend on cjc-data).

Dispatch is handled by cjc_data::tidy_dispatch::dispatch_tidy_method.

GroupedTidyView(Rc<dyn Any>)

Type-erased grouped tidy view. Concrete type is cjc_data::GroupedTidyView. Same erasure strategy as TidyView.

VizorPlot(Rc<dyn Any>)

Type-erased Vizor plot specification. Concrete type is cjc_vizor::spec::PlotSpec. Same erasure strategy as TidyView.

Dispatch is handled by cjc_vizor::dispatch::dispatch_vizor_method.

QuantumState(Rc<RefCell<dyn Any>>)

Type-erased quantum state (circuit or statevector). Concrete type: cjc_quantum::Circuit or cjc_quantum::Statevector. Uses Rc<RefCell<dyn Any>> for interior mutability (measurement collapses state). Construction and method dispatch happen in cjc-eval and cjc-mir-exec.

Na

Missing value sentinel. Propagates through arithmetic (NA + x → NA), compares unequal to everything including itself (NA == NA → false). Test with is_na(). This is the only way to detect NA.

Void

Implementations

impl Value

pub fn type_name(&self) -> &str

Return a human-readable type name string for error messages and debugging.

The returned string matches the CJC type system names (e.g., "Int", "Float", "Tensor", "Array", "Struct", "Closure").

Trait Implementations

impl Clone for Value

fn clone(&self) -> Value

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Value

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Value

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.