Enum VmValue 

pub enum VmValue {
    Int(i64),
    Float(f64),
    Decimal(Decimal),
    String(Arc<str>),
    Bytes(Arc<Vec<u8>>),
    Bool(bool),
    Nil,
    List(Arc<Vec<VmValue>>),
    Dict(Arc<DictMap>),
    Closure(Arc<VmClosure>),
    BuiltinRef(Arc<str>),
    BuiltinRefId(Arc<VmBuiltinRefId>),
    Duration(i64),
    EnumVariant(Arc<VmEnumVariant>),
    StructInstance {
        layout: Arc<StructLayout>,
        fields: Arc<Vec<Option<VmValue>>>,
    },
    TaskHandle(Arc<str>),
    Channel(Arc<VmChannelHandle>),
    Atomic(Arc<VmAtomicHandle>),
    Rng(Arc<VmRngHandle>),
    SyncPermit(Arc<VmSyncPermitHandle>),
    McpClient(Arc<VmMcpClientHandle>),
    Set(Arc<Vec<VmValue>>),
    Generator(Arc<VmGenerator>),
    Stream(Arc<VmStream>),
    Range(Arc<VmRange>),
    Iter(VmIterHandle),
    Pair(Arc<(VmValue, VmValue)>),
    Harness(Arc<VmHarness>),
}

VM runtime value.

Rare compound payloads use shared pointers so stack/local-slot traffic is bounded by the common scalar and pointer-sized value shapes. The two oversized inline payloads — Range (a 24-byte start/end/inclusive triple) and BuiltinRefId (an id + Arc<str> name) — are boxed behind a Shared pointer so no variant exceeds a fat pointer. That keeps VmValue at 24 bytes (down from 32) without inflating the common Int / Float / List / Dict / String shapes the interpreter moves on every push, pop, clone, and local-slot write. Unsafe layouts such as NaN boxing or tagged pointers are deliberately deferred until Harn has a stronger object/heap story.

Variants

Int(i64)

Float(f64)

Decimal(Decimal)

Exact base-10 decimal (96-bit mantissa, up to 28–29 significant digits) for money and other values where binary float rounding is unacceptable. Inline (rust_decimal::Decimal is Copy and 16 bytes, the same width as the existing widest variants). Constructed via the decimal(value) builtin; it is a distinct type from Int/Float for equality/ordering/hashing (a clean island) but promotes Int operands exactly in arithmetic. See docs/src/decimal.md.

String(Arc<str>)

Bytes(Arc<Vec<u8>>)

Bool(bool)

Nil

List(Arc<Vec<VmValue>>)

Dict(Arc<DictMap>)

Closure(Arc<VmClosure>)

BuiltinRef(Arc<str>)

Reference to a registered builtin function, used when a builtin name is referenced as a value (e.g. snake_dict.rekey(snake_to_camel)). The contained string is the builtin’s registered name.

BuiltinRefId(Arc<VmBuiltinRefId>)

Compact builtin reference for callback positions. The boxed VmBuiltinRefId carries the id plus the name for policy, diagnostics, and fallback if the ID cannot be used. Boxed so the { id, name } pair does not widen every VmValue.

Duration(i64)

EnumVariant(Arc<VmEnumVariant>)

StructInstance

Fields

layout: Arc<StructLayout>

fields: Arc<Vec<Option<VmValue>>>

TaskHandle(Arc<str>)

Channel(Arc<VmChannelHandle>)

Atomic(Arc<VmAtomicHandle>)

Rng(Arc<VmRngHandle>)

SyncPermit(Arc<VmSyncPermitHandle>)

McpClient(Arc<VmMcpClientHandle>)

Set(Arc<Vec<VmValue>>)

Generator(Arc<VmGenerator>)

Stream(Arc<VmStream>)

Range(Arc<VmRange>)

Lazy numeric range. Boxed behind a Shared pointer so its 24-byte start/end/inclusive payload does not set the whole-enum size; cloning a range value is then a refcount bump.

Iter(VmIterHandle)

Lazy iterator handle. Single-pass, fused. See crate::vm::iter::VmIter.

Pair(Arc<(VmValue, VmValue)>)

Two-element pair value. Produced by pair(a, b), yielded by the Dict iterator source, and (later) by zip / enumerate combinators. Accessed via .first / .second, and destructurable in for (a, b) in ... loops.

Harness(Arc<VmHarness>)

Capability handle threaded into main(harness: Harness). The same variant carries the root handle and each typed sub-handle (stdio, clock, fs, env, random, net) so they share one value shape but stay distinguishable via VmHarness::kind.

Implementations

impl VmValue

pub fn string(value: impl AsRef<str>) -> Self

Canonical VmValue::String constructor from anything string-like.

Collapses the ubiquitous VmValue::String(std::sync::Arc::from(..)) spelling to a single call and performs exactly one allocation via Arc::<str>::from(&str) regardless of whether the input is a &str, String, &String, or Cow<str>. Prefer this over hand-writing the Arc::from at call sites.

pub fn char_value(ch: char) -> Self

Builds a VmValue::String holding a single character, reusing the interned ASCII table (see [ASCII_CHAR_STRINGS]) so the common ASCII path does not allocate.

pub fn chars_list(text: &str) -> Self

Materializes a string into a VmValue::List of single-character string values in one linear pass. Backs both the chars builtin and the .chars() method, and is the cursor-scanner-friendly counterpart to the O(n)-per-call substring / slice / s[i] operations on a string.

pub fn enum_variant( enum_name: impl Into<Arc<str>>, variant: impl Into<Arc<str>>, fields: Vec<VmValue>, ) -> Self

pub fn task_handle(id: impl Into<Arc<str>>) -> Self

pub fn range(range: VmRange) -> Self

Construct a boxed VmValue::Range from a VmRange.

pub fn builtin_ref_id(id: BuiltinId, name: impl Into<Arc<str>>) -> Self

Construct a boxed VmValue::BuiltinRefId from its id and name.

pub fn dict(entries: impl IntoIterator<Item = (String, VmValue)>) -> Self

Construct a VmValue::Dict from any iterator of (key, value) entries. Accepts the BTreeMap that most builders still assemble (it is IntoIterator<Item = (String, VmValue)>) and collects it into the persistent DictMap, so callers keep their familiar map-building code while the stored value gains structural sharing.

pub fn dict_map(map: DictMap) -> Self

Construct a VmValue::Dict from an already-built DictMap.

pub fn channel(handle: VmChannelHandle) -> Self

pub fn atomic(handle: VmAtomicHandle) -> Self

pub fn rng(handle: VmRngHandle) -> Self

pub fn sync_permit(handle: VmSyncPermitHandle) -> Self

pub fn mcp_client(handle: VmMcpClientHandle) -> Self

pub fn generator(generator: VmGenerator) -> Self

pub fn stream(stream: VmStream) -> Self

pub fn harness(handle: VmHarness) -> Self

pub fn struct_instance( struct_name: impl Into<Arc<str>>, fields: DictMap, ) -> Self

pub fn is_truthy(&self) -> bool

pub fn type_name(&self) -> &'static str

pub fn as_str_cow(&self) -> Cow<'_, str>

Borrows the string contents without allocating when the value is already a string. Non-string values are rendered with display(), matching the coercion callers apply at string boundaries. Hot string builtins (regex, split, contains) use this to avoid cloning the subject text on every call.

pub fn struct_name(&self) -> Option<&str>

pub fn struct_field(&self, field_name: &str) -> Option<&VmValue>

pub fn struct_fields_map(&self) -> Option<DictMap>

pub fn struct_instance_from_map( struct_name: impl Into<String>, fields: DictMap, ) -> Self

pub fn struct_instance_with_layout( struct_name: impl Into<String>, field_names: Vec<String>, field_values: DictMap, ) -> Self

pub fn struct_instance_with_property( &self, field_name: &str, value: VmValue, ) -> Option<Self>

pub fn display(&self) -> String

pub fn write_display(&self, out: &mut String)

Writes the display representation directly into out, avoiding intermediate Vec allocations for collections.

pub fn as_dict(&self) -> Option<&DictMap>

Get the value as a DictMap reference, if it’s a Dict.

pub fn as_int(&self) -> Option<i64>

pub fn as_bytes(&self) -> Option<&[u8]>

Trait Implementations

impl Clone for VmValue

fn clone(&self) -> VmValue

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for VmValue

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

Formats the value using the given formatter.