# 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. - [Struct `ObjectBag`](#iota_object_bag_ObjectBag) - [Constants](#@Constants_0) - [Function `new`](#iota_object_bag_new) - [Function `add`](#iota_object_bag_add) - [Function `borrow`](#iota_object_bag_borrow) - [Function `borrow_mut`](#iota_object_bag_borrow_mut) - [Function `remove`](#iota_object_bag_remove) - [Function `contains`](#iota_object_bag_contains) - [Function `contains_with_type`](#iota_object_bag_contains_with_type) - [Function `length`](#iota_object_bag_length) - [Function `is_empty`](#iota_object_bag_is_empty) - [Function `destroy_empty`](#iota_object_bag_destroy_empty) - [Function `value_id`](#iota_object_bag_value_id)

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;

## 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

## Constants

const EBagNotEmpty: u64 = 0;

## Function `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,
    }
}

## Function `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;
}

## Function `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)
}

## Function `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)
}

## Function `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
}

## Function `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)
}

## Function `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)
}

## Function `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
}

## Function `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
}

## Function `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()
}

## Function `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)
}