Struct rhai::Scope

pub struct Scope<'a, const N: usize = SCOPE_ENTRIES_INLINED> { /* private fields */ }

Type containing information about the current scope. Useful for keeping state between Engine evaluation runs.

Lifetime

Currently the lifetime parameter is not used, but it is not guaranteed to remain unused for future versions. Until then, 'static can be used.

Constant Generic Parameter

There is a constant generic parameter that indicates how many entries to keep inline. As long as the number of entries does not exceed this limit, no allocations occur. The default is 8.

A larger value makes Scope larger, but reduces the chance of allocations.

Thread Safety

Currently, Scope is neither Send nor Sync. Turn on the sync feature to make it Send + Sync.

Example

use rhai::{Engine, Scope};

let engine = Engine::new();
let mut my_scope = Scope::new();

my_scope.push("z", 40_i64);

engine.run_with_scope(&mut my_scope, "let x = z + 1; z = 0;")?;

let result: i64 = engine.eval_with_scope(&mut my_scope, "x + 1")?;

assert_eq!(result, 42);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 41);
assert_eq!(my_scope.get_value::<i64>("z").expect("z should exist"), 0);

When searching for entries, newly-added entries are found before similarly-named but older entries, allowing for automatic shadowing.

Implementations

impl Scope<'_>

pub const fn new() -> Self

Create a new Scope.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

pub fn with_capacity(capacity: usize) -> Self

Create a new Scope with a particular capacity.

Example

use rhai::Scope;

let mut my_scope = Scope::with_capacity(10);

my_scope.push("x", 42_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

pub fn clear(&mut self) -> &mut Self

Empty the Scope.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
assert!(my_scope.contains("x"));
assert_eq!(my_scope.len(), 1);
assert!(!my_scope.is_empty());

my_scope.clear();
assert!(!my_scope.contains("x"));
assert_eq!(my_scope.len(), 0);
assert!(my_scope.is_empty());

pub fn len(&self) -> usize

Get the number of entries inside the Scope.

Example

use rhai::Scope;

let mut my_scope = Scope::new();
assert_eq!(my_scope.len(), 0);

my_scope.push("x", 42_i64);
assert_eq!(my_scope.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if this Scope contains no variables.

Example

use rhai::Scope;

let mut my_scope = Scope::new();
assert!(my_scope.is_empty());

my_scope.push("x", 42_i64);
assert!(!my_scope.is_empty());

pub fn push(
    &mut self,
    name: impl Into<Identifier>,
    value: impl Variant + Clone
) -> &mut Self

Add (push) a new entry to the Scope.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

pub fn push_dynamic(
    &mut self,
    name: impl Into<Identifier>,
    value: Dynamic
) -> &mut Self

Add (push) a new Dynamic entry to the Scope.

Example

use rhai::{Dynamic,  Scope};

let mut my_scope = Scope::new();

my_scope.push_dynamic("x", Dynamic::from(42_i64));
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

pub fn push_constant(
    &mut self,
    name: impl Into<Identifier>,
    value: impl Variant + Clone
) -> &mut Self

Add (push) a new constant to the Scope.

Constants are immutable and cannot be assigned to. Their values never change. Constants propagation is a technique used to optimize an AST.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push_constant("x", 42_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

pub fn push_constant_dynamic(
    &mut self,
    name: impl Into<Identifier>,
    value: Dynamic
) -> &mut Self

Add (push) a new constant with a Dynamic value to the Scope.

Constants are immutable and cannot be assigned to. Their values never change. Constants propagation is a technique used to optimize an AST.

Example

use rhai::{Dynamic, Scope};

let mut my_scope = Scope::new();

my_scope.push_constant_dynamic("x", Dynamic::from(42_i64));
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

pub fn rewind(&mut self, size: usize) -> &mut Self

Truncate (rewind) the Scope to a previous size.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
my_scope.push("y", 123_i64);
assert!(my_scope.contains("x"));
assert!(my_scope.contains("y"));
assert_eq!(my_scope.len(), 2);

my_scope.rewind(1);
assert!(my_scope.contains("x"));
assert!(!my_scope.contains("y"));
assert_eq!(my_scope.len(), 1);

my_scope.rewind(0);
assert!(!my_scope.contains("x"));
assert!(!my_scope.contains("y"));
assert_eq!(my_scope.len(), 0);
assert!(my_scope.is_empty());

pub fn contains(&self, name: &str) -> bool

Does the Scope contain the entry?

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
assert!(my_scope.contains("x"));
assert!(!my_scope.contains("y"));

pub fn get_value<T: Variant + Clone>(&self, name: &str) -> Option<T>

Get the value of an entry in the Scope, starting from the last.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

pub fn is_constant(&self, name: &str) -> Option<bool>

Check if the named entry in the Scope is constant.

Search starts backwards from the last, stopping at the first entry matching the specified name.

Returns None if no entry matching the specified name is found.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push_constant("x", 42_i64);
assert_eq!(my_scope.is_constant("x"), Some(true));
assert_eq!(my_scope.is_constant("y"), None);

pub fn set_or_push(
    &mut self,
    name: impl AsRef<str> + Into<Identifier>,
    value: impl Variant + Clone
) -> &mut Self

Update the value of the named entry in the Scope if it already exists and is not constant. Push a new entry with the value into the Scope if the name doesn’t exist or if the existing entry is constant.

Search starts backwards from the last, and only the first entry matching the specified name is updated.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.set_or_push("x", 42_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);
assert_eq!(my_scope.len(), 1);

my_scope.set_or_push("x", 0_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 0);
assert_eq!(my_scope.len(), 1);

my_scope.set_or_push("y", 123_i64);
assert_eq!(my_scope.get_value::<i64>("y").expect("y should exist"), 123);
assert_eq!(my_scope.len(), 2);

pub fn set_value(
    &mut self,
    name: impl AsRef<str> + Into<Identifier>,
    value: impl Variant + Clone
) -> &mut Self

Update the value of the named entry in the Scope.

Search starts backwards from the last, and only the first entry matching the specified name is updated. If no entry matching the specified name is found, a new one is added.

Panics

Panics when trying to update the value of a constant.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

my_scope.set_value("x", 0_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 0);

pub fn get(&self, name: &str) -> Option<&Dynamic>

Get a reference to an entry in the Scope.

If the entry by the specified name is not found, None is returned.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);

let value = my_scope.get("x").expect("x should exist");

assert_eq!(value.as_int().unwrap(), 42);

assert!(my_scope.get("z").is_none());

pub fn remove<T: Variant + Clone>(&mut self, name: &str) -> Option<T>

Remove the last entry in the Scope by the specified name and return its value.

If the entry by the specified name is not found, None is returned.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 123_i64);        // first 'x'
my_scope.push("x", 42_i64);         // second 'x', shadows first

assert_eq!(my_scope.len(), 2);

let value = my_scope.remove::<i64>("x").expect("x should exist");

assert_eq!(value, 42);

assert_eq!(my_scope.len(), 1);

let value = my_scope.get_value::<i64>("x").expect("x should still exist");

assert_eq!(value, 123);

pub fn get_mut(&mut self, name: &str) -> Option<&mut Dynamic>

Get a mutable reference to an entry in the Scope.

If the entry by the specified name is not found, or if it is read-only, None is returned.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 42);

let ptr = my_scope.get_mut("x").expect("x should exist");
*ptr = 123_i64.into();

assert_eq!(my_scope.get_value::<i64>("x").expect("x should exist"), 123);

my_scope.push_constant("z", 1_i64);
assert!(my_scope.get_mut("z").is_none());

pub fn set_alias(
    &mut self,
    name: impl AsRef<str> + Into<Identifier>,
    alias: impl Into<ImmutableString>
)

Add an alias to a variable in the Scope so that it is exported under that name. This is an advanced API.

If the alias is empty, then the variable is exported under its original name.

Multiple aliases can be added to any variable.

Only the last variable matching the name (and not other shadowed versions) is aliased by this call.

pub fn clone_visible(&self) -> Self

Clone the Scope, keeping only the last instances of each variable name. Shadowed variables are omitted in the copy.

pub fn iter(&self) -> impl Iterator<Item = (&str, bool, Dynamic)>

Get an iterator to entries in the Scope. Shared values are flatten-cloned.

Example

use rhai::{Dynamic, Scope};

let mut my_scope = Scope::new();

my_scope.push("x", 42_i64);
my_scope.push_constant("foo", "hello");

let mut iter = my_scope.iter();

let (name, is_constant, value) = iter.next().expect("value should exist");
assert_eq!(name, "x");
assert!(!is_constant);
assert_eq!(value.cast::<i64>(), 42);

let (name, is_constant, value) = iter.next().expect("value should exist");
assert_eq!(name, "foo");
assert!(is_constant);
assert_eq!(value.cast::<String>(), "hello");

pub fn iter_raw(&self) -> impl Iterator<Item = (&str, bool, &Dynamic)>

Get an iterator to entries in the Scope. Shared values are not expanded.

Trait Implementations

impl Clone for Scope<'_>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, const N: usize> Debug for Scope<'a, N>

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

Formats the value using the given formatter.

impl<'a, const N: usize> Default for Scope<'a, N>

fn default() -> Scope<'a, N>

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Scope<'de>

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

Deserialize this value from the given Serde deserializer.

impl Display for Scope<'_>

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

Formats the value using the given formatter.

impl<K: Into<Identifier>> Extend<(K, Dynamic)> for Scope<'_>

fn extend<T: IntoIterator<Item = (K, Dynamic)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<K: Into<Identifier>> Extend<(K, bool, Dynamic)> for Scope<'_>

fn extend<T: IntoIterator<Item = (K, bool, Dynamic)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<K: Into<Identifier>> FromIterator<(K, Dynamic)> for Scope<'_>

fn from_iter<T: IntoIterator<Item = (K, Dynamic)>>(iter: T) -> Self

Creates a value from an iterator.

impl<K: Into<Identifier>> FromIterator<(K, bool, Dynamic)> for Scope<'_>

fn from_iter<T: IntoIterator<Item = (K, bool, Dynamic)>>(iter: T) -> Self

Creates a value from an iterator.

impl<'a, const N: usize> Hash for Scope<'a, N>

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,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> IntoIterator for &'a Scope<'_>

type Item = (&'a SmartString<LazyCompact>, &'a Dynamic, &'a Vec<ImmutableString, Global>)

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = <&'a Scope<'_, SCOPE_ENTRIES_INLINED> as IntoIterator>::Item> + 'a, Global>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Scope<'_>

type Item = (String, Dynamic, Vec<ImmutableString, Global>)

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = <Scope<'_, SCOPE_ENTRIES_INLINED> as IntoIterator>::Item> + 'static, Global>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Serialize for Scope<'_>

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

Serialize this value into the given Serde serializer.