Lists, sets, and maps ​

Lists ​

A list of elements of type t has type sp.list[t]. For example, the list [1, 2, 3] has type sp.list[sp.int].

SmartPy lists have different methods than Python lists. For example, to add an element to a SmartPy list, use its push() method, not the standard Python append() method.

len(x: sp.list[t]) → sp.nat

Returns the length of a list, for example len(["a", "b", "c"]) == 3.

sp.sum(xs: sp.list[sp.int]) → sp.int

sp.sum(xs: sp.list[sp.nat]) → sp.nat

Returns the sum of all the elements in a list, for example sp.sum([1, 2, 3]) == 6. Works on lists of both sp.nat and sp.int.

l.push(x: t) → 

Adds an element to the start of a list. For example:

smartpy

s = [1, 2, 3]
s.push(4)
# evaluates to `[4, 1, 2, 3]`

sp.cons(x: t, x: sp.list[t]) → sp.list[t]

Returns a new list with an element added to the front. For example sp.cons(1, [2, 3]) evaluates to [1, 2, 3].

sp.range(to: sp.nat) → sp.list[sp.nat]

sp.range(to: sp.int) → sp.list[sp.int]

sp.range(from_: sp.nat, to: sp.nat) → sp.list[sp.nat]

sp.range(from_: sp.int, to: sp.int) → sp.list[sp.int]

sp.range(from_: sp.nat, to: sp.nat, step: sp.nat) → sp.list[sp.nat]

sp.range(from_: sp.int, to: sp.int, step: sp.int) → sp.list[sp.int]

Get a series of numbers with the specified parameters.

sp.range(3) evaluates to [0, 1, 2].

sp.range(3, 7) evaluates to [3, 4, 5, 6].

sp.range(3, 7, 2) evaluates to [3, 5].

reversed(x: sp.list[t]) → sp.list[t]

Reverse and return a new list from the provided list. For example, reversed([1, 2, 3]) evaluates to [3, 2, 1].

for x in  l → 

Iterate over a list. For example:

smartpy

for x in [1, 2, 3]:
    self.data.result += x

Sets ​

A set containing elements of type t is represented as {...} and has the type sp.set[t]. For instance, the set {1, 2, 3} is of type sp.set[sp.int]. To create an empty set, use set().

SmartPy sets have different methods than Python sets. For example, to check if an element is in a SmartPy set, use its contains() method, not the standard Python in operator.

len(x: sp.set[t]) → sp.nat

Returns the number of elements in a set.

s.contains(x: t) → sp.bool

Returns a boolean value indicating whether x is an element of the set.

s.elements() → sp.list[t]

Returns the elements of a set as a list.

s.add(x: t) → 

Adds an element to a set. For example:

smartpy

s = {1, 2, 3}
s.add(4)
assert s.contains(4)

Maps ​

A map that takes elements of type k to elements of type v has type sp.map[k, v]. SmartPy maps are similar to Python's dictionaries.

You can access entries in a map with the m[...] notation, as in this example:

m = {'a': 65, 'b': 66}
assert m['a'] == 65
m['c'] = 67
assert m['c'] == 67

del  m[key: t] → 

An entry can be deleted from a map using the statement del m[key]. For example:

smartpy

m = {'a': 65, 'b': 66}
del m['a']
assert not m.contains('a')

m.get(key: k, default=...: v) → v

m.get(key: t, error=...: t) → v

Looks up key in the map m. If key does not have an entry in the map, default is returned or error is raised, according to which keyword argument is given. You must provide either default or error but not both.

m.get_opt('key: k') → sp.option[t]

Returns sp.Some(value) if the value is found in the map m, None otherwise.

len(x: sp.map[k, v]) → sp.nat

Returns the size of a map, which is the number of its entries.

m.items() → sp.list[sp.record(key=k, value=v)]

{'a': 97, 'b': 98}.items() evaluates to [sp.record(key='a', value=97), sp.record(key='b', value=98)].

m.keys() → sp.list[k]

{'a': 97, 'b': 98}.keys() evaluates to ['a', 'b'].

m.values() → sp.list[k]

{'a': 97, 'b': 98}.values() evaluates to [97, 98].

sp.update_map(key: k, value: sp.option[v], m: map[k, v]) → map[k, v]

Returns a copy of m with a modified entry at key: if value == None, it is removed; if value == sp.Some(v), it is v.

Example:

smartpy

assert sp.update_map('a', sp.Some(3), {})['a'] == 3
assert sp.update_map('a', None, {'a': 2}).get('a', default=-1) == -1

sp.get_and_update(key: k, value: sp.option[v], m: map[k, v]) → sp.pair[sp.option[v], map[k, v]]

Like sp.update_map, but also returns the old value of the map (or None if k had no entry).

Big maps ​

The type sp.big_map[k, v] is similar to sp.map, but it is lazily deserialized. Big maps are useful for storing large amounts of data in a map, such as a ledger of token owners. Using sp.big_map can reduce gas costs significantly compared to standard maps because data is lazily deserialized. Note however that individual operations on sp.big_map have higher gas costs than those over standard maps. A sp.big_map also has a lower storage cost than a standard map of the same size when large keys are used, because only the hash of each key is stored in a sp.big_map.

In SmartPy, big maps behave much like maps:

• You can get, add, or update an element in a big map with the m[...] notation just lke maps.
• You can use del to remove an element from big maps.
• Big maps have some of the same methods as maps, including get() and get_opt().
• You can use sp.update_map and sp.get_and_update to update big maps.

However, they have these differences:

• To create a big map, you must use the sp.big_map function.
• Big maps do not have these methods that maps have:
  • items()
  • keys()
  • values()
• You cannot iterate over a big map or put one inside another big map.