Struct boa_engine::object::builtins::JsMap

pub struct JsMap { /* private fields */ }

JsMap provides a wrapper for Boa’s implementation of the ECMAScript Map object.

Examples

Create a JsMap and set a new entry

// Create default `Context`
let context = &mut Context::default();

// Create a new empty `JsMap`.
let map = JsMap::new(context);

// Set key-value pairs for the `JsMap`.
map.set(js_string!("Key-1"), js_string!("Value-1"), context)?;
map.set(js_string!("Key-2"), 10, context)?;

assert_eq!(map.get_size(context)?, 2.into());

Create a JsMap from a JsArray

// Create a default `Context`
let context = &mut Context::default();

// Create an array of two `[key, value]` pairs
let js_array = JsArray::new(context);

// Create a `[key, value]` pair of JsValues
let vec_one: Vec<JsValue> = vec![
    js_string!("first-key").into(),
    js_string!("first-value").into()
];

// We create an push our `[key, value]` pair onto our array as a `JsArray`
js_array.push(JsArray::from_iter(vec_one, context), context)?;

// Create a `JsMap` from the `JsArray` using it's iterable property.
let js_iterable_map = JsMap::from_js_iterable(&js_array.into(), context)?;

assert_eq!(
    js_iterable_map.get(js_string!("first-key"), context)?,
    js_string!("first-value").into()
);

}

Implementations

impl JsMap

pub fn new(context: &mut Context) -> Self

Creates a new empty JsMap object.

Example

// Create a new empty `JsMap`.
let map = JsMap::new(context);

pub fn from_js_iterable( iterable: &JsValue, context: &mut Context ) -> JsResult<Self>

Create a new JsMap object from a JsObject that has an @@Iterator field.

Examples

// Create an array of two `[key, value]` pairs
let js_array = JsArray::new(context);

// Create a `[key, value]` pair of JsValues and add it to the `JsArray` as a `JsArray`
let vec_one: Vec<JsValue> = vec![
    js_string!("first-key").into(),
    js_string!("first-value").into()
];
js_array.push(JsArray::from_iter(vec_one, context), context)?;

// Create a `JsMap` from the `JsArray` using it's iterable property.
let js_iterable_map = JsMap::from_js_iterable(&js_array.into(), context)?;

pub fn from_object(object: JsObject) -> JsResult<Self>

Creates a JsMap from a valid JsObject, or returns a TypeError if the provided object is not a JsMap

Examples

Valid Example - returns a JsMap object

// `some_object` can be any JavaScript `Map` object.
let some_object = JsObject::from_proto_and_data(
    context.intrinsics().constructors().map().prototype(),
    OrderedMap::<JsValue>::new(),
);

// Create `JsMap` object with incoming object.
let js_map = JsMap::from_object(some_object)?;

Invalid Example - returns a TypeError with the message “object is not a Map”

let some_object = JsArray::new(context);

// `some_object` is an Array object, not a map object
assert!(JsMap::from_object(some_object.into()).is_err());

pub fn entries(&self, context: &mut Context) -> JsResult<JsMapIterator>

Returns a new JsMapIterator object that yields the [key, value] pairs within the JsMap in insertion order.

pub fn keys(&self, context: &mut Context) -> JsResult<JsMapIterator>

Returns a new JsMapIterator object that yields the key for each element within the JsMap in insertion order.

pub fn set<K, V>( &self, key: K, value: V, context: &mut Context ) -> JsResult<JsValue>

where K: Into<JsValue>, V: Into<JsValue>,

Inserts a new entry into the JsMap object

Example

let js_map = JsMap::new(context);

js_map.set(js_string!("foo"), js_string!("bar"), context)?;
js_map.set(2, 4, context)?;

assert_eq!(
    js_map.get(js_string!("foo"), context)?,
    js_string!("bar").into()
);
assert_eq!(js_map.get(2, context)?, 4.into());

pub fn get_size(&self, context: &mut Context) -> JsResult<JsValue>

Gets the size of the JsMap object.

Example

let js_map = JsMap::new(context);

js_map.set(js_string!("foo"), js_string!("bar"), context)?;

let map_size = js_map.get_size(context)?;

assert_eq!(map_size, 1.into());

pub fn delete<T>(&self, key: T, context: &mut Context) -> JsResult<JsValue>

where T: Into<JsValue>,

Removes element from JsMap with a matching key value.

Example

let js_map = JsMap::new(context);
js_map.set(js_string!("foo"), js_string!("bar"), context)?;
js_map.set(js_string!("hello"), js_string!("world"), context)?;

js_map.delete(js_string!("foo"), context)?;

assert_eq!(js_map.get_size(context)?, 1.into());
assert_eq!(
    js_map.get(js_string!("foo"), context)?,
    JsValue::undefined()
);

pub fn get<T>(&self, key: T, context: &mut Context) -> JsResult<JsValue>

where T: Into<JsValue>,

Gets the value associated with the specified key within the JsMap, or undefined if the key does not exist.

Example

let js_map = JsMap::new(context);
js_map.set(js_string!("foo"), js_string!("bar"), context)?;

let retrieved_value = js_map.get(js_string!("foo"), context)?;

assert_eq!(retrieved_value, js_string!("bar").into());

pub fn clear(&self, context: &mut Context) -> JsResult<JsValue>

Removes all entries from the JsMap.

Example

let js_map = JsMap::new(context);
js_map.set(js_string!("foo"), js_string!("bar"), context)?;
js_map.set(js_string!("hello"), js_string!("world"), context)?;

js_map.clear(context)?;

assert_eq!(js_map.get_size(context)?, 0.into());

pub fn has<T>(&self, key: T, context: &mut Context) -> JsResult<JsValue>

where T: Into<JsValue>,

Checks if JsMap has an entry with the provided key value.

Example

let js_map = JsMap::new(context);
js_map.set(js_string!("foo"), js_string!("bar"), context)?;

let has_key = js_map.has(js_string!("foo"), context)?;

assert_eq!(has_key, true.into());

pub fn for_each( &self, callback: JsFunction, this_arg: JsValue, context: &mut Context ) -> JsResult<JsValue>

Executes the provided callback function for each key-value pair within the JsMap.

pub fn values(&self, context: &mut Context) -> JsResult<JsMapIterator>

Returns a new JsMapIterator object that yields the value for each element within the JsMap in insertion order.

Methods from Deref<Target = JsObject>

pub fn downcast_ref<T: NativeObject>(&self) -> Option<Ref<'_, T>>

Downcasts a reference to the object, if the object is of type T.

Panics

Panics if the object is currently mutably borrowed.

pub fn downcast_mut<T: NativeObject>( &self ) -> Option<RefMut<'_, ErasedObject, T>>

Downcasts a mutable reference to the object, if the object is type native object type T.

Panics

Panics if the object is currently borrowed.

pub fn is<T: NativeObject>(&self) -> bool

Checks if this object is an instance of a certain NativeObject.

Panics

Panics if the object is currently mutably borrowed.

pub fn is_ordinary(&self) -> bool

Checks if it’s an ordinary object.

Panics

Panics if the object is currently mutably borrowed.

pub fn is_array(&self) -> bool

Checks if it’s an Array object.

pub fn to_property_descriptor( &self, context: &mut Context ) -> JsResult<PropertyDescriptor>

The abstract operation ToPropertyDescriptor.

More information:

• ECMAScript reference

pub fn copy_data_properties<K>( &self, source: &JsValue, excluded_keys: Vec<K>, context: &mut Context ) -> JsResult<()>

where K: Into<PropertyKey>,

7.3.25 CopyDataProperties ( target, source, excludedItems )

More information:

• ECMAScript

pub fn borrow(&self) -> Ref<'_, Object<T>>

Immutably borrows the Object.

The borrow lasts until the returned Ref exits scope. Multiple immutable borrows can be taken out at the same time.

Panics

Panics if the object is currently mutably borrowed.

pub fn borrow_mut(&self) -> RefMut<'_, Object<T>, Object<T>>

Mutably borrows the Object.

The borrow lasts until the returned RefMut exits scope. The object cannot be borrowed while this borrow is active.

Panics

Panics if the object is currently borrowed.

pub fn try_borrow(&self) -> StdResult<Ref<'_, Object<T>>, BorrowError>

Immutably borrows the Object, returning an error if the value is currently mutably borrowed.

The borrow lasts until the returned GcCellRef exits scope. Multiple immutable borrows can be taken out at the same time.

This is the non-panicking variant of borrow.

pub fn try_borrow_mut( &self ) -> StdResult<RefMut<'_, Object<T>, Object<T>>, BorrowMutError>

Mutably borrows the object, returning an error if the value is currently borrowed.

The borrow lasts until the returned GcCellRefMut exits scope. The object be borrowed while this borrow is active.

This is the non-panicking variant of borrow_mut.

pub fn prototype(&self) -> JsPrototype

Get the prototype of the object.

Panics

Panics if the object is currently mutably borrowed.

pub fn set_prototype(&self, prototype: JsPrototype) -> bool

Set the prototype of the object.

Panics

Panics if the object is currently mutably borrowed

pub fn insert_property<K, P>(&self, key: K, property: P) -> bool

where K: Into<PropertyKey>, P: Into<PropertyDescriptor>,

Inserts a field in the object properties without checking if it’s writable.

If a field was already in the object with the same name, than true is returned with that field, otherwise false is returned.

pub fn is_callable(&self) -> bool

It determines if Object is a callable function with a [[Call]] internal method.

More information:

• ECMAScript reference

pub fn is_constructor(&self) -> bool

It determines if Object is a function object with a [[Construct]] internal method.

More information:

• ECMAScript reference

pub fn is_extensible(&self, context: &mut Context) -> JsResult<bool>

Check if object is extensible.

More information:

• ECMAScript reference

pub fn get<K>(&self, key: K, context: &mut Context) -> JsResult<JsValue>

where K: Into<PropertyKey>,

Get property from object or throw.

More information:

• ECMAScript reference

pub fn set<K, V>( &self, key: K, value: V, throw: bool, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>, V: Into<JsValue>,

set property of object or throw if bool flag is passed.

More information:

• ECMAScript reference

pub fn create_data_property<K, V>( &self, key: K, value: V, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>, V: Into<JsValue>,

Create data property

More information:

• ECMAScript reference

pub fn create_data_property_or_throw<K, V>( &self, key: K, value: V, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>, V: Into<JsValue>,

Create data property or throw

More information:

• ECMAScript reference

pub fn define_property_or_throw<K, P>( &self, key: K, desc: P, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>, P: Into<PropertyDescriptor>,

Define property or throw.

More information:

• ECMAScript reference

pub fn delete_property_or_throw<K>( &self, key: K, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>,

Defines the property or throws a TypeError if the operation fails.

More information:

• ECMAScript reference

pub fn has_property<K>(&self, key: K, context: &mut Context) -> JsResult<bool>

where K: Into<PropertyKey>,

Check if object has property.

More information:

• ECMAScript reference

pub fn has_own_property<K>( &self, key: K, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>,

Check if object has an own property.

More information:

• ECMAScript reference

pub fn call( &self, this: &JsValue, args: &[JsValue], context: &mut Context ) -> JsResult<JsValue>

Call ( F, V [ , argumentsList ] )

Panics

Panics if the object is currently mutably borrowed.

More information:

• ECMAScript reference

pub fn construct( &self, args: &[JsValue], new_target: Option<&Self>, context: &mut Context ) -> JsResult<Self>

Construct ( F [ , argumentsList [ , newTarget ] ] )

Construct an instance of this object with the specified arguments.

Panics

Panics if the object is currently mutably borrowed.

More information:

• ECMAScript reference

pub fn set_integrity_level( &self, level: IntegrityLevel, context: &mut Context ) -> JsResult<bool>

Make the object sealed or frozen.

More information:

• ECMAScript reference

pub fn test_integrity_level( &self, level: IntegrityLevel, context: &mut Context ) -> JsResult<bool>

Check if the object is sealed or frozen.

More information:

• ECMAScript reference

Trait Implementations

impl Clone for JsMap

fn clone(&self) -> JsMap

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for JsMap

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

Formats the value using the given formatter.

impl Deref for JsMap

type Target = JsObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for JsMap

fn drop(&mut self)

Executes the destructor for this type.

impl Finalize for JsMap

fn finalize(&self)

Cleanup logic for a type.

impl From<JsMap> for JsObject

fn from(o: JsMap) -> Self

Converts to this type from the input type.

impl From<JsMap> for JsValue

fn from(o: JsMap) -> Self

Converts to this type from the input type.

impl Trace for JsMap

unsafe fn trace(&self, tracer: &mut Tracer)

Marks all contained Gcs.

unsafe fn trace_non_roots(&self)

Trace handles located in GC heap, and mark them as non root.

fn run_finalizer(&self)

Runs Finalize::finalize on this object and all contained subobjects.

impl TryFromJs for JsMap

fn try_from_js(value: &JsValue, _context: &mut Context) -> JsResult<Self>

This function tries to convert a JavaScript value into Self.