From ebaa913c5aab21a98fc4480f2beb99aaf292a87d Mon Sep 17 00:00:00 2001 From: John David Pressman Date: Tue, 26 Nov 2019 04:08:16 -0800 Subject: [PATCH 1/3] Add better explanation of tuples and map iterator docs --- .../docs/language-basics/maps-records.md | 65 +++++++++++++++++++ .../language-basics/sets-lists-touples.md | 24 ++++++- 2 files changed, 88 insertions(+), 1 deletion(-) diff --git a/gitlab-pages/docs/language-basics/maps-records.md b/gitlab-pages/docs/language-basics/maps-records.md index 96a5bca9b..25b9367e0 100644 --- a/gitlab-pages/docs/language-basics/maps-records.md +++ b/gitlab-pages/docs/language-basics/maps-records.md @@ -85,8 +85,73 @@ const balance: tez = get_force(("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) ```cameligo let balance: tez = Map.find ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) ledger ``` + +### Iteration over the contents of a map + +There are three kinds of iteration on LIGO maps, `iter`, `map` and `fold`. `iter` +is an imperative iteration over the map with no return value, its only use is to +generate side effects. This can be useful if for example you would like to check +that each value inside of a map is within a certain range, with an error thrown +otherwise. + + + +```pascaligo +function iter_op (const m : ledger) : unit is + block { + function aggregate (const i : address ; const j : tez) : unit is block + { if (j > 100) then skip else failwith("fail") } with unit ; + } with map_iter(aggregate, m) ; +``` + + +```cameligo +let iter_op (m : ledger) : unit = + let assert_eq = fun (i: address) (j: tez) -> assert (j > 100) + in Map.iter assert_eq m +``` + + +`map` is a way to create a new map by modifying the contents of an existing one. + + + +```pascaligo +function map_op (const m : ledger) : ledger is + block { + function increment (const i : address ; const j : tez) : tez is block { skip } with j + 1 ; + } with map_map(increment, m) ; +``` + + +```cameligo +let map_op (m : ledger) : ledger = + let increment = fun (_: address) (j: tez) -> j+1 + in Map.map increment m +``` + + +`fold` is an aggregation function that return the combination of a maps contents. + + + +```pascaligo +function fold_op (const m : ledger) : tez is + block { + function aggregate (const i : address ; const j : (tez * tez)) : tez is block { skip } with j.0 + j.1 ; + } with map_fold(aggregate, m , 10) +``` + + +```cameligo +let fold_op (m : ledger) : ledger = + let aggregate = fun (_: address) (j: tez * tez) -> j.0 + j.1 + in Map.fold aggregate m 10 +``` + + ## Records diff --git a/gitlab-pages/docs/language-basics/sets-lists-touples.md b/gitlab-pages/docs/language-basics/sets-lists-touples.md index 8e2eb6679..5c71338c8 100644 --- a/gitlab-pages/docs/language-basics/sets-lists-touples.md +++ b/gitlab-pages/docs/language-basics/sets-lists-touples.md @@ -207,10 +207,24 @@ let sum_of_a_list: int = List.fold sum my_list 0 ## Tuples -Tuples are useful for data that belong together but don't have an index or a specific name. +Tuples are used to store related data that has a **specific order** and **defined +length** without the need for named fields or a dedicated type identity. Probably +the most common tuple is a pair of type `(a, b)`. For example, if we were storing +coordinates on a two dimensional grid we might use a pair tuple of type `int * int` +to store the coordinates x and y. There is a **specific order** because x and y must +always stay in the same location within the tuple for the data to make sense. There is +also a **defined length** because the tuple pair can only ever have two elements, +if we added a third dimension `z` its type would be incompatible with that of the +pair tuple. + +Like records, tuples can have members of arbitrary types in the same structure. ### Defining a tuple +Unlike [a record](language-basics/maps-records.md), tuple types do not have to be +defined before they can be used. However below we will give them names for the +sake of illustration. + ```pascaligo @@ -229,6 +243,14 @@ let full_name: full_name = ("Alice", "Johnson") ### Accessing an element in a tuple + +The traditional way to access the elements of a tuple in OCaml is through +[a pattern match](language-basics/unit-option-pattern-matching.md). LIGO **does +not** currently support tuple patterns in its syntaxes. + +However, it is possible to access LIGO tuples by their position. +Tuple elements are one-indexed and accessed like so: + ```pascaligo From d23819245ffde065b2f874ebd82337a12886dd9a Mon Sep 17 00:00:00 2001 From: John David Pressman Date: Tue, 26 Nov 2019 05:39:54 -0800 Subject: [PATCH 2/3] Add explanation of folding to the map fold --- gitlab-pages/docs/language-basics/maps-records.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/gitlab-pages/docs/language-basics/maps-records.md b/gitlab-pages/docs/language-basics/maps-records.md index 25b9367e0..64b44c2e5 100644 --- a/gitlab-pages/docs/language-basics/maps-records.md +++ b/gitlab-pages/docs/language-basics/maps-records.md @@ -135,6 +135,13 @@ let map_op (m : ledger) : ledger = `fold` is an aggregation function that return the combination of a maps contents. +The fold is a loop which extracts an element of the map on each iteration. It then +provides this element and an existing value to a folding function which combines them. +On the first iteration, the existing value is an initial expression given by the +programmer. On each subsequent iteration it is the result of the previous iteration. +It eventually returns the result of combining all the elements. + + ```pascaligo From 0908338616c632b220ec3f946164cf55024aeea3 Mon Sep 17 00:00:00 2001 From: John David Pressman Date: Tue, 26 Nov 2019 05:40:41 -0800 Subject: [PATCH 3/3] Remove 'imperative' from phrase 'imperative iteration' --- gitlab-pages/docs/language-basics/maps-records.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gitlab-pages/docs/language-basics/maps-records.md b/gitlab-pages/docs/language-basics/maps-records.md index 64b44c2e5..7b8471290 100644 --- a/gitlab-pages/docs/language-basics/maps-records.md +++ b/gitlab-pages/docs/language-basics/maps-records.md @@ -91,7 +91,7 @@ let balance: tez = Map.find ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) le ### Iteration over the contents of a map There are three kinds of iteration on LIGO maps, `iter`, `map` and `fold`. `iter` -is an imperative iteration over the map with no return value, its only use is to +is an iteration over the map with no return value, its only use is to generate side effects. This can be useful if for example you would like to check that each value inside of a map is within a certain range, with an error thrown otherwise.