pub struct Scope<'a> { /* private fields */ }
Expand description
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§
source§impl Scope<'_>
impl Scope<'_>
sourcepub fn with_capacity(capacity: usize) -> Scope<'_>
pub fn with_capacity(capacity: usize) -> Scope<'_>
sourcepub fn clear(&mut self) -> &mut Scope<'_>
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());
sourcepub fn push(
&mut self,
name: impl Into<SmartString<LazyCompact>>,
value: impl Variant + Clone,
) -> &mut Scope<'_>
pub fn push( &mut self, name: impl Into<SmartString<LazyCompact>>, value: impl Variant + Clone, ) -> &mut Scope<'_>
sourcepub fn push_dynamic(
&mut self,
name: impl Into<SmartString<LazyCompact>>,
value: Dynamic,
) -> &mut Scope<'_>
pub fn push_dynamic( &mut self, name: impl Into<SmartString<LazyCompact>>, value: Dynamic, ) -> &mut Scope<'_>
sourcepub fn push_constant(
&mut self,
name: impl Into<SmartString<LazyCompact>>,
value: impl Variant + Clone,
) -> &mut Scope<'_>
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);
sourcepub fn push_constant_dynamic(
&mut self,
name: impl Into<SmartString<LazyCompact>>,
value: Dynamic,
) -> &mut Scope<'_>
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);
sourcepub fn pop(&mut self) -> &mut Scope<'_>
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());
sourcepub fn rewind(&mut self, size: usize) -> &mut Scope<'_>
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());
sourcepub fn get_value_mut<T>(&mut self, name: &str) -> Option<&mut T>where
T: Variant + Clone,
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);
sourcepub fn is_constant(&self, name: &str) -> Option<bool>
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);
sourcepub fn set_or_push(
&mut self,
name: impl AsRef<str> + Into<SmartString<LazyCompact>>,
value: impl Variant + Clone,
) -> &mut Scope<'_>
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);
sourcepub fn set_value(
&mut self,
name: impl AsRef<str> + Into<SmartString<LazyCompact>>,
value: impl Variant + Clone,
) -> &mut Scope<'_>
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);
sourcepub fn get(&self, name: &str) -> Option<&Dynamic>
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());
sourcepub fn remove<T>(&mut self, name: &str) -> Option<T>where
T: Variant + Clone,
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);
sourcepub fn get_mut(&mut self, name: &str) -> Option<&mut Dynamic>
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());
sourcepub fn clone_visible(&self) -> Scope<'_>
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.
sourcepub fn iter(&self) -> impl Iterator<Item = (&str, bool, Dynamic)>
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");
Trait Implementations§
source§impl<'de> Deserialize<'de> for Scope<'de>
impl<'de> Deserialize<'de> for Scope<'de>
source§fn deserialize<D>(
deserializer: D,
) -> Result<Scope<'de>, <D as Deserializer<'de>>::Error>where
D: Deserializer<'de>,
fn deserialize<D>(
deserializer: D,
) -> Result<Scope<'de>, <D as Deserializer<'de>>::Error>where
D: Deserializer<'de>,
source§impl<K> Extend<(K, Dynamic)> for Scope<'_>
impl<K> Extend<(K, Dynamic)> for Scope<'_>
source§fn extend<T>(&mut self, iter: T)where
T: IntoIterator<Item = (K, Dynamic)>,
fn extend<T>(&mut self, iter: T)where
T: IntoIterator<Item = (K, Dynamic)>,
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl<K> Extend<(K, bool, Dynamic)> for Scope<'_>
impl<K> Extend<(K, bool, Dynamic)> for Scope<'_>
source§fn extend<T>(&mut self, iter: T)
fn extend<T>(&mut self, iter: T)
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl<K> FromIterator<(K, Dynamic)> for Scope<'_>
impl<K> FromIterator<(K, Dynamic)> for Scope<'_>
source§impl<'a> IntoIterator for &'a Scope<'_>
impl<'a> IntoIterator for &'a Scope<'_>
source§impl IntoIterator for Scope<'_>
impl IntoIterator for Scope<'_>
source§impl Serialize for Scope<'_>
impl Serialize for Scope<'_>
source§fn serialize<S>(
&self,
ser: S,
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
S: Serializer,
fn serialize<S>(
&self,
ser: S,
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
S: Serializer,
Auto Trait Implementations§
impl<'a> Freeze for Scope<'a>
impl<'a> !RefUnwindSafe for Scope<'a>
impl<'a> Send for Scope<'a>
impl<'a> Sync for Scope<'a>
impl<'a> Unpin for Scope<'a>
impl<'a> !UnwindSafe for Scope<'a>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)