Struct Scope

pub struct Scope<'a> { /* 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.

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 fn new() -> Scope<'_>

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) -> Scope<'_>

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 Scope<'_>

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<SmartString<LazyCompact>>, value: impl Variant + Clone, ) -> &mut Scope<'_>

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<SmartString<LazyCompact>>, value: Dynamic, ) -> &mut Scope<'_>

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<SmartString<LazyCompact>>, value: impl Variant + Clone, ) -> &mut Scope<'_>

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<SmartString<LazyCompact>>, value: Dynamic, ) -> &mut Scope<'_>

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 pop(&mut self) -> &mut Scope<'_>

Remove the last entry from the Scope.

Panics

Panics is the Scope is empty.

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.pop();
assert!(my_scope.contains("x"));
assert!(!my_scope.contains("y"));
assert_eq!(my_scope.len(), 1);

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

pub fn rewind(&mut self, size: usize) -> &mut Scope<'_>

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>(&self, name: &str) -> Option<T>

where T: Variant + Clone,

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 get_value_ref<T>(&self, name: &str) -> Option<&T>

where T: Variant + Clone,

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

Panics

Panics if the value is shared.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

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

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

assert_eq!(*ptr, 42);

pub fn get_value_mut<T>(&mut self, name: &str) -> Option<&mut T>

where T: Variant + Clone,

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

Panics

Panics if the value is shared.

Example

use rhai::Scope;

let mut my_scope = Scope::new();

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

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

*ptr = 0;

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

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<SmartString<LazyCompact>>, value: impl Variant + Clone, ) -> &mut Scope<'_>

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<SmartString<LazyCompact>>, value: impl Variant + Clone, ) -> &mut Scope<'_>

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>(&mut self, name: &str) -> Option<T>

where T: Variant + Clone,

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 the value of 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 clone_visible(&self) -> Scope<'_>

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) -> Scope<'_>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Scope<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Scope<'a>

fn default() -> Scope<'a>

Returns the “default value” for a type.

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

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Scope<'_>

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

Formats the value using the given formatter.

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

where K: Into<SmartString<LazyCompact>>,

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = (K, Dynamic)>,

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> Extend<(K, bool, Dynamic)> for Scope<'_>

where K: Into<SmartString<LazyCompact>>,

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = (K, bool, Dynamic)>,

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> FromIterator<(K, Dynamic)> for Scope<'_>

where K: Into<SmartString<LazyCompact>>,

fn from_iter<T>(iter: T) -> Scope<'_>

where T: IntoIterator<Item = (K, Dynamic)>,

Creates a value from an iterator.

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

where K: Into<SmartString<LazyCompact>>,

fn from_iter<T>(iter: T) -> Scope<'_>

where T: IntoIterator<Item = (K, bool, Dynamic)>,

Creates a value from an iterator.

impl<'a> Hash for Scope<'a>

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

where __H: Hasher,

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 str, &'a Dynamic, &'a [ImmutableString])

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a Scope<'_> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl IntoIterator for Scope<'_>

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

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = <Scope<'_> as IntoIterator>::Item>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <Scope<'_> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl Serialize for Scope<'_>

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.