Struct rhai::Dynamic

pub struct Dynamic(_);

Dynamic type containing any value.

Implementations

impl Dynamic

pub const fn tag(&self) -> i32

Get the arbitrary data attached to this Dynamic.

pub fn set_tag(&mut self, value: i32)

Attach arbitrary data to this Dynamic.

pub const fn is_variant(&self) -> bool

Does this Dynamic hold a variant data type instead of one of the supported system primitive types?

pub const fn is_shared(&self) -> bool

Is the value held by this Dynamic shared?

Not available under no_closure.

pub fn is<T: Any + Clone>(&self) -> bool

Is the value held by this Dynamic a particular type?

If the Dynamic is a shared variant checking is performed on top of its internal value.

pub fn type_id(&self) -> TypeId

Get the TypeId of the value held by this Dynamic.

Panics or Deadlocks When Value is Shared

Under the sync feature, this call may deadlock, or panic. Otherwise, this call panics if the data is currently borrowed for write.

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

Get the name of the type of the value held by this Dynamic.

Panics or Deadlocks When Value is Shared

Under the sync feature, this call may deadlock, or panic. Otherwise, this call panics if the data is currently borrowed for write.

impl Dynamic

pub const UNIT: Dynamic

A Dynamic containing a ().

pub const TRUE: Dynamic

A Dynamic containing a true.

pub const FALSE: Dynamic

A Dynamic containing a false.

pub const ZERO: Dynamic

A Dynamic containing the integer zero.

pub const ONE: Dynamic

A Dynamic containing the integer one.

pub const TWO: Dynamic

A Dynamic containing the integer two.

pub const TEN: Dynamic

A Dynamic containing the integer ten.

pub const NEGATIVE_ONE: Dynamic

A Dynamic containing the integer negative one.

pub const FLOAT_ZERO: Dynamic

A Dynamic containing 0.0.

Not available under no_float.

pub const FLOAT_ONE: Dynamic

A Dynamic containing 1.0.

Not available under no_float.

pub const FLOAT_TWO: Dynamic

A Dynamic containing 2.0.

Not available under no_float.

pub const FLOAT_TEN: Dynamic

A Dynamic containing 10.0.

Not available under no_float.

pub const FLOAT_NEGATIVE_ONE: Dynamic

A Dynamic containing the -1.0.

Not available under no_float.

pub fn is_read_only(&self) -> bool

Is this Dynamic read-only?

Constant Dynamic values are read-only. If a &mut Dynamic to such a constant is passed to a Rust function, the function can use this information to return an error of ErrorAssignmentToConstant if its value is going to be modified. This safe-guards constant values from being modified from within Rust functions.

pub fn from<T: Variant + Clone>(value: T) -> Self

Create a Dynamic from any type. A Dynamic value is simply returned as is.

Safety

This type uses some unsafe code, mainly for type casting.

Notes

Beware that you need to pass in an Array type for it to be recognized as an Array. A Vec<T> does not get automatically converted to an Array, but will be a generic restricted trait object instead, because Vec<T> is not a supported standard type.

Similarly, passing in a HashMap<String, T> or BTreeMap<String, T> will not get a Map but a trait object.

Examples

use rhai::Dynamic;

let result = Dynamic::from(42_i64);
assert_eq!(result.type_name(), "i64");
assert_eq!(result.to_string(), "42");

let result = Dynamic::from("hello");
assert_eq!(result.type_name(), "string");
assert_eq!(result.to_string(), "hello");

let new_result = Dynamic::from(result);
assert_eq!(new_result.type_name(), "string");
assert_eq!(new_result.to_string(), "hello");

pub fn into_shared(self) -> Self

Turn the Dynamic value into a shared Dynamic value backed by an Rc<RefCell<Dynamic>> or Arc<RwLock<Dynamic>> depending on the sync feature.

Not available under no_closure.

Shared Dynamic values are relatively cheap to clone as they simply increment the reference counts.

Shared Dynamic values can be converted seamlessly to and from ordinary Dynamic values.

If the Dynamic value is already shared, this method returns itself.

pub fn try_cast<T: Any>(self) -> Option<T>

Convert the Dynamic value into specific type.

Casting to a Dynamic just returns as is, but if it contains a shared value, it is cloned into a Dynamic with a normal value.

Returns None if types mismatched.

Panics or Deadlocks

Under the sync feature, this call may deadlock, or panic. Otherwise, this call panics if the data is currently borrowed for write.

These normally shouldn’t occur since most operations in Rhai is single-threaded.

Example

use rhai::Dynamic;

let x = Dynamic::from(42_u32);

assert_eq!(x.try_cast::<u32>().unwrap(), 42);

pub fn cast<T: Any + Clone>(self) -> T

Convert the Dynamic value into a specific type.

Casting to a Dynamic just returns as is, but if it contains a shared value, it is cloned into a Dynamic with a normal value.

Returns None if types mismatched.

Panics or Deadlocks

Panics if the cast fails (e.g. the type of the actual value is not the same as the specified type).

Under the sync feature, this call may deadlock, or panic. Otherwise, this call panics if the data is currently borrowed for write.

These normally shouldn’t occur since most operations in Rhai is single-threaded.

Example

use rhai::Dynamic;

let x = Dynamic::from(42_u32);

assert_eq!(x.cast::<u32>(), 42);

pub fn clone_cast<T: Any + Clone>(&self) -> T

Clone the Dynamic value and convert it into a specific type.

Casting to a Dynamic just returns as is, but if it contains a shared value, it is cloned into a Dynamic with a normal value.

Returns None if types mismatched.

Panics or Deadlocks

Panics if the cast fails (e.g. the type of the actual value is not the same as the specified type).

Under the sync feature, this call may deadlock, or panic. Otherwise, this call panics if the data is currently borrowed for write.

These normally shouldn’t occur since most operations in Rhai is single-threaded.

Example

use rhai::Dynamic;

let x = Dynamic::from(42_u32);
let y = &x;

assert_eq!(y.clone_cast::<u32>(), 42);

pub fn flatten_clone(&self) -> Self

Flatten the Dynamic and clone it.

If the Dynamic is not a shared value, it returns a cloned copy.

If the Dynamic is a shared value, it returns a cloned copy of the shared value.

pub fn flatten(self) -> Self

Flatten the Dynamic.

If the Dynamic is not a shared value, it returns itself.

If the Dynamic is a shared value, it returns the shared value if there are no outstanding references, or a cloned copy.

pub fn is_locked(&self) -> bool

Is the Dynamic a shared value that is locked?

Not available under no_closure.

Note

Under the sync feature, shared values use RwLock and they are never locked. Access just waits until the RwLock is released. So this method always returns false under Sync.

pub fn read_lock<T: Any + Clone>(&self) -> Option<DynamicReadLock<'_, T>>

Get a reference of a specific type to the Dynamic. Casting to Dynamic just returns a reference to it.

Returns None if the cast fails.

Panics or Deadlocks When Value is Shared

Under the sync feature, this call may deadlock, or panic. Otherwise, this call panics if the data is currently borrowed for write.

pub fn write_lock<T: Any + Clone>(&mut self) -> Option<DynamicWriteLock<'_, T>>

Get a mutable reference of a specific type to the Dynamic. Casting to Dynamic just returns a mutable reference to it.

Returns None if the cast fails.

Panics or Deadlocks When Value is Shared

Under the sync feature, this call may deadlock, or panic. Otherwise, this call panics if the data is currently borrowed for write.

pub fn as_unit(&self) -> Result<(), &'static str>

Cast the Dynamic as a unit () and return it. Returns the name of the actual type if the cast fails.

pub fn as_int(&self) -> Result<INT, &'static str>

Cast the Dynamic as the system integer type INT and return it. Returns the name of the actual type if the cast fails.

pub fn as_float(&self) -> Result<FLOAT, &'static str>

Cast the Dynamic as the system floating-point type FLOAT and return it. Returns the name of the actual type if the cast fails.

Not available under no_float.

pub fn as_decimal(&self) -> Result<Decimal, &'static str>

(DECIMAL) Cast the Dynamic as a Decimal and return it. Returns the name of the actual type if the cast fails.

Exported under the decimal feature only.

pub fn as_bool(&self) -> Result<bool, &'static str>

Cast the Dynamic as a bool and return it. Returns the name of the actual type if the cast fails.

pub fn as_char(&self) -> Result<char, &'static str>

Cast the Dynamic as a char and return it. Returns the name of the actual type if the cast fails.

pub fn take_string(self) -> Result<String, &'static str>

Convert the Dynamic into a String and return it. If there are other references to the same string, a cloned copy is returned. Returns the name of the actual type if the cast fails.

pub fn take_immutable_string(self) -> Result<ImmutableString, &'static str>

Convert the Dynamic into an ImmutableString and return it. Returns the name of the actual type if the cast fails.

Trait Implementations

impl Clone for Dynamic

fn clone(&self) -> Self

Clone the Dynamic value.

WARNING

The cloned copy is marked read-write even if the original is read-only.

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

Performs copy-assignment from source.

impl Debug for Dynamic

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

Formats the value using the given formatter.

impl Default for Dynamic

fn default() -> Self

Returns the “default value” for a type.

impl<'d> Deserialize<'d> for Dynamic

fn deserialize<D: Deserializer<'d>>(de: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Dynamic

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

Formats the value using the given formatter.

impl<T: Variant + Clone> From<&'_ [T]> for Dynamic

fn from(value: &[T]) -> Self

Performs the conversion.

impl From<&'_ ImmutableString> for Dynamic

fn from(value: &ImmutableString) -> Self

Performs the conversion.

impl From<&'_ SmartString<Compact>> for Dynamic

fn from(value: &Identifier) -> Self

Performs the conversion.

impl From<()> for Dynamic

fn from(value: ()) -> Self

Performs the conversion.

impl<K: Into<Identifier>, T: Variant + Clone> From<BTreeMap<K, T>> for Dynamic

fn from(value: BTreeMap<K, T>) -> Self

Performs the conversion.

impl From<Box<FnPtr, Global>> for Dynamic

fn from(value: Box<FnPtr>) -> Self

Performs the conversion.

impl From<Decimal> for Dynamic

fn from(value: Decimal) -> Self

Performs the conversion.

impl From<Dynamic> for Expr

fn from(value: Dynamic) -> Self

Performs the conversion.

impl From<FloatWrapper<f64>> for Dynamic

fn from(value: FloatWrapper<FLOAT>) -> Self

Performs the conversion.

impl From<FnPtr> for Dynamic

fn from(value: FnPtr) -> Self

Performs the conversion.

impl<K: Into<Identifier>, T: Variant + Clone> From<HashMap<K, T, RandomState>> for Dynamic

fn from(value: HashMap<K, T>) -> Self

Performs the conversion.

impl From<Instant> for Dynamic

fn from(value: Instant) -> Self

Performs the conversion.

impl From<Rc<RefCell<Dynamic>>> for Dynamic

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

Performs the conversion.

impl<S: Into<ImmutableString>> From<S> for Dynamic

fn from(value: S) -> Self

Performs the conversion.

impl<T: Variant + Clone> From<Vec<T, Global>> for Dynamic

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

Performs the conversion.

impl From<bool> for Dynamic

fn from(value: bool) -> Self

Performs the conversion.

impl From<char> for Dynamic

fn from(value: char) -> Self

Performs the conversion.

impl From<f64> for Dynamic

fn from(value: FLOAT) -> Self

Performs the conversion.

impl From<i64> for Dynamic

fn from(value: INT) -> Self

Performs the conversion.

impl<T: Variant + Clone> FromIterator<T> for Dynamic

fn from_iter<X: IntoIterator<Item = T>>(iter: X) -> Self

Creates a value from an iterator.

impl Hash for Dynamic

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Serialize for Dynamic

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

Serialize this value into the given Serde serializer.