balsoft/ligo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge branch 'website/records_docs' into 'dev'

Browse Source 
Website/records docs

See merge request ligolang/ligo!644
This commit is contained in:
Jev Björsell 2020-05-27 14:58:11 +00:00
commit c19c34d5d3
1 changed files with 27 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
gitlab-pages/docs/language-basics/maps-records.md
View File

@ -5,12 +5,12 @@ title: Records and Maps
import Syntax from '@theme/Syntax'; import Syntax from '@theme/Syntax';
So far we have seen pretty basic data types. LIGO also offers more So far, we have seen pretty basic data types. LIGO also offers more
complex built-in constructs, such as *records* and *maps*. complex built-in constructs, such as *records* and *maps*.
## Records ## Records
Records are one way data of different types can be packed into a Records are one-way data of different types can be packed into a
single type. A record is made of a set of *fields*, which are made of single type. A record is made of a set of *fields*, which are made of
a *field name* and a *field type*. Given a value of a record type, the a *field name* and a *field type*. Given a value of a record type, the
value bound to a field can be accessed by giving its field name to a value bound to a field can be accessed by giving its field name to a
@ -18,8 +18,6 @@ special operator (`.`).
Let us first consider and example of record type declaration. Let us first consider and example of record type declaration.
<Syntax syntax="pascaligo"> <Syntax syntax="pascaligo">
```pascaligo group=records1 ```pascaligo group=records1
@ -55,10 +53,8 @@ type user = {
</Syntax> </Syntax>
And here is how a record value is defined: And here is how a record value is defined:
<Syntax syntax="pascaligo"> <Syntax syntax="pascaligo">
```pascaligo group=records1 ```pascaligo group=records1
@ -142,7 +138,7 @@ points on a plane.
In PascaLIGO, the shape of that expression is In PascaLIGO, the shape of that expression is
`<record variable> with <record value>`. `<record variable> with <record value>`.
The record variable is the record to update and the The record variable is the record to update, and the
record value is the update itself. record value is the update itself.
```pascaligo group=records2 ```pascaligo group=records2
@ -160,13 +156,13 @@ following command of the shell:
```shell ```shell
ligo run-function ligo run-function
gitlab-pages/docs/language-basics/src/maps-records/record_update.ligo gitlab-pages/docs/language-basics/src/maps-records/record_update.ligo
translate "(record [x=2;y=3;z=1], record [dx=3;dy=4])" xy_translate "(record [x=2;y=3;z=1], record [dx=3;dy=4])"
# Outputs: {z = 1 , y = 7 , x = 5} # Outputs: {z = 1 , y = 7 , x = 5}
``` ```
You have to understand that `p` has not been changed by the functional You have to understand that `p` has not been changed by the functional
update: a namless new version of it has been created and returned by update: a nameless new version of it has been created and returned by
the blockless function. the block-less function.
</Syntax> </Syntax>
<Syntax syntax="cameligo"> <Syntax syntax="cameligo">
@ -186,6 +182,7 @@ let xy_translate (p, vec : point * vector) : point =
You can call the function `xy_translate` defined above by running the You can call the function `xy_translate` defined above by running the
following command of the shell: following command of the shell:
```shell ```shell
ligo run-function ligo run-function
gitlab-pages/docs/language-basics/src/maps-records/record_update.mligo gitlab-pages/docs/language-basics/src/maps-records/record_update.mligo
@ -218,6 +215,7 @@ let xy_translate = ((p, vec) : (point, vector)) : point =>
You can call the function `xy_translate` defined above by running the You can call the function `xy_translate` defined above by running the
following command of the shell: following command of the shell:
```shell ```shell
ligo run-function ligo run-function
gitlab-pages/docs/language-basics/src/maps-records/record_update.religo gitlab-pages/docs/language-basics/src/maps-records/record_update.religo
@ -326,12 +324,21 @@ let change_color_preference = (account : account, color : color): account =>
Note that all the records in the path will get updated. In this example that's Note that all the records in the path will get updated. In this example that's
`account` and `preferences`. `account` and `preferences`.
You can call the function `change_color_preference` defined above by running the
following command:
```shell
ligo run-function gitlab-pages/docs/language-basics/src/maps-records/record_nested_update.ligo
change_color_preference "(record [id=1001; preferences=record [color=Blue; other=1]], Green)"
# Outputs: record[id -> 1001 , preferences -> record[color -> Green(unit) , other -> 1]]
```
<Syntax syntax="pascaligo"> <Syntax syntax="pascaligo">
### Record Patches ### Record Patches
Another way to understand what it means to update a record value is to Another way to understand what it means to update a record value is to
make sure that any further reference to the value afterwards will make sure that any further reference to the value afterward will
exhibit the modification. This is called a `patch` and this is only exhibit the modification. This is called a `patch` and this is only
possible in PascaLIGO, because a patch is an *instruction*, therefore possible in PascaLIGO, because a patch is an *instruction*, therefore
we can only use it in a block. Similarly to a *functional update*, a we can only use it in a block. Similarly to a *functional update*, a
@ -355,6 +362,7 @@ function xy_translate (var p : point; const vec : vector) : point is
You can call the function `xy_translate` defined above by running the You can call the function `xy_translate` defined above by running the
following command of the shell: following command of the shell:
```shell ```shell
ligo run-function ligo run-function
gitlab-pages/docs/language-basics/src/maps-records/record_patch.ligo gitlab-pages/docs/language-basics/src/maps-records/record_patch.ligo
@ -378,6 +386,7 @@ function xy_translate (var p : point; const vec : vector) : point is
You can call the new function `xy_translate` defined above by running the You can call the new function `xy_translate` defined above by running the
following command of the shell: following command of the shell:
```shell ```shell
ligo run-function ligo run-function
gitlab-pages/docs/language-basics/src/maps-records/record_patch2.ligo gitlab-pages/docs/language-basics/src/maps-records/record_patch2.ligo
@ -401,6 +410,7 @@ function xy_translate (var p : point; const vec : vector) : point is
You can call the new function `xy_translate` defined above by running the You can call the new function `xy_translate` defined above by running the
following command of the shell: following command of the shell:
```shell ```shell
ligo run-function ligo run-function
gitlab-pages/docs/language-basics/src/maps-records/record_simu.ligo gitlab-pages/docs/language-basics/src/maps-records/record_simu.ligo
@ -425,8 +435,6 @@ sense.
Here is how a custom map from addresses to a pair of integers is Here is how a custom map from addresses to a pair of integers is
defined. defined.
<Syntax syntax="pascaligo"> <Syntax syntax="pascaligo">
```pascaligo group=maps ```pascaligo group=maps
@ -680,8 +688,8 @@ let assign = (m : register) : register =>
(("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), Some ((4,9)), m); (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), Some ((4,9)), m);
``` ```
Notice the optional value `Some (4,9)` instead of `(4,9)`. If we had Notice the optional value `Some (4,9)` instead of `(4,9)`. If we used
use `None` instead, that would have meant that the binding is removed. `None` instead that would have meant that the binding is removed.
As a particular case, we can only add a key and its associated value. As a particular case, we can only add a key and its associated value.
@ -693,7 +701,6 @@ let add = (m : register) : register =>
</Syntax> </Syntax>
To remove a binding from a map, we need its key. To remove a binding from a map, we need its key.
@ -748,8 +755,8 @@ There are three kinds of functional iterations over LIGO maps: the
The first, the *iterated operation*, is an iteration over the map with The first, the *iterated operation*, is an iteration over the map with
no return value: its only use is to produce side-effects. This can be no return value: its only use is to produce side-effects. This can be
useful if for example you would like to check that each value inside useful if, for example you would like to check that each value inside
of a map is within a certain range, and fail with an error otherwise. of a map is within a certain range and fail with an error otherwise.
The predefined functional iterator implementing the iterated operation The predefined functional iterator implementing the iterated operation
over maps is called `Map.iter`. In the following example, the register over maps is called `Map.iter`. In the following example, the register
@ -985,7 +992,7 @@ let moves : register =
(("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (0,3))] (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (0,3))]
``` ```
The predefind function `Big_map.literal` constructs a big map from a The predefined function `Big_map.literal` constructs a big map from a
list of key-value pairs `(<key>, <value>)`. Note also the semicolon list of key-value pairs `(<key>, <value>)`. Note also the semicolon
separating individual map entries. The annotated value `("<string> separating individual map entries. The annotated value `("<string>
value>" : address)` means that we cast a string into an address. value>" : address)` means that we cast a string into an address.
@ -1000,7 +1007,7 @@ let moves : register =
("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address, (0,3))]); ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address, (0,3))]);
``` ```
The predefind function `Big_map.literal` constructs a big map from a The predefined function `Big_map.literal` constructs a big map from a
list of key-value pairs `(<key>, <value>)`. Note also the semicolon list of key-value pairs `(<key>, <value>)`. Note also the semicolon
separating individual map entries. The annotated value `("<string> separating individual map entries. The annotated value `("<string>
value>" : address)` means that we cast a string into an address. value>" : address)` means that we cast a string into an address.