Standard Library
The Move standard library exposes interfaces that implement the following functionality:
- Basic operations on vectors.
- Option types and operations on
Option
types. - A common error encoding code interface for abort codes.
- 32-bit precision fixed-point numbers.
Vector#
The Vector
module defines a number of operations over the primitive
vector
type. The module is published under the
core code address at 0x1
and consists of a number of native functions, as
well as functions defined in Move. The API for this module is as follows.
#
FunctionsCreate an empty vector
.
The Element
type can be both a resource
or copyable
type.
Create a vector of length 1
containing the passed in element
.
Destroy (deallocate) the vector v
. Will abort if v
is non-empty.
Note: The emptiness restriction is due to the fact that Element
can be a
resource type, and destruction of a non-empty vector would violate
resource conservation.
Acquire an immutable reference to the i
th element of the vector v
. Will abort if
the index i
is out of bounds for the vector v
.
Acquire a mutable reference
to the i
th element of the vector v
. Will abort if
the index i
is out of bounds for the vector v
.
Empty and destroy the other
vector, and push each of the elements in
the other
vector onto the lhs
vector in the same order as they occurred in other
.
Push an element e
of type Element
onto the end of the vector v
. May
trigger a resizing of the underlying vector's memory.
Pop an element from the end of the vector v
in-place and return the owned
value. Will abort if v
is empty.
Remove the element at index i
in the vector v
and return the owned value
that was previously stored at i
in v
. All elements occurring at indices
greater than i
will be shifted down by 1. Will abort if i
is out of bounds
for v
.
Swap the i
th element of the vector v
with the last element and then pop
this element off of the back of the vector and return the owned value that
was previously stored at index i
.
This operation is O(1), but does not preserve ordering of elements in the vector.
Aborts if the index i
is out of bounds for the vector v
.
Swap the elements at the i
'th and j
'th indices in the vector v
. Will
abort if either of i
or j
are out of bounds for v
.
Reverse the order of the elements in the vector v
in-place.
Return the index of the first occurrence of an element in v
that is
equal to e
. Returns (true, index)
if such an element was found, and
(false, 0)
otherwise.
Return if an element equal to e
exists in the vector v
.
Return the length of a vector
.
Return whether the vector v
is empty.
Option#
The Option
module defines a generic option type Option<T>
that represents a
value of type T
that may, or may not, be present. It is published under the core code address at 0x1
.
The Move option type is internally represented as a singleton vector, and may
contain a value of resource
or copyable
kind. If you are familiar with option
types in other languages, the Move Option
behaves similarly to those with a
couple notable exceptions since the option can contain a value of kind resource
.
Particularly, certain operations such as get_with_default
and
destroy_with_default
require that the element type T
be of copyable
kind.
The API for the Option
module is as as follows
#
TypesGeneric type abstraction of a value that may, or may not, be present. Can contain
a value of either resource
or copyable
kind.
#
FunctionsCreate an empty Option
of that can contain a value of Element
type.
Create a non-empty Option
type containing a value e
of type Element
.
Return an immutable reference to the value inside the option opt_elem
Will abort if opt_elem
does not contain a value.
Return a reference to the value inside opt_elem
if it contains one. If
opt_elem
does not contain a value the passed in default_ref
reference will be returned.
Does not abort.
Return a mutable reference to the value inside opt_elem
. Will abort if
opt_elem
does not contain a value.
Convert an option value that contains a value to one that is empty in-place by
removing and returning the value stored inside opt_elem
.
Will abort if opt_elem
does not contain a value.
Return the value contained inside the option opt_elem
if it contains one.
Will return the passed in default
value if opt_elem
does not contain a
value. The Element
type that the Option
type is instantiated with must be
of copyable
kind in order for this function to be callable.
Convert an empty option opt_elem
to an option value that contains the value e
.
Will abort if opt_elem
already contains a value.
Swap the value currently contained in opt_elem
with new_elem
and return the
previously contained value. Will abort if opt_elem
does not contain a value.
Return true if opt_elem
contains a value equal to the value of e_ref
.
Otherwise, false
will be returned.
Return true
if opt_elem
does not contain a value.
Return true
if opt_elem
contains a value.
Unpack opt_elem
and return the value that it contained.
Will abort if opt_elem
does not contain a value.
Destroys the opt_elem
value passed in. If opt_elem
contained a value it
will be returned otherwise, the passed in default
value will be returned.
Destroys the opt_elem
value passed in, opt_elem
must be empty and not
contain a value. Will abort if opt_elem
contains a value.
#
ErrorsRecall that each abort code in Move is represented as an unsigned 64-bit integer. The Errors
module defines a common interface that can be used to "tag" each of these abort codes so that they can represent both the error category along with an error reason.
Error categories are declared as constants in the Errors
module and are globally unique with respect to this module. Error reasons on the other hand are module-specific error codes, and can provide greater detail (perhaps, even a particular reason) about the specific error condition. This representation of a category and reason for each error code is done by dividing the abort code into two sections.
The lower 8 bits of the abort code hold the error category. The remaining 56 bits of the abort code hold the error reason. The reason should be a unique number relative to the module which raised the error and can be used to obtain more information about the error at hand. It should mostly be used for diagnostic purposes as error reasons may change over time if the module is updated.
Since error categories are globally stable, these present the most stable API and should in general be what is used by clients to determine the messages they may present to users (whereas the reason is useful for diagnostic purposes). There are public functions in the Errors
module for creating an abort code of each error category with a specific reason
number (represented as a u64
).
#
ConstantsThe system is in a state where the performed operation is not allowed.
A specific account address was required to perform an operation, but a different address from what was expected was encounterd.
An account did not have the expected role for this operation. Useful for Role Based Access Control (RBAC) error conditions.
An account did not not have a required capability. Useful for RBAC error conditions.
A resource was expected, but did not exist under an address.
Attempted to publish a resource under an address where one was already published.
An argument provided for an operation was invalid.
A limit on a value was exceeded.
An internal error (bug) has occurred.
A custom error category for extension points.
#
Functions Should be used in the case where invalid (global) state is encountered. Constructs an abort code with specified reason
and category INVALID_STATE
. Will abort if reason
does not fit in 56 bits.
Should be used if an account's address does not match a specific address. Constructs an abort code with specified reason
and category REQUIRES_ADDRESS
. Will abort if reason
does not fit in 56 bits.
Should be used if a role did not match a required role when using RBAC. Constructs an abort code with specified reason
and category REQUIRES_ROLE
. Will abort if reason
does not fit in 56 bits.
Should be used if an account did not have a required capability when using RBAC. Constructs an abort code with specified reason
and category REQUIRES_CAPABILITY
. Should be Will abort if reason
does not fit in 56 bits.
Should be used if a resource did not exist where one was expected. Constructs an abort code with specified reason
and category NOT_PUBLISHED
. Will abort if reason
does not fit in 56 bits.
Should be used if a resource already existed where one was about to be published. Constructs an abort code with specified reason
and category ALREADY_PUBLISHED
. Will abort if reason
does not fit in 56 bits.
Should be used if an invalid argument was passed to a function/operation. Constructs an abort code with specified reason
and category INVALID_ARGUMENT
. Will abort if reason
does not fit in 56 bits.
Should be used if a limit on a specific value is reached, e.g., subtracting 1 from a value of 0. Constructs an abort code with specified reason
and category LIMIT_EXCEEDED
. Will abort if reason
does not fit in 56 bits.
Should be used if an internal error or bug was encountered. Constructs an abort code with specified reason
and category INTERNAL
. Will abort if reason
does not fit in 56 bits.
Used for extension points, should be not used under most circumstances. Constructs an abort code with specified reason
and category CUSTOM
. Will abort if reason
does not fit in 56 bits.
FixedPoint32#
The FixedPoint32
module defines a fixed-point numeric type with 32 integer bits and 32 fractional bits. Internally, this is represented as a u64
integer wrapped in a struct to make a unique FixedPoint32
type. Since the numeric representation is a binary one, some decimal values may not be exactly representable, but it provides more than 9 decimal digits of precision both before and after the decimal point (18 digits total). For comparison, double precision floating-point has less than 16 decimal digits of precision, so you should be careful about using floating-point to convert these values to decimal.
#
TypesRepresents a fixed-point numeric number with 32 fractional bits.
#
FunctionsMultiply a u64 integer by a fixed-point number, truncating any fractional part of the product. This will abort if the product overflows.
Divide a u64 integer by a fixed-point number, truncating any fractional part of the quotient. This will abort if the divisor is zero or if the quotient overflows.
Create a fixed-point value from a rational number specified by its numerator and denominator. Calling this function should be preferred for using FixedPoint32::create_from_raw_value
which is also available. This will abort if the denominator is zero. It will also abort if the numerator is nonzero and the ratio is not in the range $2^{-32}\ldots2^{32}-1$. When specifying decimal fractions, be careful about rounding errors: if you round to display $N$ digits after the decimal point, you can use a denominator of $10^N$ to avoid numbers where the very small imprecision in the binary representation could change the rounding, e.g., 0.0125 will round down to 0.012 instead of up to 0.013.
Create a fixedpoint value from a raw u64
value.
Returns true
if the decimal value of num
is equal to zero.
Accessor for the raw u64
value. Other less common operations, such as adding or subtracting FixedPoint32
values, can be done using the raw values directly.