Version: 0.11.0

Big_map

A lazily deserialized map that's intended to store large amounts of data. "Lazily" means that storage is read or written per key on demand. Therefore there are no map, fold, and iter operations as there are in Map.

Compared to non-lazy maps, which have a high upfront gas cost to deserialize all the data and then have cheaper access costs thereafter, lazily-deserialized maps spread this cost out across each access, increasing the per-access gas costs, but providing a cheaper overall cost when only a small portion of a large dataset is needed.

function empty : big_map ('key, 'value)

Create an empty big_map.

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

const empty : register = Big_map.empty

Alternatively, you can also create an empty big_map using:

const empty_alternative : register = big_map []

function literal : list ('key * 'value) -> big_map ('key, 'value)

Create a non-empty big_map.

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

Alternative way of creating an empty big_map:

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

function find_opt : 'key -> big_map ('key, 'value) -> option 'value

Retrieve a value from a big map with the given key.

Because the key may be missing in the big map, the result is an optional value.

const my_balance : option (move) =
  Big_map.find_opt (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), moves)

Alternatively:

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

function mem : 'key -> big_map ('key, 'value) -> bool

Test whether a given key exists within a big map.

const has_balance : bool =
  Big_map.mem (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), moves)

function update : 'key -> option 'value -> big_map ('key, 'value) -> big_map ('key, 'value)

Note: when None is used as a value, the value is removed from the big_map.

  const updated_big_map : register = Big_map.update(("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), Some (4,9), moves);

Alternatively:

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

If multiple bindings need to be updated, PascaLIGO offers a patch instruction for maps, similar to that for records.

function assignments (var m : register) : register is
  block {
    patch m with map [
      ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) -> (4,9);
      ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address) -> (1,2)
    ]
  } with m

Note the use of the keyword map instead of big_map (which is not a keyword).

function get_and_update : key -> option(value) -> big_map (key, value) -> option(value) * big_map (key, value)

Similar to update but it also returns the value that was previously stored in the big_map

function add : 'key -> 'value -> big_map ('key, 'value) -> big_map ('key, 'value)

const added_item : register = Big_map.add (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (4, 9), moves)

function remove: 'key -> big_map ('key, 'value) -> big_map ('key, 'value)

  const updated_map : register = 
    Big_map.remove (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), moves)

Alternatively, the instruction remove key from map m removes the key key from the big map m (note that the keyword is map, not big_map).

function rem (var m : register) : register is
  block {
    remove ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) from map moves
  } with m

const updated_map : register = rem (moves)