Enum VmValue 

pub enum VmValue {
    Int(i64),
    Float(f64),
    Decimal(Arc<Decimal>),
    String(HarnStr),
    Bytes(Arc<Vec<u8>>),
    Bool(bool),
    Nil,
    List(Arc<Vec<VmValue>>),
    Dict(Arc<DictMap>),
    Closure(Arc<VmClosure>),
    BuiltinRef(HarnStr),
    BuiltinRefId(Arc<VmBuiltinRefId>),
    Duration(i64),
    EnumVariant(Arc<VmEnumVariant>),
    StructInstance(Arc<StructInstanceData>),
    TaskHandle(HarnStr),
    Channel(Arc<VmChannelHandle>),
    Atomic(Arc<VmAtomicHandle>),
    Rng(Arc<VmRngHandle>),
    SyncPermit(Arc<VmSyncPermitHandle>),
    McpClient(Arc<VmMcpClientHandle>),
    Set(Arc<VmSet>),
    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. Every variant is held to a single machine word (8 bytes): the oversized payloads — Range (a 24-byte triple), BuiltinRefId (id + name), Decimal (16-byte base-10 mantissa), and StructInstance (two pointers) — are boxed behind a Shared pointer, and the string-shaped variants use the thin-pointer HarnStr instead of a 16-byte Arc<str> fat pointer. That keeps VmValue at 16 bytes (down from 24, and 32 before that) 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 remain deferred; the thin string’s unsafe is encapsulated in the vetted arcstr crate.

Variants

Int(i64)

Float(f64)

Decimal(Arc<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. Boxed behind a Shared pointer (rust_decimal::Decimal is 16 bytes, so inlining it would set the whole-enum size); cloning is a refcount bump. 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(HarnStr)

Bytes(Arc<Vec<u8>>)

Bool(bool)

Nil

List(Arc<Vec<VmValue>>)

Dict(Arc<DictMap>)

Closure(Arc<VmClosure>)

BuiltinRef(HarnStr)

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(Arc<StructInstanceData>)

TaskHandle(HarnStr)

Channel(Arc<VmChannelHandle>)

Atomic(Arc<VmAtomicHandle>)

Rng(Arc<VmRngHandle>)

SyncPermit(Arc<VmSyncPermitHandle>)

McpClient(Arc<VmMcpClientHandle>)

Set(Arc<VmSet>)

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(arcstr::ArcStr::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 decimal(value: Decimal) -> Self

Canonical VmValue::Decimal constructor.

Boxes the 16-byte rust_decimal::Decimal behind a Shared pointer so the value stays one word wide; see VmValue::Decimal.

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<HarnStr>, variant: impl Into<HarnStr>, fields: Vec<VmValue>, ) -> Self

pub fn task_handle(id: impl Into<HarnStr>) -> 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<HarnStr>) -> Self

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

pub fn dict<K: IntoDictKey>( entries: impl IntoIterator<Item = (K, 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 set(values: impl IntoIterator<Item = VmValue>) -> Self

Construct a VmValue::Set from any iterator of values, deduplicating by structural equality and preserving first-seen insertion order.

pub fn set_value(set: VmSet) -> Self

Construct a VmValue::Set from an already-built VmSet.

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_data(&self) -> Option<&StructInstanceData>

Borrows the boxed struct payload (layout + field slots) when this value is a struct instance. The single accessor most match sites use instead of destructuring the now-boxed variant.

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.

impl From<&ActorChain> for VmValue

fn from(chain: &ActorChain) -> Self

Converts to this type from the input type.

impl From<ActorChain> for VmValue

fn from(chain: ActorChain) -> Self

Converts to this type from the input type.

impl FromIterator<VmValue> for VmSet

fn from_iter<I: IntoIterator<Item = VmValue>>(iter: I) -> Self

Creates a value from an iterator.

impl TryFrom<&VmValue> for ActorChain

type Error = ActorChainError

The type returned in the event of a conversion error.

fn try_from(value: &VmValue) -> Result<Self, Self::Error>

Performs the conversion.