Merge branch 'docs/iterators' into 'dev'

Add better explanation of tuples and map iterator docs

See merge request ligolang/ligo!223

gitlab-pages/docs/language-basics/maps-records.md

@@ -85,8 +85,80 @@ const balance: tez = get_force(("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address)
 ```cameligo
 let balance: tez = Map.find ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) ledger
 ```
+
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+### Iteration over the contents of a map
+
+There are three kinds of iteration on LIGO maps, `iter`, `map` and `fold`. `iter`
+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.
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Pascaligo-->
+```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-->
+```cameligo
+let iter_op (m : ledger) : unit =
+  let assert_eq = fun (i: address) (j: tez) -> assert (j > 100)
+  in Map.iter assert_eq m
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+`map` is a way to create a new map by modifying the contents of an existing one.
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Pascaligo-->
+```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-->
+```cameligo
+let map_op (m : ledger) : ledger =
+  let increment = fun (_: address) (j: tez) -> j+1
+  in Map.map increment m
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+`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.
+
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Pascaligo-->
+```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-->
+```cameligo
+let fold_op (m : ledger) : ledger =
+  let aggregate = fun (_: address) (j: tez * tez) -> j.0 + j.1
+  in Map.fold aggregate m 10
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 ## Records
 

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.
+
 <!--DOCUSAURUS_CODE_TABS-->
 <!--Pascaligo-->
 ```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:
+
 <!--DOCUSAURUS_CODE_TABS-->
 <!--Pascaligo-->
 ```pascaligo