Skip to main content

Asset

A.add(a)

Adds a new asset a in collection A. It fails when the key of asset a is already contained in collection A.

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 a new loan to the collection of loans:

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

When all fields are specified, it is possible to omit fields label:

loan.add({ "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.add({
id = "1a3245";
subscriber = tz1Lc2qBKEWCBeDU8npG6zCeCqpmaegRi6Jg;
}) /* interest and time are defaulted to 2% and 10 weeks respectively */

Partition

A partitioned asset may be added 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 proper way to add the mile asset { "#1", now } is with the following instruction on the partition field of flyer a:

flyer[a].miles.add({ "#1"; (now + 30d) })

Note that the effect of above instruction is to:

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

The following instruction is rejected by the compiler:

mile.add({ "#1"; (now + 30d) })

with the following error:

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

Aggregate

The add instruction on an aggregate field only takes the key to the referenced 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 adds the reference to vehicle "1G1AF1F57A7192174" to driver caller:

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

The instruction above fails if vehicle "1G1AF1F57A7192174" does not exist.

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).


Related

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 */

Parameter


a :

asset literal

Asset literal to be added.

Fails with

does not fail


Related

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 by {
{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.

Parameters


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).


Related

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

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


Related

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.

Parameters


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


Related

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.

Parameter


Key of the asset to remove.

Fails with

does not fail


Related

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.

Parameter


p :

predicate

Predicate.

Fails with

does not fail


Related

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.

Fails with

does not fail


Related

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

Fails with

does not fail


Related