Skip to main content

Module iota::object_bag

Similar to iota::bag, an ObjectBag is a heterogeneous map-like collection. But unlike iota::bag, the values bound to these dynamic fields must be objects themselves. This allows for the objects to still exist in storage, which may be important for external tools. The difference is otherwise not observable from within Move.

use iota::address;
use iota::dynamic_field;
use iota::dynamic_object_field;
use iota::hex;
use iota::object;
use iota::tx_context;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;

Module Functions​

pub new​

Creates a new, empty bag

public fun new(ctx: &mut iota::tx_context::TxContext): iota::object_bag::ObjectBag
Implementation
public fun new(ctx: &mut TxContext): ObjectBag {
    ObjectBag {
        id: object::new(ctx),
        size: 0,
    }
}

Structs​

struct ObjectBag​

public struct ObjectBag has key, store
Fields
id: iota::object::UID

the ID of this bag

size: u64

the number of key-value pairs in the bag

pub add​

Adds a key-value pair to the bag bag: &mut ObjectBag Aborts with iota::dynamic_field::EFieldAlreadyExists if the bag already has an entry with that key k: K.

public fun add<K: copy, drop, store, V: key, store>(bag: &mut iota::object_bag::ObjectBag, k: K, v: V)
Implementation
public fun add<K: copy + drop + store, V: key + store>(bag: &mut ObjectBag, k: K, v: V) {
    ofield::add(&mut bag.id, k, v);
    bag.size = bag.size + 1;
}

pub borrow​

Immutably borrows the value associated with the key in the bag bag: &ObjectBag. Aborts with iota::dynamic_field::EFieldDoesNotExist if the bag does not have an entry with that key k: K. Aborts with iota::dynamic_field::EFieldTypeMismatch if the bag has an entry for the key, but the value does not have the specified type.

public fun borrow<K: copy, drop, store, V: key, store>(bag: &iota::object_bag::ObjectBag, k: K): &V
Implementation
public fun borrow<K: copy + drop + store, V: key + store>(bag: &ObjectBag, k: K): &V {
    ofield::borrow(&bag.id, k)
}

pub borrow_mut​

Mutably borrows the value associated with the key in the bag bag: &mut ObjectBag. Aborts with iota::dynamic_field::EFieldDoesNotExist if the bag does not have an entry with that key k: K. Aborts with iota::dynamic_field::EFieldTypeMismatch if the bag has an entry for the key, but the value does not have the specified type.

public fun borrow_mut<K: copy, drop, store, V: key, store>(bag: &mut iota::object_bag::ObjectBag, k: K): &mut V
Implementation
public fun borrow_mut<K: copy + drop + store, V: key + store>(bag: &mut ObjectBag, k: K): &mut V {
    ofield::borrow_mut(&mut bag.id, k)
}

pub contains​

Returns true iff there is an value associated with the key k: K in the bag bag: &ObjectBag

public fun contains<K: copy, drop, store>(bag: &iota::object_bag::ObjectBag, k: K): bool
Implementation
public fun contains<K: copy + drop + store>(bag: &ObjectBag, k: K): bool {
    ofield::exists_<K>(&bag.id, k)
}

pub contains_with_type​

Returns true iff there is an value associated with the key k: K in the bag bag: &ObjectBag with an assigned value of type V

public fun contains_with_type<K: copy, drop, store, V: key, store>(bag: &iota::object_bag::ObjectBag, k: K): bool
Implementation
public fun contains_with_type<K: copy + drop + store, V: key + store>(bag: &ObjectBag, k: K): bool {
    ofield::exists_with_type<K, V>(&bag.id, k)
}

pub destroy_empty​

Destroys an empty bag Aborts with EBagNotEmpty if the bag still contains values

public fun destroy_empty(bag: iota::object_bag::ObjectBag)
Implementation
public fun destroy_empty(bag: ObjectBag) {
    let ObjectBag { id, size } = bag;
    assert!(size == 0, EBagNotEmpty);
    id.delete()
}

pub is_empty​

Returns true iff the bag is empty (if length returns 0)

public fun is_empty(bag: &iota::object_bag::ObjectBag): bool
Implementation
public fun is_empty(bag: &ObjectBag): bool {
    bag.size == 0
}

pub length​

Returns the size of the bag, the number of key-value pairs

public fun length(bag: &iota::object_bag::ObjectBag): u64
Implementation
public fun length(bag: &ObjectBag): u64 {
    bag.size
}

pub remove​

Mutably borrows the key-value pair in the bag bag: &mut ObjectBag and returns the value. Aborts with iota::dynamic_field::EFieldDoesNotExist if the bag does not have an entry with that key k: K. Aborts with iota::dynamic_field::EFieldTypeMismatch if the bag has an entry for the key, but the value does not have the specified type.

public fun remove<K: copy, drop, store, V: key, store>(bag: &mut iota::object_bag::ObjectBag, k: K): V
Implementation
public fun remove<K: copy + drop + store, V: key + store>(bag: &mut ObjectBag, k: K): V {
    let v = ofield::remove(&mut bag.id, k);
    bag.size = bag.size - 1;
    v
}

pub value_id​

Returns the ID of the object associated with the key if the bag has an entry with key k: K Returns none otherwise

public fun value_id<K: copy, drop, store>(bag: &iota::object_bag::ObjectBag, k: K): std::option::Option<iota::object::ID>
Implementation
public fun value_id<K: copy + drop + store>(bag: &ObjectBag, k: K): Option<ID> {
    ofield::id(&bag.id, k)
}

Constants​

err EBagNotEmpty​

const EBagNotEmpty: u64 = 0;