Basic ursus functions

Operations with mapping

Consider terms with name and type such as:

m: URValue (mapping keyType valueType)
k: URValue (keyType)

Mapping functions:

fetch returns value of key k in mapping m.

\\ m->fetch(k) \\ : URValue (optional valueType)

Piece of example:

::// var val: optional uint := uint_to_uint_dict->fetch({3}) ;_|.

exists returns whether key k exists in the mapping.

\\ m->exists(k) \\: URValue boolean

Piece of example:

::// var val: boolean := uint_to_uint_dict->exists({3}) ;_|.

set sets the value associated with key and returns update mapping

\\ m->set(k, v) \\: URValue (mapping keyType valueType)

Piece of example:

::// var new_map: mapping uint uint := old_map->set({3}, {3}) ;_|.

delete deletes the value associated with key and returns update mapping

\\ m->delete(k) \\: URValue (mapping keyType valueType)

Piece of example:

::// var new_map: mapping uint uint := old_map->delete({3}) ;_|.

min returns mininum in the list of keys (< must be defined for keyType)

\\ m->min() \\: URValue (optional keyType)

Piece of example:

::// var minimum: optional uint := uint_to_uint_dict->min() ;_|.

max returns maximum in the list of keys (< must be defined for keyType)

\\ m->max() \\: URValue (optional keyType)

Piece of example:

::// var maximum: optional uint := uint_to_uint_dict->max() ;_|.

next returns next or greater of key k in keys order and associated value in pair

\\ m->next(k) \\: URValue (optional (keyType ** valueType))

Piece of example:

::// var next_one: optional (keyType ** valueType) := uint_to_uint_dict->next({3}) ;_|.

prev returns previous or lesser of key k in keys order and associated value in pair

\\ m->prev(k) \\ : URValue (optional (keyType ** valueType))

Piece of example:

::// var prev_one: optional (keyType ** valueType) := uint_to_uint_dict->prev({3}) ;_|.

nextOrEq computes the maximal key in the mapping that is lexicographically less than or equal to key and returns an optional value containing that key and the associated value. Returns an empty optional if there is no such key.

\\ m->nextOrEq(k) \\ : URValue (optional (keyType ** valueType))

Piece of example:

::// var prev_one: optional (keyType ** valueType) := uint_to_uint_dict->nextOrEq({3}) ;_|.

prevOrEq computes the minimal key in the mapping that is lexicographically greater than or equal to key and returns an optional value containing that key and the associated value. Returns an empty optional if there is no such key.

\\ m->prevOrEq(k) \\ : URValue (optional (keyType ** valueType))

Piece of example:

::// var prev_one: optional (keyType ** valueType) := uint_to_uint_dict->prevOrEq({3}) ;_|.

replace sets the value v associated with key k only if key exists in the mapping and returns the success flag.

m: ULValue (mapping keyType valueType)
\\ m->replace(k, v) \\: URValue boolean

Piece of example:

::// var flag: boolean := uint_to_uint_dict->replace({3}, {3}) ;_|.

getReplace sets the value associated with key, but only if key exists in the mapping. On success, returns an optional with the old value associated with the key. Otherwise, returns an empty optional.

m: ULValue (mapping keyType valueType)
\\ m->getReplace(k, v) \\: URValue (optional valueType)

Piece of example:

::// var old_value: optional valueType := uint_to_uint_dict->getReplace({3}, {3}) ;_|.

erase removes assotiated value for key k

m: ULValue (mapping keyType valueType)
// m->erase(k) //: UExpression ?R ?b

Piece of example:

::// uint_to_uint_dict->erase({3}) .

If mapping is not empty, then this delMin computes the minimal key of the mapping, deletes that key and the associated value from the mapping and returns an optional value containing that key and the associated value. Returns an empty optional if there is no such key.

m: ULValue (mapping keyType valueType)
// m->delMin() //: UExpression ?R ?b

m: ULValue (mapping keyType valueType)
\\ m->delMin() \\: URValue (optional (keyType ** valueType))

Piece of example:

::// uint_to_uint_dict->delMin() .
::// var old_value: optional valueType := uint_to_uint_dict->delMin() ;_|.

If mapping is not empty, then this delMax computes the maximal key of the mapping, deletes that key and the associated value from the mapping and returns an optional value containing that key and the associated value. Returns an empty optional if there is no such key.

m: ULValue (mapping keyType valueType)
// m->delMax() //: UExpression ?R ?b

m: ULValue (mapping keyType valueType)
\\ m->delMax() \\: URValue (optional (keyType ** valueType))

Piece of example:

::// uint_to_uint_dict->delMax() .
::// var old_value: optional valueType := uint_to_uint_dict->delMax() ;_|.

getSet sets the value associated with key, but also returns an optional with the previous value associated with the key, if any. Otherwise, returns an empty optional.

m: ULValue (mapping keyType valueType)
// m->getSet(k, v) //: UExpression ?R ?b

m: ULValue (mapping keyType valueType)
\\ m->getSet(k, v) \\: URValue (optional valueType)

Piece of example:

::// uint_to_uint_dict->getSet(k, v) .
::// var old_value: optional valueType := uint_to_uint_dict->getSet({3}, {3}) ;_|.

add sets the value associated with key and returns whether key k was in the mapping before.

m: ULValue (mapping keyType valueType)
// m->add(k, v) //: UExpression ?R ?b

m: ULValue (mapping keyType valueType)
\\ m->add(k, v) \\: URValue boolean

Piece of example:

::// uint_to_uint_dict->add(k, v) .
::// var flag: boolean := uint_to_uint_dict->add({3}, {3}) ;_|.

getAdd sets the value associated with key and returns previous associated value (if it doesn't exist then returns None).

m: ULValue (mapping keyType valueType)
// m->getAdd(k, v) //: UExpression ?R ?b

m: ULValue (mapping keyType valueType)
\\ m->getAdd(k, v) \\: URValue (optional valueType)

Piece of example:

::// uint_to_uint_dict->getAdd(k, v) .
::// var flag: optional valueType  := uint_to_uint_dict->getAdd({3}, {3}) ;_|.

set_at sets the associated value v with key k.

m: ULValue (mapping keyType valueType)
// m->set_at(k, v) //: UExpression ?R ?b

Piece of example:

::// uint_to_uint_dict->set_at(k, v) .

extract sets the value associated with key and returns previous associated value (if it doesn't exist then returns None).

m: ULValue (mapping keyType valueType)
\\ m->extract(k) \\: URValue (optional valueType)

Piece of example:

::// var old_value: optional valueType  := uint_to_uint_dict->extract({3}) ;_|.

insert sets the value associated with key.

m: ULValue (mapping keyType valueType)
// m->insert((k, v)) //: UExpression ?R ?b

Piece of example:

::// uint_to_uint_dict->insert(({3}, {3})) .

at returns the value associated with key (if it doesn't exist then throw error).

m: ULValue (mapping keyType valueType)
\\ m->at(k) \\: URValue valueType true

Piece of example:

::// var old_value: valueType  := uint_to_uint_dict->at({3}) ;_|.

at is a true-function

String operations

Consider terms with name and type such as:

\\ x \\: URValue string _
\\ y \\: URValue string _

is_prefix returns whether x prefix of y.

\\ x is_prefix y \\: URValue boolean _

Piece of example:

::// var flag: boolean := ({"abs"} is_prefix {"absc"}) ;_|.

substr returns substring of string x from n-th to m-th position (m > n)

n: URValue uint _
m: URValue uint _
\\ x->substr(n, m) \\: URValue string _

Piece of example:

::// var sub: boolean := {"abs"}->substr({2},{4}) ;_|.

find does something

x: URValue string _
y: URValue uint _
\\ x->find(y) \\: URValue (optional uint) _

Piece of example:

::// var num: optional uint := {"abs"}->find({"abs"}) ;_|.

appendString, appendBytes returns concatenation of strings x and y.

\\ x->appendString(y) \\: URValue string _

Piece of example:

::// var xy: string := {"x"}->appendString({"y"}) ;_|.

Optional operations

Consider terms with name and type such as:

\\ v \\: URValue valueType _
\\ x \\: URValue (optional valueType) _

hasValue returns whether x has value

\\ x->hasValue() \\ : URValue boolean _

Piece of example:

::// var flag: boolean := x->hasValue()  ;_|.

set, some wrapped value in optional v

\\ v->set() \\: URValue (optional valueType) _
\\ some(v) \\: URValue (optional valueType) _

Piece of example:

::// var flag1: optional boolean := some(@false)  ;_|.
::// var flag2: optional boolean := (@false)->set()  ;_|.

`reset` put none in optional `v` \ x->reset() \: URValue (optional valueType) _

get returns value from optional, or if it doesn't exist then throw error.

\\ x->get() \\: URValue valueType true

Piece of example:

::// var value: valueType := x->get() ;_|.

`get` is a true-function `get_default` is 'false' version of `get` function

x->reset() put Null/None/xMaybeNone into x
x->set(a) put value a into x

Function length

x->length returns term of type uint, which simply means lenght of term x

Function empty

x->empty() returns term of type boolean, which means is x empty

Operations with queue

x->queue_pop()
x->begin()
x->end()
x->queue_push()
x->front_with_idx_opt() " x '->' 'front_with_idx' '()'" := (queue_begin_right x) " x '->' 'back_with_idx' '()' " := (queue_end_right x)

Operations with bytes

bytes_app x y
x->bytes_get(n)

Operations with vector

function x->push(y) which adds to the end of vector x element y
function x->pop() which removes last element of vector x and returns it

Unpack

x->unpack()

Casting functions

Here is list of available casting operations for nums:

int(num)
uint8!(num)
uint8(num)
uint16!(num)
uint16'(num)
uint32!(num)
uint32(num)
uint64!(num)
uint64(num)
varUint16!(num)
uint128!(num)
uint128(num)
uint256!(num)
uint256(num)

where

uintN(num) cast any num with type uintM (M ≤ N) to uintN
uintN!(num) cast any num to uintN (even if M ≥ N). These functions are true TODO LINK

Ursus language documentation

reset put none in optional v \ x->reset() \: URValue (optional valueType) _

get is a true-function get_default is 'false' version of get function

`reset` put none in optional `v` \ x->reset() \: URValue (optional valueType) _

`get` is a true-function `get_default` is 'false' version of `get` function