# Lists, sets, and maps ​

## Lists ​

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

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

Returns the length of a list, e.g. `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, e.g. `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]

`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]`.

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

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

Returns the number of elements in a set.

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

For a set `m` of type `sp.set[t]`, returns a boolean value indicating whether `x` is an element of `s`.

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

For a set `s` of type `sp.set[t]` returns its elements as a list.

Adds an element to a set. For example:

smartpy
``````s = {1, 2, 3}
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. `sp.map({'a': 65}, {'b': 66})`.

m[...]

An entry can be looked up with the `m[...]` notation, e.g.:

smartpy
``````m = {'a': 65, 'b': 66}
assert m['a'] == 65``````
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.

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, i.e. 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 ​

Analogous to `sp.map` there is `sp.big_map[k, v]`, denoting lazily deserialized maps from `k` to `v`. These maps should be used if you intend to store large amounts of data in a map. Using `sp.big_map` can reduce gas costs significantly compared to standard maps, as 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, since only the hash of each key is stored in a `sp.big_map`.

A `sp.big_map` cannot be iterated over, nor contained in another big map.