ligo/gitlab-pages/docs/reference/map.md

id	title
map-reference	Map

Defining A Map Type

type move is int * int
type register is map (address, move)

type move = int * int
type register = (address, move) map

type move = (int, int);
type register = map (address, move);

Creating an Empty Map

Create an empty map.

const empty : register = map []

let empty : register = Map.empty

let empty : register = Map.empty

Populating A Map

const moves: register =
  map [
    ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address) -> (1,2);
    ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) -> (0,3)]

let moves: register =
  Map.literal [
    (("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address), (1,2));
    (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (0,3))]

let moves: register =
  Map.literal ([
    ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address, (1,2)),
    ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address, (0,3))]);

Retrieving a Value in a Map

Retrieve the value associated with a particular key. This version returns an option which can either shift logic in response to a missing value or throw an error.

const my_balance : option (move) =
  moves [("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address)]

The function is Map.find_opt whose type is 'key -> ('key,'value) map) -> 'value option. Recall that the function Map.find_opt must always be fully applied to its arguments. Here is an example:

let my_balance : move option =
  Map.find_opt ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) moves

The function is Map.find_opt whose type is ('key, ('key, 'value) map) : 'value option. Here is an example:

let my_balance : option (move) =
  Map.find_opt ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address, moves);

Updating a Binding in a Map

Given a map, we may want to add a new binding, remove one, or modify one by changing the value associated to an already existing key. We may even want to retain the key but not the associated value. All those operations are called updates.

The values of a PascaLIGO map can be updated using the ordinary assignment syntax:

function add (var m : register) : register is
  block {
    m [("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address)] := (4,9)
  } with m

const updated_map : register = add (moves)

See further for the removal of bindings.

In CameLIGO, you need the predefined function Map.update whose type is 'key -> 'value option -> ('key, 'value) map -> ('key, 'value) map. If the value (second argument) is None, then the binding is to be removed. Recall that the function Map.update must always be fully applied to its arguments. Here is an example:

let updated_map : register =
  Map.update
    ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) (Some (4,9)) moves

In ReasonLIGO, you need the predefined function Map.update whose type is ('key, 'value option, ('key, 'value) map) : ('key, 'value) map. If the value (second componenat) is None, then the binding is to be removed. Here is an example:

let updated_map : register =
  Map.update
    (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), Some ((4,9)), moves);

Adding a Binding to a Map

Add a key and its associated value to the map.

function add (var m : register) : register is
  block {
    m [("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address)] := (4,9)
  } with m

const updated_map : register = add (moves)

In CameLIGO, we use the predefined function Map.add, whose type is 'key -> 'value -> ('key, 'value) map -> ('key, 'value) map. Recall that the function Map.add must always be fully applied to its arguments. Here is an example:

let add (m : register) : register =
  Map.add
    ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) (4,9) m

In ReasonLIGO, we use the predefined function Map.add, whose type is ('key, 'value, ('key, 'value) map : ('key, 'value) map. Here is an example:

let add = (m : register) : register =>
  Map.add
    (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (4,9), m);

Removing a Binding from a Map

Remove a key and its associated value from the map.

function delete (const key : address; var moves : register) : register is
  block {
    remove key from map moves
  } with moves

In CameLIGO, we use the predefined function Map.remove whose type is 'key -> ('key, 'value) map -> ('key, 'value) map. Note that, despite being curried, the calls to that function must be complete. Here is an example:

let delete (key, moves : address * register) : register =
  Map.remove key moves

In ReasonLIGO, we use the predefined function Map.remove whose type is ('key, ('key, 'value) map) : ('key, 'value) map. Here is an example:

let delete = ((key, moves) : (address, register)) : register =>
  Map.remove (key, moves);

Getting the Size of a Map

The size of a map is its number of bindings.

function size_of (const m : register) : nat is size (m)

let size_of (m : register) : nat = Map.size m

let size_of = (m : register): nat => Map.size (m);