Struct sub_script::engine::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 Dynamic

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>(&self) -> bool where
    T: Any + Clone, 

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 = Self(Union::Unit((), DEFAULT_TAG_VALUE, ReadWrite))

A Dynamic containing a ().

pub const TRUE: Dynamic = Self::from_bool(true)

A Dynamic containing a true.

pub const FALSE: Dynamic = Self::from_bool(false)

A Dynamic containing a false.

pub const ZERO: Dynamic = Self::from_int(0)

A Dynamic containing the integer zero.

pub const ONE: Dynamic = Self::from_int(1)

A Dynamic containing the integer 1.

pub const TWO: Dynamic = Self::from_int(2)

A Dynamic containing the integer 2.

pub const THREE: Dynamic = Self::from_int(3)

A Dynamic containing the integer 3.

pub const TEN: Dynamic = Self::from_int(10)

A Dynamic containing the integer 10.

pub const HUNDRED: Dynamic = Self::from_int(100)

A Dynamic containing the integer 100.

pub const THOUSAND: Dynamic = Self::from_int(1000)

A Dynamic containing the integer 1,000.

pub const MILLION: Dynamic = Self::from_int(1000000)

A Dynamic containing the integer 1,000,000.

pub const NEGATIVE_ONE: Dynamic = Self::from_int(-1)

A Dynamic containing the integer -1.

pub const NEGATIVE_TWO: Dynamic = Self::from_int(-2)

A Dynamic containing the integer -2.

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

Create a new Dynamic from a bool.

pub const fn from_int(value: i64) -> Dynamic

Create a new Dynamic from an INT.

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

Create a new Dynamic from a char.

pub fn from_decimal(value: Decimal) -> Dynamic

Create a new Dynamic from a Decimal.

Exported under the decimal feature only.

pub fn from_array(array: Vec<Dynamic, Global>) -> Dynamic

Create a Dynamic from an Array.

pub fn from_blob(blob: Vec<u8, Global>) -> Dynamic

Create a Dynamic from a Blob.

pub fn from_map(map: BTreeMap<SmartString<LazyCompact>, Dynamic>) -> Dynamic

Create a Dynamic from a Map.

pub fn from_timestamp(value: Instant) -> Dynamic

Create a new Dynamic from an Instant.

Not available under no-std.

pub fn into_read_only(self) -> Dynamic

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.

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>(value: T) -> Dynamic where
    T: Variant + Clone, 

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 Into<Dynamic> 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 Into<Dynamic> 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) -> Dynamic

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>(self) -> Option<T> where
    T: Any, 

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>(self) -> T where
    T: Any + Clone, 

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>(&self) -> T where
    T: Any + Clone, 

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) -> Dynamic

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) -> Dynamic

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>(&self) -> Option<DynamicReadLock<'_, T>> where
    T: Any + Clone, 

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>(&mut self) -> Option<DynamicWriteLock<'_, T>> where
    T: Any + Clone, 

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<i64, &'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_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<Vec<Dynamic, Global>, &'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>(self) -> Result<Vec<T, Global>, &'static str> where
    T: Variant + Clone, 

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

pub fn into_blob(self) -> Result<Vec<u8, Global>, &'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) -> Dynamic

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<(), Error>

Formats the value using the given formatter.

impl Default for Dynamic

fn default() -> Dynamic

Returns the “default value” for a type.

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

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

Deserialize this value from the given Serde deserializer.

impl Display for Dynamic

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

Formats the value using the given formatter.

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

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

Converts to this type from the input type.

impl<'_> From<&'_ ImmutableString> for Dynamic

fn from(value: &ImmutableString) -> Dynamic

Converts to this type from the input type.

impl From<()> for Dynamic

fn from(value: ()) -> Dynamic

Converts to this type from the input type.

impl From<Arc<RwLock<Dynamic>>> for Dynamic

fn from(value: Arc<RwLock<Dynamic>>) -> Dynamic

Converts to this type from the input type.

impl<K, T> From<BTreeMap<K, T>> for Dynamic where
    K: Into<SmartString<LazyCompact>>,
    T: Variant + Clone, 

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

Converts to this type from the input type.

impl<K> From<BTreeSet<K>> for Dynamic where
    K: Into<SmartString<LazyCompact>>, 

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

Converts to this type from the input type.

impl From<Decimal> for Dynamic

fn from(value: Decimal) -> Dynamic

Converts to this type from the input type.

impl From<FnPtr> for Dynamic

fn from(value: FnPtr) -> Dynamic

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl<K> From<HashSet<K, RandomState>> for Dynamic where
    K: Into<SmartString<LazyCompact>>, 

fn from(value: HashSet<K, RandomState>) -> Dynamic

Converts to this type from the input type.

impl From<Instant> for Dynamic

fn from(value: Instant) -> Dynamic

Converts to this type from the input type.

impl From<Range<i64>> for Dynamic

fn from(value: Range<i64>) -> Dynamic

Converts to this type from the input type.

impl From<RangeInclusive<i64>> for Dynamic

fn from(value: RangeInclusive<i64>) -> Dynamic

Converts to this type from the input type.

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

fn from(value: S) -> Dynamic

Converts to this type from the input type.

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

fn from(value: Vec<T, Global>) -> Dynamic

Converts to this type from the input type.

impl From<bool> for Dynamic

fn from(value: bool) -> Dynamic

Converts to this type from the input type.

impl From<char> for Dynamic

fn from(value: char) -> Dynamic

Converts to this type from the input type.

impl From<i64> for Dynamic

fn from(value: i64) -> Dynamic

Converts to this type from the input type.

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

fn from_iter<X>(iter: X) -> Dynamic where
    X: IntoIterator<Item = T>, 

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<Dynamic, <Dynamic as FromStr>::Err>

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

impl Hash for Dynamic

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

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>(
    &self,
    ser: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.