标准库（Standard Library）

The Move standard library exposes interfaces that implement the following functionality:

Basic operations on vectors.
Option types and operations onOption types.
A common error encoding code interface for abort codes.
32-bit precision fixed-point numbers.

Move标准库公开了实现以下功能的接口:

向量的基本操作.
Option类型与基本操作.
终止码的常见错误编码接口.
32位精确定点数字.

向量（vector）

The vector module defines a number of operations over the primitive vector type. The module is published under the named address Std and consists of a number of native functions, as well as functions defined in Move. The API for this module is as follows.

向量模块在原生类型向量上定义了许多操作。该模块以命名地址Std发布，并由许多原生函数以及在Move中定义的函数组成。此模块的API如下所示:

函数（Functions）

Create an empty vector. The Element type can be both a resource or copyable type.

创建一个空的向量。 Element类型可以是资源或可复制类型。

    native public fun empty<Element>(): vector<Element>;

Create a vector of length 1 containing the passed in element.

创建一个长度为1的vector，并且包含传入的element。

    public fun singleton<Element>(e: Element): vector<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.

销毁(释放)向量v。如果v非空操作将终止。注意:空的限制是由于Element可以是资源类型，而销毁非空的向量会违反资源保护机制。

    native public fun destroy_empty<Element>(v: vector<Element>);

Acquire an immutable reference to the ith element of the vector v. Will abort if the index i is out of bounds for the vector v.

获取向量v的第i个元素的不可变引用。如果索引i超出了向量v的范围，操作将会终止。

    native public fun borrow<Element>(v: &vector<Element>, i: u64): &Element;

Acquire a mutable reference to the ith element of the vector v. Will abort if the index i is out of bounds for the vector v.

获取向量v的第i个元素的可变引用。如果索引i超出了向量v的范围，操作将会终止。

    native public fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element;

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.

清空并销毁other动态数组，并将other向量中的每个元素按顺序添加到lhs动态数组。

    public fun append<Element>(lhs: &mut vector<Element>, other: vector<Element>);

Push an element e of type Element onto the end of the vector v. May trigger a resizing of the underlying vector's memory.

将类型为Element的元素e添加到向量v的末尾。可能触发底层向量内存的大小调整。

    native public fun push_back<Element>(v: &mut vector<Element>, e: Element);

Pop an element from the end of the vector v in-place and return the owned value. Will abort if v is empty.

从向量v的末尾取出一个元素并返回。如果v为空将终止操作。

    native public fun pop_back<Element>(v: &mut vector<Element>): Element;

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.

移除向量v中索引i处的元素，并返回之前存储在v中的i处的值。所有下标大于i的元素将向前移动1个位置。如果i超出了v的范围，操作将会终止。

    public fun remove<Element>(v: &mut vector<Element>, i: u64): Element;

Swap the ith 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.

将向量v的第i个元素与最后一个元素交换，然后将这个元素从向量的后面取出，并返回之前存储在索引i处的所有元素的值。这个操作时间复杂度是O(1)，但是不保持向量容器中元素的顺序。如果索引i超出了向量v的边界，则操作终止。

    public fun swap_remove<Element>(v: &mut vector<Element>, i: u64): Element;

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.

交换向量v中下标为第i和第j的元素。如果i或j中的任何一个超出了v的范围，则操作将终止。

    native public fun swap<Element>(v: &mut vector<Element>, i: u64, j: u64);

Reverse the order of the elements in the vector v in-place.

将向量v中的元素顺序颠倒。

    public fun reverse<Element>(v: &mut vector<Element>);

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.

返回v中第一个与e相等的元素的索引。如果找到这样的元素，则返回(true, index)，否则返回(false, 0)。

    public fun index_of<Element>(v: &vector<Element>, e: &Element): (bool, u64);

Return if an element equal to e exists in the vector v.

如果向量v中存在等于e的元素，则返回true, 否则返回false。

    public fun contains<Element>(v: &vector<Element>, e: &Element): bool;

Return the length of a vector.

返回向量的长度。

    native public fun length<Element>(v: &vector<Element>): u64;

Return whether the vector v is empty.

如果向量v中没有元素，则返回true, 否则返回false。

    public fun is_empty<Element>(v: &vector<Element>): bool;

选项（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 named address Std.

option模块定义了一个泛型option类型Option<T>，它表示类型为T的值可能存在，也可能不存在。它发布在命名地址Std下。

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.

Move option类型在内部表示为一个单例向量，可能包含资源或可复制类型的值。如果你熟悉其他语言中的option类型，Move Option的行为与那些类似，但有几个显著的例外，因为option可以包含一个类型为资源的值。特别地，某些操作如get_with_default和destroy_with_default要求元素类型T为可复制类型。

The API for the option module is as as follows

option模块的API如下所示:

类型（Types）

Generic type abstraction of a value that may, or may not, be present. Can contain a value of either resource or copyable kind.

一个值的泛型类型的抽象，可能存在，也可能不存在。它可以包含资源或可复制类型的值。

    struct Option<T>;

函数（Functions）

Create an empty Option of that can contain a value of Element type.

创建一个可以包含Element类型值的空Option。

    public fun none<Element>(): Option<Element>;

Create a non-empty Option type containing a value e of type Element.

创建一个非空的Option类型，包含类型为Element的值e。

    public fun some<Element>(e: T): Option<Element>;

Return an immutable reference to the value inside the option opt_elem Will abort if opt_elem does not contain a value.

返回opt_elem内部值的不可变引用,如果opt_elem不包含值，则将终止操作。

    public fun borrow<Element>(opt_elem: &Option<Element>): &Element;

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.

如果opt_elem中包含值，则返回该值的引用。如果opt_elem不包含值，将返回传入的default_ref引用。不会终止操作。

    public fun borrow_with_default<Element>(opt_elem: &Option<Element>, default_ref: &Element): &Element;

Return a mutable reference to the value inside opt_elem. Will abort if opt_elem does not contain a value.

返回opt_elem内部值的可变引用。如果opt_elem不包含值，则操作将终止。

    public fun borrow_mut<Element>(opt_elem: &mut Option<Element>): &mut Element;

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.

通过删除并返回存储在opt_elem中的值，将包含值的opt_elem转换为空option类型。如果opt_elem不包含值，则将终止。

    public fun extract<Element>(opt_elem: &mut Option<Element>): Element;

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.

如果opt_elem中包含值，则返回该值。如果opt_elem不包含值，将返回传入的default值。default类型必须是可复制类型，这样该函数才能被调用。

    public fun get_with_default<Element: copyable>(opt_elem: &Option<Element>, default: Element): Element;

Convert an empty option opt_elem to an option value that contains the value e. Will abort if opt_elem already contains a value.

将空option类型opt_elem转换为包含值e的option类。如果opt_elem已经包含值，则操作将终止。

    public fun fill<Element>(opt_elem: &mut Option<Element>, e: Element);

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.

将opt_elem当前包含的值与new_elem交换，并返回先前包含的值。如果opt_elem不包含值，则操作将终止。

    public fun swap<Element>(opt_elem: &mut Option<Element>, e: Element): Element;

Return true if opt_elem contains a value equal to the value of e_ref. Otherwise, false will be returned.

如果opt_elem包含一个等于e_ref的值，则返回true。否则，将返回false。

    public fun contains<Element>(opt_elem: &Option<Element>, e_ref: &Element): bool;

Return true if opt_elem does not contain a value.

如果opt_elem不包含值，则返回true。

    public fun is_none<Element>(opt_elem: &Option<Element>): bool;

Return true if opt_elem contains a value.

如果opt_elem包含值，则返回true。

    public fun is_some<Element>(opt_elem: &Option<Element>): bool;

Unpack opt_elem and return the value that it contained. Will abort if opt_elem does not contain a value.

解包opt_elem并返回它所包含的值。如果opt_elem不包含值，则操作将终止。

    public fun destroy_some<Element>(opt_elem: Option<Element>): Element;

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.

销毁传入的opt_elem。如果opt_elem包含值，它将被返回，否则将返回传入的default值。

    public fun destroy_with_default<Element: copyable>(opt_elem: Option<Element>, default: Element): Element;

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.

销毁传入的opt_elem，opt_elem必须为空且不包含值。如果opt_elem包含一个值，则会终止操作。

    public fun destroy_none<Element>(opt_elem: Option<Element>);

错误（errors）

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

回想一下，Move中的每个终止代码都表示为无符号64位整数。errors模块定义了一个通用接口，可用于"标记"每个终止代码，以便它们既可以表示错误类别，也可以表示错误原因。

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.

错误类别在errors模块中声明为常量，并且对该模块来说是全局唯一的。另一方面，错误原因是特定于模块的错误代码，可以提供关于特定错误条件的更详细的信息(甚至可能是一个特定的_reason_)。每个错误代码的类别和原因的这种表示是通过将终止代码分成两部分来完成的。

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.

Category	Reason
8 bits	56 bits

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

终止代码的较低8位保存错误类别。终止代码的其余56位包含错误原因。原因应该是相对于引发错误的模块的唯一数字，并且可以用来获取关于当前错误的更多信息。它应该主要用于诊断目的，因为如果模块更新，错误原因可能会随着时间的推移而变化。

类型	原因
8 bits	56 bits

由于错误类别是全局稳定的，所以它们提供了稳定的API，通常应该由客户端用来确定它们可能向用户提供的消息(而原因则用于诊断目的)。在errors模块中有一些公共函数，用于创建每个错误类别的带有特定原因号的终止代码(表示为u64)。

常量（Constants）

The system is in a state where the performed operation is not allowed.

系统处于不允许操作的状态。

    const INVALID_STATE: u8 = 1;

A specific account address was required to perform an operation, but a different address from what was expected was encounterd.

执行操作需要一个特定的帐户地址，但遇到的地址与预期的不同。

    const REQUIRES_ADDRESS: u8 = 2;

An account did not have the expected role for this operation. Useful for Role Based Access Control (RBAC) error conditions.

帐户没有此操作的预期角色。用于基于角色访问控制(RBAC)错误。

    const REQUIRES_ROLE: u8 = 3;

An account did not not have a required capability. Useful for RBAC error conditions.

帐户没有所需的能力。用于RBAC错误。

    const REQUIRES_CAPABILITY: u8 = 4;

A resource was expected, but did not exist under an address.

地址下不存在期望的资源。

    const NOT_PUBLISHED: u8 = 5;

Attempted to publish a resource under an address where one was already published.

试图在已发布资源的地址发布资源。

    const ALREADY_PUBLISHED: u8 = 6;

An argument provided for an operation was invalid.

为操作提供的参数无效。

    const INVALID_ARGUMENT: u8 = 7;

A limit on a value was exceeded.

超过了一个值的限制。

    const LIMIT_EXCEEDED: u8 = 8;

An internal error (bug) has occurred.

发生了内部错误(bug)。

    const INTERNAL: u8 = 10;

A custom error category for extension points.

扩展自定义错误类别。

    const CUSTOM: u8 = 255;

函数（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.

在遇到无效(全局)状态的情况下应使用。构造一个具有指定的reason和类别INVALID_STATE的终止代码。如果reason不适合56位，将会终止操作。

    public fun invalid_state(reason: u64): u64;

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.

当账户地址与特定地址不匹配时应使用。构造一个具有指定的reason和类别REQUIRES_ADDRESS的终止代码。如果reason不适合56位，将会终止操作。

    public fun requires_address(reason: u64): u64;

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.

在使用RBAC时，角色与所需角色不匹配时应使用。构造一个具有指定的reason和类别REQUIRES_ROLE的终止代码。如果reason不适合56位，将会终止操作。

    public fun requires_role(reason: u64): u64;

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.

在使用RBAC时，帐户没有必要的能力时应使用。构造一个具有指定的reason和类别REQUIRES_CAPABILITY的终止代码。如果reason不适合56位，将会终止操作。

    public fun requires_capability(reason: u64): u64;

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.

在需要资源的地方不存在资源时应使用。构造一个具有指定的reason和类别NOT_PUBLISHED的终止代码。如果reason不适合56位，将会终止操作。

    public fun not_published(reason: u64): u64;

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.

要发布资源的地方已经存在资源时使用。构造一个具有指定的reason和类别ALREADY_PUBLISHED的终止代码。如果reason不适合56位，将会终止操作。

    public fun already_published(reason: u64): u64;

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.

当向函数/操作传递无效参数时使用。构造一个具有指定的reason和类别INVALID_ARGUMENT的终止代码。如果reason不适合56位，将会终止操作。

    public fun invalid_argument(reason: u64): u64;

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.

当达到特定值的限制时应使用，例如，0减去1。构造一个具有指定的reason和类别LIMIT_EXCEEDED的终止代码。如果reason不适合56位，将会终止操作。

    public fun limit_exceeded(reason: u64): u64;

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.

在遇到内部错误或错误时使用。构造一个具有指定的reason和类别INTERNAL的终止代码。如果reason不适合56位，将会终止操作。

    public fun internal(reason: u64): u64;

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.

用于扩展，大多数情况下不应使用。构造一个具有指定的reason和类别CUSTOM的终止代码。如果reason不适合56位，将会终止操作。

    public fun custom(reason: u64): u64;

32位精确定点数字（fixed_point32）

The fixed_point32 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 fixed_point32 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.

fixed_point32模块定义了一个具有32个整数位和32个小数位的定点数值类型。在内部，它被表示为一个u64整数，包装在一个结构中，形成一个唯一的fixed_point32类型。由于数字表示是二进制的，一些十进制值可能不能完全表示，但它在小数点之前和之后都提供了9位以上的十进制精度(总共18位)。为了进行比较，双精度浮点数的精度小于16位十进制数字，因此在使用浮点数将这些值转换为十进制时应该小心。

类型（Types）

Represents a fixed-point numeric number with 32 fractional bits.

表示具有32个小数位的定点数字。

    struct FixedPoint32;

函数（Functions）

Multiply a u64 integer by a fixed-point number, truncating any fractional part of the product. This will abort if the product overflows.

当u64整数乘以定点数，截断乘积的任何小数部分。如果乘积溢出，该操作将终止。

    public fun multiply_u64(val: u64, multiplier: FixedPoint32): u64;

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.

当u64整数除以定点数，截断商的任何小数部分。如果除数为零或商溢出，该操作将终止。

    public fun divide_u64(val: u64, divisor: FixedPoint32): u64;

Create a fixed-point value from a rational number specified by its numerator and denominator. Calling this function should be preferred for using fixed_point32::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.

根据分子和分母指定的有理数创建定点值。如果fixed_point32::create_from_raw_value函数可用，应优先使用。如果分母为零，该操作将终止。如果分子非零且比值不在$2^{-32}\ldots2^{32}-1$范围内，该操作将终止。指定小数时，请注意四舍五入错误：如果要对小数点后$N$位进行四舍五入，则可以用$10^N$做分母，这样就能避免精确度丢失问题，例如，0.0125将四舍五入到0.012而不是0.013。

    public fun create_from_rational(numerator: u64, denominator: u64): FixedPoint32;

Create a fixedpoint value from a raw u64 value.

通过u64原始值创建一个定点值。

    public fun create_from_raw_value(value: u64): FixedPoint32;

Returns true if the decimal value of num is equal to zero.

如果num的十进制值等于0，则返回true。

    public fun is_zero(num: FixedPoint32): bool;

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.

获取u64原始值的方法。其他不太常见的操作，例如添加或减去FixedPoint32值，可以直接使用原始值来完成。

    public fun get_raw_value(num: FixedPoint32): u64;

Move Book 中文版