Asset

Parameter

a :

asset literal

Asset literal to be added, formed of the value of asset fields.

Fails with

(Pair "A" "KEY_EXISTS")

when an asset with same key is already in the collection. ("A" being the name of the asset collection).

Asset

put

update

remove

`A.put(a)`

Adds a new asset a in collection A, or replaces by asset a the asset in collection A with same key.

For example, given the following asset declaration with 5 fields:

asset loan {
  id         : string;
  subscriber : address;
  principal  : tez;
  interest   : rational = 2%;
  time       : duration = 10w; /* 10 weeks */
}

The following instruction adds or replaces asset "1a3245":

loan.put({
  id         = "1a3245";
  subscriber = tz1Lc2qBKEWCBeDU8npG6zCeCqpmaegRi6Jg;
  interest   = 5%;
  time       = 50w;
})

As for the add instruction, fields label may be omitted when all fields are specified:

loan.put({ "1a3245"; tz1Lc2qBKEWCBeDU8npG6zCeCqpmaegRi6Jg; 5%; 50w5d })

Fields with default values (like interest and time) may be omitted in asset literal; other fields labels must then be present:

loan.put({
  id         = "1a3245";
  subscriber = tz1Lc2qBKEWCBeDU8npG6zCeCqpmaegRi6Jg;
})  /* interest and time are defaulted to 2% and 10 weeks respectively */

Type of collection `A`

Parameter

a :

asset literal

Asset literal to be added.

Fails with

does not fail

Asset

add

update

remove

`A.update(k, { u })`

Updates one or several fields of asset with key k in collection A, and fails when kis not found in A.

For example, consider the car asset:

asset car {
  vin        : string;
  nb_doors   : nat;
  nb_repairs : nat;
  owner      : address;
}

The following instruction increments nbrepairs and assigns owner:

car.update("1G1AF1F57A7192174", {
  nb_repairs += 1;
  owner     := tz1Lc2qBKEWCBeDU8npG6zCeCqpmaegRi6Jg
})

An "inlined" syntax for update is available; for example the update instruction above is equivalent to:

var k = "1G1AF1F57A7192174";
car[k].nb_repairs += 1;
car[k].owner := tz1Lc2qBKEWCBeDU8npG6zCeCqpmaegRi6Jg;

Basic containers

Maps and sets fieds may be updated with := += and -= update instructions.

For example, consider the following asset declaration:

asset my_asset {
  id : nat;
  m  : map<string, bytes>;
} initialized with {
  {0; []}
}

The following associates 3 values to "k" "l" and "m" keys in map field m of asset 0:

my_asset.update(0, { m += [("k", 0x00); ("l", 0x01); ("m", 0x02)] });

The += instruction overwrites any previous association.

The following removes key "k" in m of asset 0:

my_asset.add_update(0, { m -= ["k"] });

Aggregate and partition

A partition or aggregate field does not provide the update instruction, as it does not impact the reference to the asset. The update instruction is done straightorwardly on the (partitioned or aggregated) asset collection.

Asset view

As a read-only set of asset references, an asset_view does not provide the update instruction.

Type of collection `A`

Parameters

k :

Key of the asset to update fields of.

u :

update literal

Curly bracketed list of fields' assignment instructions (separated by ;); these instructions are presented in the assignment section (:= += -= *= /= &= |=).

Fails with

(Pair "A" "ASSET_NOT_FOUND")

when no asset with key k is in the collection ("A" being the name of the asset collection).

Asset

Assignment

add_update

`A.update_all({ u })`

Updates one or several fields of all assets of a collection, aggregate, partition or asset_view A.

For example, the following instruction increments by 1 the nb_repairs field of all cars owned by caller:

car.select(the.owner = caller).update_all({ nb_repairs += 1 })

This is equivalent to:

const v = car.select(the.owner = caller);
for k in v do
  car.update(k, { nb_repairs += 1 })
done

Type of collection `A`

Parameter

u :

update literal

Curly bracketed list of fields' assignment instructions (separated by ;); these instructions are presented in the assignment section (:= += -= *= /= &= |=).

Fails with

does not fail

Asset

Assignment

update

`A.add_update(k, { u })`

Adds a new asset or updates asset with key k in collection A (does not fail):

it adds a new asset if asset k is not in A
it updates asset k is in A

For example, consider the ledger asset:

asset ledger identified by holder to big_map {
  holder     : address;
  tokens     : nat = 0;
}

Consider the following add_update instruction:

ledger.add_update(%to, { tokens += value });

if %to holder is not in the ledger collection, this adds asset { %to; value } to it
if %to is in ledger collection, this increments the tokens field by value

info

Note that it is possible to use the += assignment instruction on field tokens because tokens has a default value specified (0) in asset declaration.

Basic containers

Maps and sets fieds may be updated with := += and -= update instructions.

For example, consider the following asset declaration:

asset my_asset {
  id : nat;
  m  : map<string, bytes>;
}

The following creates asset 0 and associates 3 values to "k" "l" and "m" keys in map field m:

my_asset.add_update(0, { m += [("k", 0x00); ("l", 0x01); ("m", 0x02)] });

The += instruction overwrites any previous association.

The following removes key "k" in m of asset 0:

my_asset.add_update(0, { m -= ["k"] });

Partition

As for the add instruction, the add_update instruction is available for partition field.

For example, the following instruction adds or updates the expiration date of mile "#1" of flyer caller:

flyer[caller].miles.add_update("#1", { expiration := (now + 40d) })

See the paritition section above for more information.

Aggregate

An aggregate field does not provide the add_update instruction.

Type of collection `A`

Parameters

k :

Key of the asset to update fields of.

u :

update literal

Curly bracketed list of fields' assignment instructions (separated by ;); these instructions are presented in the assignment section (:= += -= *= /= &= |=).

Note that these update instructions are only available for fields with a specified default value.

Fails with

does not fail

Asset

Assignment

add

update

`A.remove(k)`

Removes asset with key k from collection A.

For example, consider the following declaration:

asset ledger {
  owner  : address;
  amount : nat;
}

The following instruction removes entry for address tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb:

ledger.remove(tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb);

Note that it does not fail when the asset is not in the collection.

Partition

A partitioned asset may be removed only through the partition field of the partitioning asset, that is that it is not possible to straighforwardly add an asset in a partitioned asset.

For example, consider the following declarations where a mile belongs to one and only one flyer through the miles partition field:

asset mile identified by k {
  k          : string;
  expiration : date
}

asset flyer identified by a {
  a     : address;
  miles : partition<mile>
}

The following instruction removes the mile asset with key "#1" owned by flyer a:

flyer[a].miles.remove("#1")

Note that the effect of above instruction is to:

remove the asset in the partitioned asset (so that mile.contains("#1") returns false)
remove the reference "#1" to the partition field assets (so that flyer[a].miles.contains("#1") returns false )

The following instruction is rejected by the compiler:

mile.remove("#1")

with the following error:

Cannot access asset collection: asset partitioned is partitionned by field(s) (miles).

Aggregate

The remove instruction on an aggregate field removes the reference to the asset.

For example, consider the following declarations where a vehicle may be referenced by several driver assets through the drives aggregate field:

asset vehicle identified by vin {
  vin     : string;
  nbdoors : nat
}

asset driver identified by id {
  id     : address;
  drives : aggregate<vehicle>
}

The following instruction removes the reference to vehicle "1G1AF1F57A7192174":

driver[caller].drives.remove("1G1AF1F57A7192174");

info

The instruction above does not fail if vehicle "1G1AF1F57A7192174" is not referenced by drives.

Asset view

As a read-only set of asset references, an asset_view does not provide the remove instruction.

Type of collection `A`

Parameter

k :

Key of the asset to remove.

Fails with

does not fail

Asset

add

`A.put_remove(k, o)`

Puts or removes an asset in collection A depending on value of option value o:

when o is some(v), then asset make_asset(k, v) is put in collection
when o is none, then asset with key k is removed from collection

Type of collection `A`

Parameters

k :

Key of the asset to add or remove.

o :

option<asset_value<A>>

Option of asset value to add or remove.

Fails with

does not fail

Asset

put

remove

make_asset

`A.remove_if(p)`

Removes assets referenced by an aggregate or partition field A and that verify predicate p.

For example, consider the following declarations:

asset vehicle identified by vin {
  vin      : string;
  nb_doors : nat
}

asset driver identified by id {
  id     : address;
  drives : aggregate<vehicle>
}

For example the following instruction removes all vehicles driven by driver caller with nb_doors equal to 0:

driver[caller].drives.remove_if(the.nb_doors = 0)

The the keyword refers to the asset being evaluated; all asset fields are available in predicates.

caution

When used on a partition field, references in the parititon field are also removed for consistency reason, as the partition ensures that any reference points to an existing asset.

Type of collection `A`

Parameter

p :

predicate

Predicate.

Fails with

does not fail

Asset

remove

remove_all

`A.remove_all()`

Removes elements from container A, A being an asset collection, an aggregate or a partition field.

For example, to remove all loan assets:

loan.remove_all();

info

As iteration is not available on big maps, remove_all is not available for asset to big_map type.

Partition

The remove_all instruction on a partition field removes all references in the partition field and also removes assets from the partiotioned asset collection.

For example, the following instruction removes all miles owned by caller flyer:

flyer[caller].miles.remove_all();

The effect of above instruction is to:

remove all miles from mile collection owner by caller
remove all reference to these miles so that flyer[caller].miles.count() = 0 stands true afterwards

info

Note that the above instruction is equivalent to remove_if(true) instruction because a partition synchronizes the existence of the reference towards the asset.

Aggregate

The remove_all instruction on an aggregate field removes all references in the aggregate fields.

For example, the following instruction removes all references from driver caller to vehicle assets:

driver[caller].drives.remove_all()

The only effect of above instruction is to empty the list of vehicles driven by driver caller so that driver[caller].drives.count() = 0 stands true afterwards. The collection of vehicles is left unchanged.

Type of collection `A`

Fails with

does not fail

Asset

remove

remove_if

select

`A.clear()`

Removes all assets referenced by asset_view A.

For example, the following instruction removes all cars assets owned by caller :

car.select(the.owner = caller).clear()

This is equivalent to:

const v = car.select(the.owner = caller);
for k in v do
  car.remove(k)
done

Type of collection `A`