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