An asset is defined by a set of fields, one of which is the identification field. Each asset has a unique identification value over the collection of assets.
For example, the following defines a car asset:
1
asset car {
2
vin: string;
3
model: string;
4
year: nat;
5
nbdoors: nat;
6
}
Copied!
By default, the first field is used as the asset identifier. It is possible to specify another field with the identified by instruction. It is also possible to declare several fields to identify an asset:
1
asset allowance identified by owner spender {
2
owner: address;
3
spender: address;
4
amount: nat;
5
}
Copied!
Collection
Declaring an asset automatically creates a collection of these assets. This collection is named after the asset. In the example above, car refers to the collections of car assets. In a collection, each asset has a unique identifier.
Write
add
Use the add instruction to add an asset to the collection. It fails if an asset with the same id is already in the collection:
1
effect {
2
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
3
}
Copied!
update
Use the update instruction to update a field of an asset. It fails if the collection does not have an asset with the id:
1
effect {
2
/* update one field */
3
car.update("YS3ED48E5Y3070016",{ year =1967});
4
/* update severa fields */
5
car.update("YS3ED48E5Y3070016",{ year =1967; nbdoors =3});
It is possible to increment or decrement integer fields with the += and -= operators:
1
effect {
2
car.update("YS3ED48E5Y3070016",{ year +=2; nbdoors -=1});
3
}
Copied!
addupdate
Use the addupdate instruction to add or update an update. The argument asset is added if not already present or updated if present. It does not fail.
1
effect {
2
// all fiels are necessary, no field name required
3
car.addupdate("YS3ED48E5Y3070016",{ model ="mustang";
4
year =1968;
5
nbdoors =2});
6
}
Copied!
remove
Use the remove instruction to remove an asset.
1
effect {
2
car.remove("YS3ED48E5Y3070016");
3
}
Copied!
removedoes not fail if the collection does not have an asset with the id.
removeif
Use the removeif instruction to remove assets under given criteria. For example, in order to remove all cars with less than 4 doors:
1
effect {
2
car.removeif(the.nbdoors <4);
3
}
Copied!
The the keyword refers to the asset being evaluated.
Read an asset
The [ ] and . syntax is used to retrieve an asset and read a field value:
1
effect {
2
var amodel = car["YS3ED48E5Y3070016"].model;
3
...
4
}
Copied!
Views
Views are used to access assets in a different way than the base collection seen above. They enable access with a different order, position range, or specific criteria.
You cannot build a view from scratch. It is derived from a collection with the operators presented below. Note at last that you cannot modify the collection through a view.
As for collections, views guarantee the order of the assets. By default, assets are ordered by identification field values, unless an explicit sort is invoked.
Note that collections are automatically transformed to views when necessary. As a consequence, you may use the view API presented below straightforwardly on collections; for example car.count() returns the number of car asset in the car collection.
Create
head
head returns the first n elements of the collection or view. By default assets are ordered by the identification field. It fails if n is greater than the number of elements in the collection or view (or negative).
1
effect {
2
car.clear();
3
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
4
car.add({"3VWCK21Y33M306146";"fiesta";2010;4});
5
car.add({"1FTDF15Y2SNB02216";"focus";2008;4});
6
var v = car.head(2);// view creation :
7
// v has 1FTDF15Y2SNB02216 and 3VWCK21Y33M306146 assets
8
...
9
}
Copied!
tail
tail returns the last n elements of the collection or view. By default assets are ordered by the identification field. It fails if n is greater than the number of elements in the collection or view (or negative).
1
effect {
2
car.clear();
3
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
4
car.add({"3VWCK21Y33M306146";"fiesta";2010;4});
5
car.add({"1FTDF15Y2SNB02216";"focus";2008;4});
6
var v = car.tail(1);// view creation :
7
// v has only the YS3ED48E5Y3070016 asset
8
...
9
}
Copied!
sort
sort provides access to assets in a different order than the default one based on the identification order.
1
effect {
2
car.clear();
3
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
4
car.add({"3VWCK21Y33M306146";"fiesta";2010;4});
5
car.add({"1FTDF15Y2SNB02216";"focus";2008;4});
6
var v = car.sort(nbdoors);
7
if v.nth(0)="YS3ED48E5Y3070016"then transfer 1tz to coder;
8
if v.nth(1)="1FTDF15Y2SNB02216"then transfer 1tz to coder;
9
if v.nth(2)="3VWCK21Y33M306146"then transfer 1tz to coder;
10
}
Copied!
Note in the example below that the sort operator preserves the initial order for assets with the same criterion. In this example, 1FTDF15Y2SNB02216 comes before 3VWCK21Y33M306146.
It is possible to specify the descending order with the desc operator:
1
var v = car.sort(desc(nbdoors));
Copied!
sort is not stable; it means that two assets with equal sort values do not appear in the same order in sorted output as they appear in the input view.
As a consequence, if you want to sort a collection according to two fields f1and f2, the following will not provide what you want:
1
myasset.sort(f1).sort(f2);
Copied!
The solution is to pass the fields as arguments to the sort operator:
1
myasset.sort(f1, f2);
Copied!
Do not chain sort operations; rather call one sort operation with the fields as arguments.
select
select returns a view with assets that satisfy a criterion:
1
effect {
2
car.clear();
3
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
4
car.add({"3VWCK21Y33M306146";"fiesta";2010;4});
5
car.add({"1FTDF15Y2SNB02216";"focus";2008;4});
6
var v = car.select(the.nbdoors =4);// view creation
7
// v contains 3VWCK21Y33M306146 and
8
// 3VWCK21Y33M306146 assets
9
...
10
}
Copied!
As in removeif above, the the keyword refers to the asset being evaluated.
Test membership
contains returns true if the view or collection contains a key.
1
effect {
2
car.clear();
3
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
4
if car.contains("YS3ED48E5Y3070016")then transfer 1tz to coder;
5
}
Copied!
Access by position
nth returns the key at position n in the view. By default assets are ordered by the identification field. It fails if n is out of the bounds of the collection.
1
effect {
2
car.clear();
3
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
4
car.add({"3VWCK21Y33M306146";"fiesta";2010;4});
5
if car.nth(0)="3VWCK21Y33M306146"then transfer 1tz to coder;
6
if car[car.nth(0)].model ="mustang"then transfer 1tz to coder;
7
}
Copied!
Summerize
count
count returns the number of elements in a collection:
1
effect {
2
car.clear();
3
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
4
if car.count()=1then transfer 1tz to coder;
5
}
Copied!
sum
sum returns the sum of a field:
1
effect {
2
car.clear();
3
car.add({"YS3ED48E5Y3070016";"mustang";1968;2});
4
car.add({"3VWCK21Y33M306146";"fiesta";2010;4});
5
car.add({"1FTDF15Y2SNB02216";"focus";2008;4});
6
if car.sum(nbdoors)=10then transfer 1tz to coder;
7
}
Copied!
Iterate
It is possible to iterate a view with the for ... in ... do ... done loop instruction.
1
effect {
2
for k in car.select(the.year >=2010)do
3
car.update(k,{ nbdoors +=1});
4
done;
5
}
Copied!
The example above increments nbdoors of cars with year above 2010.
Note that the iteration is done over asset keys.
Clear
Use the clear instruction to remove all asset referenced in a view:
1
effect {
2
car.select(the.year =2000).clear();
3
}
Copied!
clear is the only view instruction that changes the contract data.