Struct Value 

pub struct Value { /* private fields */ }

A handle to a RayforceDB object (atom, vector, list, dict, table, …).

Confined to its scope

A Value points into the engine heap, and tearing the runtime down unmaps that heap — ray_runtime_destroy munmaps every pool without consulting any object’s reference count, so a surviving handle would point at unmapped address space, not at freed bytes. There is no check that could make such a handle safe to read; only never producing one can.

crate::Runtime::scope is what never produces one. The closure is handed a &Runtime it cannot drop, and its Send bounds reject a Value leaving by return or by capture — so every Value is dropped before the heap it lives in goes away.

Safety

!Send/!Sync, and must stay so — twice over. The core’s VM is thread-local, so a value on another thread would release against the wrong heap; and Runtime::scope’s bounds are spelled in terms of Send, so this marker is also what confines a value to its scope.

fn assert_send<T: Send>() {}
assert_send::<rayforce::Value>();

fn assert_sync<T: Sync>() {}
assert_sync::<rayforce::Value>();

Control — compile_fail passes on any build failure, a rename included:

fn assert_exists<T>() {}
assert_exists::<rayforce::Value>();

Implementations

impl Value

pub fn new<T: ToValue>(v: T) -> Value

Convenience: build a Value from any ToValue.

pub fn extract<T: FromValue>(&self) -> Result<T>

Convenience: extract any FromValue from this value.

impl Value

pub fn dict(keys: Value, values: Value) -> Value

Build a dict from a keys vector/list and a values vector/list.

Consumes both arguments (the core takes ownership of each).

pub fn is_dict(&self) -> bool

True if this value is a dictionary.

pub fn dict_keys(&self) -> Result<Value>

The keys collection (borrowed view).

pub fn dict_values(&self) -> Result<Value>

The values collection (borrowed view).

pub fn dict_len(&self) -> Result<usize>

Number of key/value pairs.

pub fn dict_get(&self, key: &Value) -> Result<Option<Value>>

Look up a key, returning the associated value if present.

impl Value

pub fn list(items: &[Value]) -> Value

Build a list from boxed values (each is retained by the list).

pub fn empty_list(capacity: i64) -> Value

An empty list with the given capacity.

pub fn is_list(&self) -> bool

True if this value is a heterogeneous list.

pub fn list_push(&mut self, item: &Value) -> Result<()>

Append a boxed value (the list retains it). Copy-on-write move semantics.

impl Value

pub fn bool(v: bool) -> Value

A boolean atom (-RAY_BOOL).

pub fn u8(v: u8) -> Value

An unsigned byte atom (-RAY_U8).

pub fn i16(v: i16) -> Value

A 16-bit signed integer atom (-RAY_I16).

pub fn i32(v: i32) -> Value

A 32-bit signed integer atom (-RAY_I32).

pub fn i64(v: i64) -> Value

A 64-bit signed integer atom (-RAY_I64).

pub fn f32(v: f32) -> Value

A 32-bit float atom (-RAY_F32).

pub fn f64(v: f64) -> Value

A 64-bit float atom (-RAY_F64).

pub fn sym(s: &str) -> Value

A symbol atom (-RAY_SYM): interns s in the global table.

pub fn string(s: &str) -> Value

A string atom (-RAY_STR).

pub fn name_ref(name: &str) -> Value

A symbol atom used as a name reference (column / global-env lookup): the ATTR_QUOTED flag is cleared so the query compiler resolves it by name rather than treating it as a literal symbol.

pub fn date_days(days: i32) -> Value

A date atom: raw days since 2000-01-01.

pub fn time_millis(ms: i32) -> Value

A time atom: raw milliseconds since midnight.

pub fn timestamp_nanos(ns: i64) -> Value

A timestamp atom: raw nanoseconds since 2000-01-01 UTC.

pub fn guid(bytes: &[u8; 16]) -> Value

A GUID atom from 16 raw bytes.

pub fn typed_null(abs_type: i8) -> Value

A typed null atom for the given canonical type id (e.g. sys::RAY_I64).

pub fn is_atom_null(&self) -> bool

True if this atom is a (typed or untyped) null.

pub fn as_bool(&self) -> Result<bool>

Read a boolean atom.

pub fn as_u8(&self) -> Result<u8>

Read an unsigned-byte atom.

pub fn as_i16(&self) -> Result<i16>

Read an i16 atom.

pub fn as_i32(&self) -> Result<i32>

Read an i32 atom.

pub fn as_i64(&self) -> Result<i64>

Read an i64 atom.

pub fn as_f32(&self) -> Result<f32>

Read an f32 atom.

pub fn as_f64(&self) -> Result<f64>

Read an f64 atom.

pub fn as_sym(&self) -> Result<String>

Read a symbol atom as an owned String.

pub fn as_string(&self) -> Result<String>

Read a string atom as an owned String.

pub fn as_date_days(&self) -> Result<i32>

Read a date atom as raw days since 2000-01-01.

pub fn as_time_millis(&self) -> Result<i32>

Read a time atom as raw milliseconds since midnight.

pub fn as_timestamp_nanos(&self) -> Result<i64>

Read a timestamp atom as raw nanoseconds since 2000-01-01 UTC.

pub fn as_guid(&self) -> Result<[u8; 16]>

Read a GUID atom as 16 raw bytes.

impl Value

pub fn is_table(&self) -> bool

True if this value is a table.

pub fn as_table(&self) -> Result<Table>

Interpret this value as a Table (cloning the handle).

impl Value

pub fn attrs(&self) -> u8

The value’s attribute byte.

Rarely needed — the typed accessors cover the normal cases. The exception is telling a keyed table apart from a plain list: it decodes as a 2-element list carrying RAY_ATTR_DICT, which no type code distinguishes.

pub fn null() -> Value

The untyped null singleton (RAY_NULL_OBJ).

__ray_null is a static in the C library, not a pool block, so it is unaffected by the heap’s teardown. Retain and release are no-ops for it in the core too.

pub fn type_code(&self) -> i8

The signed type tag (negative = atom, positive = vector, 0 = list, …).

pub fn abs_type(&self) -> i8

|type| — the canonical (unsigned) type id.

pub fn is_atom(&self) -> bool

True for atoms (scalars and function objects).

pub fn is_vec(&self) -> bool

True for homogeneous vectors (bool…str).

pub fn is_null(&self) -> bool

True if this is the null singleton.

pub fn len_raw(&self) -> i64

Element / pair count for vectors, lists, and dicts; for other objects the raw len field (not meaningful for atoms).

pub fn ref_count(&self) -> u32

Current core reference count (diagnostic).

pub fn format(&self) -> String

Pretty-print via the core formatter (ray_fmt).

pub fn serialize(&self) -> Result<Vec<u8>>

Serialize to a byte vector (core wire format with IPC header).

pub fn deserialize(bytes: &[u8]) -> Result<Value>

Deserialize a value from bytes previously produced by Value::serialize (or another Rayforce wire-format encoder).

impl Value

pub fn vec<T: VecElem>(data: &[T]) -> Value

Build a vector from a slice of fixed-width elements: a single memcpy, followed by one pass over the payload that raises HAS_NULLS if it already holds the type’s sentinel — see Value::is_null_at.

pub fn bool_vec(data: &[bool]) -> Value

Build a boolean vector (RAY_BOOL) from a slice of bool.

pub fn sym_vec<S: AsRef<str>>(items: &[S]) -> Value

Build a symbol vector, interning each string.

pub fn str_vec<S: AsRef<str>>(items: &[S]) -> Value

Build a string vector (RAY_STR).

pub fn empty_vec(abs_type: i8, capacity: i64) -> Value

Allocate an empty vector of the given canonical type with capacity.

pub fn len(&self) -> usize

Element count, for vectors / lists / dicts.

pub fn is_empty(&self) -> bool

True if the collection has zero elements.

pub fn as_slice<T: VecElem>(&self) -> Result<&[T]>

Zero-copy view of a fixed-width vector’s storage as &[T].

Errors if the vector’s element type doesn’t match T. The slice borrows self, so it cannot outlive the vector.

pub fn bool_slice(&self) -> Result<&[u8]>

Zero-copy view of a boolean vector’s storage (each byte is 0 or 1).

pub fn date_days_slice(&self) -> Result<&[i32]>

Zero-copy view of a date vector as raw days since 2000-01-01.

pub fn time_millis_slice(&self) -> Result<&[i32]>

Zero-copy view of a time vector as raw milliseconds since midnight.

pub fn timestamp_nanos_slice(&self) -> Result<&[i64]>

Zero-copy view of a timestamp vector as raw nanoseconds since 2000-01-01 UTC.

pub fn is_null_at(&self, idx: usize) -> bool

True if element idx is null.

Nulls are in-band. For the sentinel-encoded types (i16/i32/i64, f32/f64, date/time/timestamp, GUID) the core first consults the vector’s HAS_NULLS attribute — raised by Value::vec when the raw payload already holds a sentinel, and by Value::set_null — and only then compares the element against its sentinel (i64::MIN, NaN, the all-zero GUID, …). Symbol and string vectors skip the gate: the empty symbol and the empty string are their nulls. bool/u8 vectors are never null.

Because of the gate, a numeric sentinel written later through Value::set or Value::push is not reported here; the boxed atom still answers Value::is_atom_null, which is why to_vec::<Option<T>>() maps it to None either way. Use set_null to null an element.

pub fn get(&self, idx: usize) -> Result<Value>

Box element idx as a Value. Bounds-checked.

Null elements of the sentinel-encoded types (integers, floats, temporals, GUID) come back as the untyped null singleton (Value::is_null). Symbol and string vectors carry their null in-band, so an empty element comes back as the empty atom: Value::is_atom_null is true for it and Option<String> extraction yields None, while plain String extraction still succeeds.

pub fn to_vec<T: FromValue>(&self) -> Result<Vec<T>>

Collect all elements, converting each via crate::FromValue.

pub fn iter(&self) -> VecIter<'_>

Iterate over boxed elements.

pub fn set<T: VecElem>(&mut self, idx: usize, elem: T) -> Result<()>

Overwrite element idx with a fixed-width value.

pub fn push<T: VecElem>(&mut self, elem: T) -> Result<()>

Append a fixed-width value.

pub fn set_null(&mut self, idx: usize, is_null: bool) -> Result<()>

Mark element idx as null: writes the type’s sentinel into the payload (i64::MIN, NaN, symbol id 0, the empty string, the all-zero GUID) and raises HAS_NULLS so Value::is_null_at reports it. Rejected for bool/u8 vectors and for slices.

is_null = false is a no-op in the core — it cannot know the prior real value — so the sentinel stays and the element remains null until the caller overwrites it with Value::set.

pub fn slice(&self, offset: i64, len: i64) -> Result<Value>

A zero-copy sub-range view [offset, offset+len).

pub fn concat(&self, other: &Value) -> Result<Value>

Concatenate two vectors into a new one.

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.

impl Drop for Value

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl FromValue for Value

fn from_value(v: &Value) -> Result<Self>

impl IntoExpr for Value

fn into_expr(self) -> Expr

impl ToValue for Value

fn to_value(&self) -> Value