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, VmResult};

#[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.

pub fn is_readable(&self) -> bool

Test if the value is readable.

pub const fn empty() -> Self

Construct an empty value.

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

Format the value using the Protocol::DISPLAY_FMT protocol.

Requires a work buffer buf which will be used in case the value provided requires out-of-line formatting. This must be cleared between calls and can be re-used.

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

Panics

This function will panic if called outside of a virtual machine.

pub fn clone_(&self) -> VmResult<Self>

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

This requires read access to the underlying value.

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

Panics

This function will panic if called outside of a virtual machine.

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

Debug format the value using the DEBUG_FMT protocol.

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

Panics

This function will panic if called outside of a virtual machine.

pub fn into_iter(self) -> VmResult<Iterator>

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) -> VmResult<String>

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_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.

This consumes the underlying value.

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) -> VmResult<bool>

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) -> VmResult<bool>

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) -> VmResult<Option<Ordering>>

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) -> VmResult<Ordering>

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) -> VmResult<()>

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());

Trait Implementations

impl Clone for Value

fn clone(&self) -> Self

Returns a copy 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

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

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

Converts to this type from the input type.

impl From<AnyObj> for Value

fn from(value: AnyObj) -> 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 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<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<i8> for Value

fn from(number: i8) -> 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 From<u8> for Value

fn from(number: u8) -> 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

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

Coerce the current value into an output.

impl MaybeTypeOf for Value

fn maybe_type_of() -> Result<DocType>

Type information for the given type.

impl Serialize for Value

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<ConstValue, RuntimeError>

Convert into a constant value.

fn construct() -> Option<Arc<dyn ConstConstruct>>

Return the constant constructor for the given type.

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 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.

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.