Maps and big maps ​

Maps ​

Maps in SmartPy are of type sp.TMap(tKey, tValue).
The corresponding type in Michelson is

Michelson map

See reference Lists and Maps template.

Literals ​

sp.map(l = ..., tkey = ..., tvalue = ...) or { 0 : "aa", 12 : "bb" }
Define a map of (optional) elements in l (a Python dictionary) with optional key type tkey and optional value type tvalue.

Example ​

my_map = sp.map(l = {0 : "aa", 12 : "bb" }, tkey = sp.TNat, tvalue = sp.TString)

# Standard Python dictionaries are also accepted
my_map = {0 : "aa", 12 : "bb" }

See

Michelson EMPTY_MAP

and

Michelson PUSH

Adding/Updating entries ​

<my_map>[key] = <new_value>
Set or replace an element in a map.

Example ​

my_map[key] = value

sp.update_map(map, key, value)
Return a new copy of map my_map where key has optional value value (sp.none to delete).

Example ​

# Update entry with key `0` to have value `"cc"`
my_map = sp.update_map(my_map, 0, sp.some("cc"))

sp.get_and_update(map, key, value)
Return two elements, the previous optional value (sp.none if missing) and a new map as sp.update_map would do.

Example ​

(previous_value, new_map) = sp.get_and_update(my_map, 1, sp.some("dd"))

Michelson UPDATE

Deleting entries ​

del my_map[key]
Delete an element from a map.

Example ​

my_map = sp.map({ 1: "aa", 2: "bb" })
del my_map[1] # my_map == { 2: "bb" }

sp.update_map(my_map, key, sp.none)
Return a new copy of map my_map where sp.none value is used to remove the entry.

Example ​

# Remove entry with key `1`
my_map = sp.update_map({ 1: "aa", 2: "bb" }, 1, sp.none) # my_map == { 2: "bb" }

sp.get_and_update(my_map, key, sp.none)
Return two elements, the previous optional value (sp.none if missing) and a new map as sp.update_map would do.

Example ​

# Remove entry with key `1` and return the previous and new state of the map
(previous_value, new_map) = sp.get_and_update({ 1: "aa", 2: "bb" }, 1, sp.none) # previous_value = { 1: "aa", 2: "bb" }, new_map == { 2: "bb" }

Access entry value ​

<my_map>[key]
Look up an entry in a map. It fails if the entry is not found. key must have the type of its keys.

Example ​

sp.map({ 1: "aa", 2: "bb" })[1] # "aa"

<my_map>.get(key, default_value = None, message = None)
Same as my_map[key]. If default_value is specified and there is no entry for key in my_map, returns default_value instead of failing. If default_value is not specified and the is no entry for key, it fails with message if present.

Example ​

sp.map({ 1: "aa", 2: "bb" }).get(1) # "aa"

<my_map>.get_opt(key)
Look up an entry in a map. It returns sp.some(<value>) if found, sp.none otherwise. key must have the type of its keys.

Example ​

my_map.get_opt(key)

Michelson GET

Check key existence ​

<my_map>.contains(key)
Check whether the map my_map contains the key.

Example ​

sp.map({ 1: "aa", 2: "bb" }).contains(1) # True

Work in progress...

Michelson MEM

Get size ​

sp.len(my_map)
Return the size of the map my_map.

Example ​

self.data.my_map = { 1: "aa", 2: "bb" }
sp.len(self.data.my_map) # 2

Michelson SIZE

Get entries ​

<my_map>.items()
Return the sorted list of key-value entries in a map. Each entry is rendered as record with the two fields key and value.

Example ​

sp.map({ 1: "aa", 2: "bb" }).items() # [{ key: 1, value: "aa" }, { key: 2, value: "bb" }]

Get Keys ​

<my_map>.keys()
Return the sorted list of keys of a map.

Example ​

sp.map({ 1: "aa", 2: "bb" }).keys() # [1, 2]

Get values ​

<my_map>.values()
Return the list of values of a map, sorted by keys.

Example ​

sp.map({ 1: "aa", 2: "bb" }).values() # ["aa", "bb"]

Big maps ​

Big maps, of type sp.TBigMap(key, value)`, are lazy data structures that are only serialized and deserialized on demand.
The corresponding type in Michelson is

Michelson big_map

We cannot iterate on big maps or compute their sizes.

See reference Lists template.

Literals ​

sp.big_map(l = ..., tkey = ..., tvalue = ...)
Define a big_map of (optional) elements in l (a Python dictionary) with optional key type tkey and optional value type tvalue.

Example ​

my_big_map = sp.big_map(l = {0 : "aa", 12 : "bb" }, tkey = sp.TNat, tvalue = sp.TString)

Michelson EMPTY_BIG_MAP

Adding/Updating entries ​

<my_big_map>[key] = <new_value>
Set or replace an element in a big_map.

Example ​

my_big_map[key] = value

sp.update_map(my_big_map, 0, sp.some("cc"))
Return a new copy of big_map my_big_map where key has optional value value (sp.none to delete).

Example ​

# Update entry with key `0` to have value `"cc"`
my_big_map = sp.update_map({ 0 : "aa", 1 : "bb" }, 0, sp.some("cc"))

sp.get_and_update(my_big_map, 1, sp.some("dd"))
Return two elements, the previous optional value (sp.none if missing) and a new big_map as sp.update_map would do.

Example ​

(previous_value, new_big_map) = sp.get_and_update({ 0 : "aa", 1 : "bb" }, 1, sp.some("dd"))

Michelson UPDATE

Deleting entries ​

del my_big_map[key]
Delete an element from a big_map.

Example ​

my_big_map = sp.big_map({ 0: "aa", 1: "bb" })
del my_big_map[0]

sp.update_map(my_big_map, 0, sp.none)
Return a new copy of big_map my_big_map where sp.none value is used to remove the entry.

Example ​

# Remove entry with key `0`
my_big_map = sp.update_map({ 0 : "aa", 1 : "bb" }, 0, sp.none)

sp.get_and_update(my_big_map, 0, sp.none)
Return two elements, the previous optional value (sp.none if missing) and a new big_map as sp.update_map would do.

Example ​

# Remove entry with key `1` and return the previous and new state of the big_map
(previous_value, new_map) = sp.get_and_update({ 0 : "aa", 1 : "bb" }, 1, sp.none)

Access entry value ​

Look up an entry in a big_map. It fails if the entry is not found. key must have the type of its keys.

Example ​

my_big_map[key]

<my_big_map>.get(key, default_value = None, message = None)
Same as my_big_map[key]. If default_value is specified and there is no entry for key in my_big_map, returns default_value instead of failing. If default_value is not specified and the is no entry for key, it fails with message if present.

Example ​

my_big_map.get(key, default_value = None)

<my_big_map>.get_opt(key)
Look up an entry in a big_map. It returns sp.some(<value>) if found, sp.none otherwise. key must have the type of its keys.

Example ​

my_big_map.get_opt(key)

Michelson GET

Check key existence ​

<my_big_map>.contains(key)
Check whether the big_map my_big_map contains the key.

Example ​

my_big_map.contains(key)

Michelson MEM