# Module sui::bag

*[Documentation index](/llms.txt) · [Full index](/llms-full.txt)*

A bag is a heterogeneous map-like collection. The collection is similar to [sui::table](../sui_sui/table#sui_table) in that
its keys and values are not stored within the [Bag](../sui_sui/bag#sui_bag_Bag) value, but instead are stored using Sui's
object system. The [Bag](../sui_sui/bag#sui_bag_Bag) struct acts only as a handle into the object system to retrieve those
keys and values.

Note that this means that [Bag](../sui_sui/bag#sui_bag_Bag) values with exactly the same key-value mapping will not be
equal, with ==, at runtime. For example
```
let bag1 = bag::new();
let bag2 = bag::new();
bag::add(&mut bag1, 0, false);
bag::add(&mut bag1, 1, true);
bag::add(&mut bag2, 0, false);
bag::add(&mut bag2, 1, true);
// bag1 does not equal bag2, despite having the same entries
assert!(&bag1 != &bag2);
```
At it's core, [sui::bag](../sui_sui/bag#sui_bag) is a wrapper around UID that allows for access to
[sui::dynamic_field](../sui_sui/dynamic_field#sui_dynamic_field) while preventing accidentally stranding field values. A UID can be
deleted, even if it has dynamic fields associated with it, but a bag, on the other hand, must be
empty to be destroyed.

```
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;
use sui::address;
use sui::dynamic_field;
use sui::hex;
use sui::object;
use sui::tx_context;
```

## Struct Bag

```
public struct Bag has key, store
```

**Fields**

**id: sui::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 sui::tx_context::TxContext): sui::bag::Bag
```

## Function add

Adds a key-value pair to the bag [bag](../sui_sui/bag#sui_bag): &**mut** [Bag](../sui_sui/bag#sui_bag_Bag).

Aborts with [sui::dynamic_field::EFieldAlreadyExists](../sui_sui/dynamic_field#sui_dynamic_field_EFieldAlreadyExists) if the bag already has an entry with
that key k: K.

```
public fun add<K: copy, drop, store, V: store>(bag: &mut sui::bag::Bag, k: K, v: V)
```

## Function borrow

Immutable borrows the value associated with the key in the bag [bag](../sui_sui/bag#sui_bag): &[Bag](../sui_sui/bag#sui_bag_Bag).

Aborts with [sui::dynamic_field::EFieldDoesNotExist](../sui_sui/dynamic_field#sui_dynamic_field_EFieldDoesNotExist) if the bag does not have an entry with
that key k: K.

Aborts with [sui::dynamic_field::EFieldTypeMismatch](../sui_sui/dynamic_field#sui_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: store>(bag: &sui::bag::Bag, k: K): &V
```

## Function borrow_mut

Mutably borrows the value associated with the key in the bag [bag](../sui_sui/bag#sui_bag): &**mut** [Bag](../sui_sui/bag#sui_bag_Bag).

Aborts with [sui::dynamic_field::EFieldDoesNotExist](../sui_sui/dynamic_field#sui_dynamic_field_EFieldDoesNotExist) if the bag does not have an entry with
that key k: K.

Aborts with [sui::dynamic_field::EFieldTypeMismatch](../sui_sui/dynamic_field#sui_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: store>(bag: &mut sui::bag::Bag, k: K): &mut V
```

## Function remove

Mutably borrows the key-value pair in the bag [bag](../sui_sui/bag#sui_bag): &**mut** [Bag](../sui_sui/bag#sui_bag_Bag) and returns the value.

Aborts with [sui::dynamic_field::EFieldDoesNotExist](../sui_sui/dynamic_field#sui_dynamic_field_EFieldDoesNotExist) if the bag does not have an entry with
that key k: K.

Aborts with [sui::dynamic_field::EFieldTypeMismatch](../sui_sui/dynamic_field#sui_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: store>(bag: &mut sui::bag::Bag, k: K): V
```

## Function contains

Returns true iff there is an value associated with the key k: K in the bag [bag](../sui_sui/bag#sui_bag): &[Bag](../sui_sui/bag#sui_bag_Bag)

```
public fun contains<K: copy, drop, store>(bag: &sui::bag::Bag, k: K): bool
```

## Function contains_with_type

Returns true iff there is an value associated with the key k: K in the bag [bag](../sui_sui/bag#sui_bag): &[Bag](../sui_sui/bag#sui_bag_Bag)
with an assigned value of type V

```
public fun contains_with_type<K: copy, drop, store, V: store>(bag: &sui::bag::Bag, k: K): bool
```

## Function length

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

```
public fun length(bag: &sui::bag::Bag): u64
```

## Function is_empty

Returns true iff the bag is empty (if [length](../sui_sui/bag#sui_bag_length) returns 0)

```
public fun is_empty(bag: &sui::bag::Bag): bool
```

## Function destroy_empty

Destroys an empty bag.

Aborts with [EBagNotEmpty](../sui_sui/bag#sui_bag_EBagNotEmpty) if the bag still contains values

```
public fun destroy_empty(bag: sui::bag::Bag)
```