Felt252dict

Cairo currently supports a dictionary type called Felt252Dict that maps keys of type felt252 to other simple types, namely u8, u16, u32, u64, u128, felt252 and nullable<T>. The nullable<T> type enables the dictionary to contain more complex types.

By default, the value 0, or value logically equivalent to 0, is returned for non-existing keys.

Here is a simple usage example for a dictionary:

let mut dict = Felt252DictTrait::new();
    dict.insert(10, 110);
    dict.insert(11, 111);
    let val10 = dict[10]; // 110
    let val11 = dict[11]; // 111
    let val12 = dict[12]; // 0
    dict.insert(10, 120);
    let val10 = dict[10]; // 120

Dictionary Entry

Reading from a dictionary creates a copy of the value and thus requires the value to implement the Copy trait. However, dictionaries also support a special type of read access, using the dictionary entry method, which is useful for in-place updates of the dictionary.

To create an entry, call entry(key), which returns the current value of the given key and a Felt252DictEntry object. The Felt252DictEntry object is a temporary owner of the dictionary and can only be destructed by calling finalize(new_value) on it. This ensures that the dictionary is not used while it is being modified.

    let mut dict = Felt252DictTrait::new();
    dict.insert(10, 110);
    let (val10, entry) = dict.entry(10);
    let new_val = do_some_calculation(val10);
    entry.finalize(new_val);
    let val10 = dict[10]; // new_val

Dictionary Destruction

Dictionaries are automatically destroyed when they go out of scope. However, the destruction process of a dictionary is not trivial, and the Destruct trait is implemented for Felt252Dict`. This means that Destruct must be derived for any type that contains a dictionary. For more information, see the Destructors section.

    #[derive(Destruct)]
    struct MyStruct {
        dict: Felt252Dict,
    }