Struct Value 

pub struct Value { /* private fields */ }

An entry on the stack.

Implementations

impl Value

pub fn take(value: &mut Self) -> Self

Take a mutable value, replacing the original location with an empty value.

pub fn new<T>(data: T) -> Result<Self>

where T: Any,

Construct a value from a type that implements Any which owns the underlying value.

pub unsafe fn from_ref<T>(data: &T) -> Result<(Self, ValueRefGuard)>

where T: Any,

Construct an Any that wraps a pointer.

Safety

Caller must ensure that the returned Value doesn’t outlive the reference it is wrapping.

This would be an example of incorrect use:

use rune::Any;
use rune::runtime::Value;

#[derive(Any)]
struct Foo(u32);

let mut v = Foo(1u32);

unsafe {
    let (any, guard) = unsafe { Value::from_ref(&v)? };
    drop(v);
    // any use of `any` beyond here is undefined behavior.
}

Examples

use rune::Any;
use rune::runtime::Value;

#[derive(Any)]
struct Foo(u32);

let mut v = Foo(1u32);

unsafe {
    let (any, guard) = Value::from_ref(&mut v)?;
    let b = any.borrow_ref::<Foo>()?;
    assert_eq!(b.0, 1u32);
}

pub unsafe fn from_mut<T>(data: &mut T) -> Result<(Self, ValueMutGuard)>

where T: Any,

Construct a value that wraps a mutable pointer.

Safety

Caller must ensure that the returned Value doesn’t outlive the reference it is wrapping.

This would be an example of incorrect use:

use rune::Any;
use rune::runtime::Value;

#[derive(Any)]
struct Foo(u32);

let mut v = Foo(1u32);
unsafe {
    let (any, guard) = Value::from_mut(&mut v)?;
    drop(v);
    // any use of value beyond here is undefined behavior.
}

Examples

use rune::Any;
use rune::runtime::Value;

#[derive(Any)]
struct Foo(u32);

let mut v = Foo(1u32);

unsafe {
    let (any, guard) = Value::from_mut(&mut v)?;

    if let Ok(mut v) = any.borrow_mut::<Foo>() {
        v.0 += 1;
    }

    drop(guard);
    assert!(any.borrow_mut::<Foo>().is_err());
    drop(any);
}

assert_eq!(v.0, 2);

pub fn is_writable(&self) -> bool

Test if the value is writable.

Examples

use rune::{Any, Value};

#[derive(Any)]
struct Struct(u32);

let value = Value::new(Struct(42))?;

{
    assert!(value.is_writable());

    let borrowed = value.borrow_mut::<Struct>()?;
    assert!(!value.is_writable());
    drop(borrowed);
    assert!(value.is_writable());
}

let foo = Struct(42);

{
    let (value, guard) = unsafe { Value::from_ref(&foo)? };
    assert!(value.is_readable());
    assert!(!value.is_writable());
}

let mut foo = Struct(42);

{
    let (value, guard) = unsafe { Value::from_mut(&mut foo)? };
    assert!(value.is_readable());
    assert!(value.is_writable());
}

pub fn is_readable(&self) -> bool

Test if a value is readable.

Examples

use rune::{Any, Value};

#[derive(Any)]
struct Struct(u32);

let value = Value::new(Struct(42))?;

{
    assert!(value.is_writable());

    let borrowed = value.borrow_mut::<Struct>()?;
    assert!(!value.is_writable());
    drop(borrowed);
    assert!(value.is_writable());
}

let foo = Struct(42);

{
    let (value, guard) = unsafe { Value::from_ref(&foo)? };
    assert!(value.is_readable());
    assert!(!value.is_writable());
}

let mut foo = Struct(42);

{
    let (value, guard) = unsafe { Value::from_mut(&mut foo)? };
    assert!(value.is_readable());
    assert!(value.is_writable());
}

pub const fn empty() -> Self

Construct an empty value.

pub fn display_fmt(&self, f: &mut Formatter) -> Result<(), VmError>

Format the value using the DISPLAY_FMT protocol.

You must use Vm::with to specify which virtual machine this function is called inside.

Errors

This function errors if called outside of a virtual machine.

pub fn clone_(&self) -> Result<Self, VmError>

Perform a shallow clone of the value using the CLONE protocol.

You must use Vm::with to specify which virtual machine this function is called inside.

Errors

This function errors if called outside of a virtual machine.

pub fn debug_fmt(&self, f: &mut Formatter) -> Result<(), VmError>

Debug format the value using the DEBUG_FMT protocol.

You must use Vm::with to specify which virtual machine this function is called inside.

Errors

This function errors if called outside of a virtual machine.

pub fn into_iter(self) -> Result<Iterator, VmError>

Convert value into an iterator using the Protocol::INTO_ITER protocol.

You must use Vm::with to specify which virtual machine this function is called inside.

Errors

This function will error if called outside of a virtual machine context.

pub fn into_type_name(self) -> Result<String, VmError>

Retrieves a human readable type name for the current value.

You must use Vm::with to specify which virtual machine this function is called inside.

Errors

This function errors in case the provided type cannot be converted into a name without the use of a Vm and one is not provided through the environment.

pub fn vec(vec: Vec<Value>) -> Result<Self>

Construct a vector.

pub fn tuple(vec: Vec<Value>) -> Result<Self>

Construct a tuple.

pub fn empty_struct(rtti: Arc<Rtti>) -> Result<Self>

Construct an empty.

pub fn tuple_struct( rtti: Arc<Rtti>, data: impl IntoIterator<IntoIter: ExactSizeIterator, Item = Value>, ) -> Result<Self>

Construct a typed tuple.

pub fn as_usize(&self) -> Result<usize, RuntimeError>

Try to coerce value into a usize.

pub fn as_string(&self) -> Result<BorrowRef<'_, str>, RuntimeError>

👎Deprecated:

For consistency with other methods, this has been renamed Value::borrow_string_ref

Get the value as a string.

pub fn borrow_string_ref(&self) -> Result<BorrowRef<'_, str>, RuntimeError>

Borrow the interior value as a string reference.

pub fn into_string(self) -> Result<String, RuntimeError>

Take the current value as a string.

pub fn into_unit(&self) -> Result<(), RuntimeError>

Coerce into a unit.

pub fn as_ordering(&self) -> Result<Ordering, RuntimeError>

Coerce into Ordering.

This gets a copy of the value.

pub fn as_ordering_mut(&mut self) -> Result<&mut Ordering, RuntimeError>

Coerce into Ordering.

This gets the value by mutable reference.

pub fn as_hash(&self) -> Result<Hash, RuntimeError>

Coerce into Hash.

This gets a copy of the value.

pub fn as_hash_mut(&mut self) -> Result<&mut Hash, RuntimeError>

Coerce into Hash.

This gets the value by mutable reference.

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

Coerce into bool.

This gets a copy of the value.

pub fn as_bool_mut(&mut self) -> Result<&mut bool, RuntimeError>

Coerce into bool.

This gets the value by mutable reference.

pub fn as_char(&self) -> Result<char, RuntimeError>

Coerce into char.

This gets a copy of the value.

pub fn as_char_mut(&mut self) -> Result<&mut char, RuntimeError>

Coerce into char.

This gets the value by mutable reference.

pub fn as_signed(&self) -> Result<i64, RuntimeError>

Coerce into i64 integer.

This gets a copy of the value.

pub fn as_signed_mut(&mut self) -> Result<&mut i64, RuntimeError>

Coerce into i64 integer.

This gets the value by mutable reference.

pub fn as_unsigned(&self) -> Result<u64, RuntimeError>

Coerce into u64 unsigned integer.

This gets a copy of the value.

pub fn as_unsigned_mut(&mut self) -> Result<&mut u64, RuntimeError>

Coerce into u64 unsigned integer.

This gets the value by mutable reference.

pub fn as_float(&self) -> Result<f64, RuntimeError>

Coerce into f64 float.

This gets a copy of the value.

pub fn as_float_mut(&mut self) -> Result<&mut f64, RuntimeError>

Coerce into f64 float.

This gets the value by mutable reference.

pub fn as_type(&self) -> Result<Type, RuntimeError>

Coerce into Type.

This gets a copy of the value.

pub fn as_type_mut(&mut self) -> Result<&mut Type, RuntimeError>

Coerce into Type.

This gets the value by mutable reference.

pub fn borrow_tuple_ref(&self) -> Result<BorrowRef<'_, Tuple>, RuntimeError>

Borrow as a tuple.

This ensures that the value has read access to the underlying value and does not consume it.

pub fn borrow_tuple_mut(&self) -> Result<BorrowMut<'_, Tuple>, RuntimeError>

Borrow as a tuple as mutable.

This ensures that the value has write access to the underlying value and does not consume it.

pub fn into_tuple(&self) -> Result<Box<Tuple>, RuntimeError>

Borrow as an owned tuple reference.

This ensures that the value has read access to the underlying value and does not consume it.

pub fn into_tuple_ref(&self) -> Result<Ref<Tuple>, RuntimeError>

Borrow as an owned tuple reference.

This ensures that the value has read access to the underlying value and does not consume it.

pub fn into_tuple_mut(&self) -> Result<Mut<Tuple>, RuntimeError>

Borrow as an owned tuple mutable.

This ensures that the value has write access to the underlying value and does not consume it.

pub fn into_any_obj(self) -> Result<AnyObj, RuntimeError>

Coerce into an AnyObj.

pub fn into_shared<T>(self) -> Result<Shared<T>, RuntimeError>

where T: Any,

Coerce into a Shared<T>.

This type checks and coerces the value into a type which statically guarantees that the underlying type is of the given type.

pub fn into_future(self) -> Result<Future, RuntimeError>

Coerce into a future, or convert into a future using the Protocol::INTO_FUTURE protocol.

You must use Vm::with to specify which virtual machine this function is called inside.

Errors

This function errors in case the provided type cannot be converted into a future without the use of a Vm and one is not provided through the environment.

pub fn into_any_ref_ptr<T>( self, ) -> Result<(NonNull<T>, RawValueGuard), RuntimeError>

where T: Any,

Try to coerce value into a typed reference.

Safety

The returned pointer is only valid to dereference as long as the returned guard is live.

pub fn downcast<T>(self) -> Result<T, RuntimeError>

where T: Any,

Downcast the value into a stored value that implements Any.

This takes the interior value, making it inaccessible to other owned references.

You should usually prefer to use rune::from_value instead of this directly.

Examples

use rune::Value;
use rune::alloc::String;

let a = Value::try_from("Hello World")?;
let b = a.clone();

assert!(b.borrow_ref::<String>().is_ok());

// NB: The interior representation of the stored string is from rune-alloc.
let a = a.downcast::<String>()?;

assert!(b.borrow_ref::<String>().is_err());

assert_eq!(a, "Hello World");

pub fn borrow_ref<T>(&self) -> Result<BorrowRef<'_, T>, RuntimeError>

where T: Any,

Borrow the value as a typed reference of type T.

Examples

use rune::Value;
use rune::alloc::String;

let a = Value::try_from("Hello World")?;
let b = a.clone();

assert!(b.borrow_ref::<String>().is_ok());

// NB: The interior representation of the stored string is from rune-alloc.
let a = a.downcast::<String>()?;

assert!(b.borrow_ref::<String>().is_err());

assert_eq!(a, "Hello World");

pub fn into_ref<T>(self) -> Result<Ref<T>, RuntimeError>

where T: Any,

Try to coerce value into a typed reference of type T.

You should usually prefer to use rune::from_value instead of this directly.

Examples

use rune::Value;
use rune::alloc::String;

let mut a = Value::try_from("Hello World")?;
let b = a.clone();

assert_eq!(a.into_ref::<String>()?.as_str(), "Hello World");
assert_eq!(b.into_ref::<String>()?.as_str(), "Hello World");

pub fn borrow_mut<T>(&self) -> Result<BorrowMut<'_, T>, RuntimeError>

where T: Any,

Try to borrow value into a typed mutable reference of type T.

pub fn into_mut<T>(self) -> Result<Mut<T>, RuntimeError>

where T: Any,

Try to coerce value into a typed mutable reference of type T.

You should usually prefer to use rune::from_value instead of this directly since it supports transparently coercing into types like Mut<str>.

Examples

use rune::{Mut, Value};
use rune::alloc::String;

let mut a = Value::try_from("Hello World")?;
let b = a.clone();

fn modify_string(mut s: Mut<String>) {
    assert_eq!(s.as_str(), "Hello World");
    s.make_ascii_lowercase();
    assert_eq!(s.as_str(), "hello world");
}

modify_string(a.into_mut::<String>()?);

assert_eq!(b.borrow_mut::<String>()?.as_str(), "hello world");

pub fn type_hash(&self) -> Hash

Get the type hash for the current value.

One notable feature is that the type of a variant is its container enum, and not the type hash of the variant itself.

pub fn type_info(&self) -> TypeInfo

Get the type information for the current value.

pub fn partial_eq(a: &Value, b: &Value) -> Result<bool, VmError>

Perform a partial equality test between two values.

This is the basis for the eq operation (partial_eq / ‘==’).

External types will use the Protocol::PARTIAL_EQ protocol when invoked through this function.

Errors

This function will error if called outside of a virtual machine context.

pub fn eq(&self, b: &Value) -> Result<bool, VmError>

Perform a total equality test between two values.

This is the basis for the eq operation (==).

External types will use the Protocol::EQ protocol when invoked through this function.

Errors

This function will error if called outside of a virtual machine context.

pub fn partial_cmp(a: &Value, b: &Value) -> Result<Option<Ordering>, VmError>

Perform a partial ordering comparison between two values.

This is the basis for the comparison operation.

External types will use the Protocol::PARTIAL_CMP protocol when invoked through this function.

Errors

This function will error if called outside of a virtual machine context.

pub fn cmp(a: &Value, b: &Value) -> Result<Ordering, VmError>

Perform a total ordering comparison between two values.

This is the basis for the comparison operation (cmp).

External types will use the Protocol::CMP protocol when invoked through this function.

Errors

This function will error if called outside of a virtual machine context.

pub fn hash(&self, hasher: &mut Hasher) -> Result<(), VmError>

Hash the current value.

pub fn as_integer<T>(&self) -> Result<T, RuntimeError>

where T: TryFrom<u64> + TryFrom<i64>,

Try to coerce the current value as the specified integer T.

Examples

let value = rune::to_value(u32::MAX)?;

assert_eq!(value.as_integer::<u64>()?, u32::MAX as u64);
assert!(value.as_integer::<i32>().is_err());

pub fn as_any(&self) -> Option<&AnyObj>

Coerce into a checked AnyObj object.

Any empty value will cause an access error.

Trait Implementations

impl Clone for Value

fn clone(&self) -> Self

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<'de> Deserialize<'de> for Value

Available on crate feature serde only.

Deserialize implementation for value pointers.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Dismantle for Value

A value is the leaf of the walk: it is handed over as it is, unless it cannot contain other values, in which case there is nothing to hand over.

This is what makes handing a field over the same call whatever the field holds, which is what the derive writes.

fn dismantle(&mut self, out: &mut Handover<'_>)

Hand over every value this is made of, leaving nothing behind which is itself made of values.

impl Drop for Value

A graph of values is taken apart in place rather than by recursing into it, since how deeply one nests is decided at runtime and dropping it by recursing would exhaust the call stack.

A destructor has nobody to report a failure to and must not spend the memory limit which is in effect, so it takes the graph apart without allocating. The machine hands the values over to a worklist instead, which is faster and reports running into the limit rather than working around it.

See the dismantle module for how the graph is walked.

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 From<()> for Value

fn from((): ()) -> Self

Converts to this type from the input type.

impl From<AnyObj> for Value

Conversion from a AnyObj into a Value.

Examples

use rune::Value;
use rune::runtime::AnyObj;
use rune::alloc::String;

let string = String::try_from("Hello World")?;
let string = AnyObj::new(string)?;
let string = Value::from(string);

let string = string.into_shared::<String>()?;
assert_eq!(string.borrow_ref()?.as_str(), "Hello World");

fn from(value: AnyObj) -> Self

Converts to this type from the input type.

impl From<Hash> for Value

fn from(value: Hash) -> Self

Converts to this type from the input type.

impl From<Inline> for Value

fn from(value: Inline) -> Self

Converts to this type from the input type.

impl From<Ordering> for Value

fn from(value: Ordering) -> Self

Converts to this type from the input type.

impl<T> From<Shared<T>> for Value

where T: Any,

Conversion from a Shared<T> into a Value.

Examples

use rune::Value;
use rune::runtime::Shared;
use rune::alloc::String;

let string = String::try_from("Hello World")?;
let string = Shared::new(string)?;
let string = Value::from(string);

let string = string.into_any_obj()?;
assert_eq!(string.borrow_ref::<String>()?.as_str(), "Hello World");

fn from(value: Shared<T>) -> Self

Converts to this type from the input type.

impl From<Type> for Value

fn from(value: Type) -> Self

Converts to this type from the input type.

impl From<bool> for Value

fn from(value: bool) -> Self

Converts to this type from the input type.

impl From<char> for Value

fn from(value: char) -> Self

Converts to this type from the input type.

impl From<f32> for Value

fn from(value: f32) -> Value

Converts to this type from the input type.

impl From<f64> for Value

fn from(value: f64) -> Self

Converts to this type from the input type.

impl From<i8> for Value

fn from(number: i8) -> Self

Converts to this type from the input type.

impl From<i16> for Value

fn from(number: i16) -> Self

Converts to this type from the input type.

impl From<i32> for Value

fn from(number: i32) -> Self

Converts to this type from the input type.

impl From<i64> for Value

fn from(value: i64) -> Self

Converts to this type from the input type.

impl From<u8> for Value

fn from(number: u8) -> Self

Converts to this type from the input type.

impl From<u16> for Value

fn from(number: u16) -> Self

Converts to this type from the input type.

impl From<u32> for Value

fn from(number: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Value

fn from(value: u64) -> Self

Converts to this type from the input type.

impl FromValue for Value

fn from_value(value: Value) -> Result<Self, RuntimeError>

Try to convert to the given type, from the given value.

impl IntoOutput for Value

impl MaybeTypeOf for Value

fn maybe_type_of() -> Result<DocType>

Type information for the given type.

impl Serialize for Value

Available on crate feature serde only.

Serialize implementation for value pointers.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl ToConstValue for Value

fn to_const_value(self) -> Result<ConstValueBuf, RuntimeError>

Convert into a constant value.

impl ToValue for Value

fn to_value(self) -> Result<Value, RuntimeError>

Convert into a value.

impl ToValue for &Value

fn to_value(self) -> Result<Value, RuntimeError>

Convert into a value.

impl TryClone for Value

fn try_clone(&self) -> Result<Self>

Try to clone the current value, raising an allocation error if it’s unsuccessful.

fn try_clone_from(&mut self, source: &Self) -> Result<(), Error>

Performs copy-assignment from source.

impl TryFrom<&[u8]> for Value

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &[u8]) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&str> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Bytes> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<ControlFlow> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Format> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Function> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Future> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Generator> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<GeneratorState> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Object> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Option<Value>> for Value

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Option<Value>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<OwnedTuple> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Result<Value, Value>> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Stream> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<String> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Vec> for Value

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<i128> for Value

type Error = RuntimeError

The type returned in the event of a conversion error.

fn try_from(value: i128) -> Result<Self, RuntimeError>

Performs the conversion.

impl TryFrom<isize> for Value

type Error = RuntimeError

The type returned in the event of a conversion error.

fn try_from(value: isize) -> Result<Self, RuntimeError>

Performs the conversion.

impl TryFrom<u128> for Value

type Error = RuntimeError

The type returned in the event of a conversion error.

fn try_from(value: u128) -> Result<Self, RuntimeError>

Performs the conversion.

impl TryFrom<usize> for Value

type Error = RuntimeError

The type returned in the event of a conversion error.

fn try_from(value: usize) -> Result<Self, RuntimeError>

Performs the conversion.

impl TryFromIteratorIn<Value, Global> for Stack

fn try_from_iter_in<T: IntoIterator<Item = Value>>( iter: T, alloc: Global, ) -> Result<Self>

Creates a value from an iterator within an allocator.

impl TryFromIteratorIn<Value, Global> for OwnedTuple

fn try_from_iter_in<T: IntoIterator<Item = Value>>( iter: T, alloc: Global, ) -> Result<Self>

Creates a value from an iterator within an allocator.