Struct rhai::Dynamic

pub struct Dynamic(_);

Dynamic type containing any value.

Implementations

impl Dynamic

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

👎Deprecated since 1.1.0:

use into_string instead

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.

Deprecated

This method is deprecated. Use into_string instead.

This method will be removed in the next major version.

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

👎Deprecated since 1.1.0:

use into_immutable_string instead

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

Deprecated

This method is deprecated. Use into_immutable_string instead.

This method will be removed in the next major version.

impl Dynamic

pub const fn tag(&self) -> i32

Get the arbitrary data attached to this Dynamic.

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

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: Self = _

A Dynamic containing a ().

pub const TRUE: Self = _

A Dynamic containing a true.

pub const FALSE: Self = _

A Dynamic containing a false.

pub const ZERO: Self = _

A Dynamic containing the integer zero.

pub const ONE: Self = _

A Dynamic containing the integer 1.

pub const TWO: Self = _

A Dynamic containing the integer 2.

pub const THREE: Self = _

A Dynamic containing the integer 3.

pub const TEN: Self = _

A Dynamic containing the integer 10.

pub const HUNDRED: Self = _

A Dynamic containing the integer 100.

pub const THOUSAND: Self = _

A Dynamic containing the integer 1,000.

pub const MILLION: Self = _

A Dynamic containing the integer 1,000,000.

pub const NEGATIVE_ONE: Self = _

A Dynamic containing the integer -1.

pub const NEGATIVE_TWO: Self = _

A Dynamic containing the integer -2.

pub const FLOAT_ZERO: Self = _

A Dynamic containing 0.0.

Not available under no_float.

pub const FLOAT_ONE: Self = _

A Dynamic containing 1.0.

Not available under no_float.

pub const FLOAT_TWO: Self = _

A Dynamic containing 2.0.

Not available under no_float.

pub const FLOAT_TEN: Self = _

A Dynamic containing 10.0.

Not available under no_float.

pub const FLOAT_HUNDRED: Self = _

A Dynamic containing 100.0.

Not available under no_float.

pub const FLOAT_THOUSAND: Self = _

A Dynamic containing 1000.0.

Not available under no_float.

pub const FLOAT_MILLION: Self = _

A Dynamic containing 1000000.0.

Not available under no_float.

pub const FLOAT_NEGATIVE_ONE: Self = _

A Dynamic containing -1.0.

Not available under no_float.

pub const FLOAT_NEGATIVE_TWO: Self = _

A Dynamic containing -2.0.

Not available under no_float.

pub const FLOAT_HALF: Self = _

A Dynamic containing 0.5.

Not available under no_float.

pub const FLOAT_QUARTER: Self = _

A Dynamic containing 0.25.

Not available under no_float.

pub const FLOAT_FIFTH: Self = _

A Dynamic containing 0.2.

Not available under no_float.

pub const FLOAT_TENTH: Self = _

A Dynamic containing 0.1.

Not available under no_float.

pub const FLOAT_HUNDREDTH: Self = _

A Dynamic containing 0.01.

Not available under no_float.

pub const FLOAT_THOUSANDTH: Self = _

A Dynamic containing 0.001.

Not available under no_float.

pub const FLOAT_MILLIONTH: Self = _

A Dynamic containing 0.000001.

Not available under no_float.

pub const FLOAT_PI: Self = _

A Dynamic containing π.

Not available under no_float.

pub const FLOAT_HALF_PI: Self = _

A Dynamic containing π/2.

Not available under no_float.

pub const FLOAT_QUARTER_PI: Self = _

A Dynamic containing π/4.

Not available under no_float.

pub const FLOAT_TWO_PI: Self = _

A Dynamic containing 2π.

Not available under no_float.

pub const FLOAT_INVERSE_PI: Self = _

A Dynamic containing 1/π.

Not available under no_float.

pub const FLOAT_E: Self = _

A Dynamic containing e.

Not available under no_float.

pub const FLOAT_LOG_E: Self = _

A Dynamic containing log e.

Not available under no_float.

pub const FLOAT_LN_10: Self = _

A Dynamic containing ln 10.

Not available under no_float.

pub const fn from_bool(value: bool) -> Self

Create a new Dynamic from a bool.

pub const fn from_int(value: INT) -> Self

Create a new Dynamic from an INT.

pub const fn from_char(value: char) -> Self

Create a new Dynamic from a char.

pub const fn from_float(value: FLOAT) -> Self

Create a new Dynamic from a FLOAT.

Not available under no_float.

pub fn from_decimal(value: Decimal) -> Self

Create a new Dynamic from a Decimal.

Exported under the decimal feature only.

pub fn from_array(array: Array) -> Self

Create a Dynamic from an Array.

pub fn from_blob(blob: Blob) -> Self

Create a Dynamic from a Blob.

pub fn from_map(map: Map) -> Self

Create a Dynamic from a Map.

pub fn from_timestamp(value: Instant) -> Self

Create a new Dynamic from an Instant.

Not available under no-std.

pub fn into_read_only(self) -> Self

Make this Dynamic read-only (i.e. a constant).

pub fn is_read_only(&self) -> bool

Is this Dynamic read-only?

Constant Dynamic values are read-only.

Usage

If a &mut Dynamic to such a constant is passed to a Rust function, the function can use this information to return the error ErrorAssignmentToConstant if its value will be modified.

This safe-guards constant values from being modified within Rust functions.

Shared Values

If a Dynamic holds a shared value, then it is read-only only if the shared value itself is read-only.

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

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

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 custom type instead (stored as a trait object). Use Dynamic::from_array to convert a Vec<T> into a Dynamic as an Array value.

Similarly, passing in a HashMap<String, T> or BTreeMap<String, T> will not get a Map but a custom type. Again, use Dynamic::from_map to get a Dynamic with a Map value.

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>().expect("x should be u32"), 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.

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 (). 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. 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. 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. 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. 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. Returns the name of the actual type if the cast fails.

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

Convert the Dynamic into a String. 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 into_immutable_string(self) -> Result<ImmutableString, &'static str>

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

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

Convert the Dynamic into an Array. Returns the name of the actual type if the cast fails.

pub fn into_typed_array<T: Variant + Clone>(
    self
) -> Result<Vec<T>, &'static str>

Convert the Dynamic into a Vec. Returns the name of the actual type if any cast fails.

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

Convert the Dynamic into a Blob. 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

Converts to this type from the input type.

impl From<&ImmutableString> for Dynamic

fn from(value: &ImmutableString) -> Self

Converts to this type from the input type.

impl From<()> for Dynamic

fn from(value: ()) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl<K: Into<Identifier>> From<BTreeSet<K, Global>> for Dynamic

fn from(value: BTreeSet<K>) -> Self

Converts to this type from the input type.

impl From<Decimal> for Dynamic

fn from(value: Decimal) -> Self

Converts to this type from the input type.

impl From<FloatWrapper<f64>> for Dynamic

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

Converts to this type from the input type.

impl From<FnPtr> for Dynamic

fn from(value: FnPtr) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl<K: Into<Identifier>> From<HashSet<K, RandomState>> for Dynamic

fn from(value: HashSet<K>) -> Self

Converts to this type from the input type.

impl From<Instant> for Dynamic

fn from(value: Instant) -> Self

Converts to this type from the input type.

impl From<Range<i64>> for Dynamic

fn from(value: Range<INT>) -> Self

Converts to this type from the input type.

impl From<RangeInclusive<i64>> for Dynamic

fn from(value: RangeInclusive<INT>) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

fn from(value: S) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<bool> for Dynamic

fn from(value: bool) -> Self

Converts to this type from the input type.

impl From<char> for Dynamic

fn from(value: char) -> Self

Converts to this type from the input type.

impl From<f64> for Dynamic

fn from(value: FLOAT) -> Self

Converts to this type from the input type.

impl From<i64> for Dynamic

fn from(value: INT) -> Self

Converts to this type from the input type.

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 FromStr for Dynamic

type Err = ()

The associated error which can be returned from parsing.

fn from_str(value: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Dynamic

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

Hash the Dynamic value.

Panics

Panics if the Dynamic value contains an unrecognized trait object.

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.