3.2 库 (Libraries)

Libraries in Sway are files used to define new common behavior. The most prominent example of this is the Sway Standard Library that is made implicitly available to all Forc projects created using forc new.

编写库 (Writing Libraries)

Libraries are defined using the library keyword at the beginning of a file, followed by a name so that they can be imported.

库的定义是在文件的开头使用library关键字，后面跟一个名字，这们就可以被导入。

library;

// library code

A good reference library to use when learning library design is the Sway Standard Library. For example, the standard library offers an implementation of enum Option<T> which is a generic type that represents either the existence of a value using the variant Some(..) or a value's absence using the variant None. The Sway file implementing Option<T> has the following structure:

在学习库的设计时，有一个很好的参考：Sway标准库。例如，标准库提供了一个enum Option<T>的实现，它是一个通用类型，使用变量Some(..)表示一个值的存在，或者使用变量None表示一个值的不存在。实现Option<T> 的Sway文件有以下结构：

• The library keyword: library 关键字：

library;

• A use statement that imports revert from another library inside the standard library: 从标准库以外的另一个库中导入 revert的 use语句：

use ::revert::revert;

• The enum definition which starts with the keyword pub to indicate that this Option<T> is publically available outside the option library: 以关键字 pub开始的 enum定义，表明这个 Option<T>在 Option库之外是公开可用的：

pub enum Option<T> {
    // variants
}

• An impl block that implements some methods for Option<T>: 实现了 Option<T>的一些方法的一个 impl区块，：

impl<T> Option<T> {

    fn is_some(self) -> bool {
        // body of is_some
    }

    // other methods
}

Now that the library option is fully written, and because Option<T> is defined with the pub keyword, we are now able to import Option<T> using use std::option::Option; from any Sway project and have access to all of its variants and methods. That being said, Option is automatically available in the standard library prelude so you never actually have to import it manually.

现在库option已经完全编好了，而且因为Option<T>是用pub关键字定义的，我们现在可以使用use std::option::Option;从任何Sway项目中导入Option<T>，并可以访问它的所有变体和方法。也就是说，Option在标准库前置条件中是自动可用的，所以你实际上从来不需要手动导入它。

Libraries are composed of just a Forc.toml file and a src directory, unlike contracts which usually contain a tests directory and a Cargo.toml file as well. An example of a library's Forc.toml:

库只由一个Forc.toml文件和一个src目录组成，不像合约通常包含一个tests目录和一个Cargo.toml文件。以一个库的 Forc.toml 为例：

[project]
authors = ["Fuel Labs <[e-mail]>"]
entry = "lib.sw"
license = "Apache-2.0"
name = "my_library"

[dependencies]

which denotes the authors, an entry file, the name by which it can be imported, and any dependencies.

说明了作者，一个入口文件，可以被导入的名称，以及任何依赖。

For large libraries, it is recommended to have a lib.sw entry point re-export all other sub-libraries.

对于大型的库，建议有一个lib.sw入口点来重新输出所有其他子库。

The mod keyword registers a submodule, making its items (such as functions and structs) accessible from the parent library. If used at the top level it will refer to a file in the src folder and in other cases in a folder named after the library in which it is defined.

mod关键字注册了一个子模块，使其项目（如函数和结构）可以从父库中访问。如果在顶层使用，它将指向src文件夹中的一个文件，在其他情况下则指向以其定义的库来命名的文件夹。

For example, the lib.sw of the standard library looks like:

例如，标准库的lib.sw看起来像：

library;

mod block;
mod storage;
mod constants;
mod vm;
// .. Other deps

with other libraries contained in the src folder, like the vm library (inside of src/vm.sw):

与其他包含在 src文件夹中的库，如vm库（在 "src/vm.sw "内）：

library;

mod evm;
// ...

and it's own sub-library evm located in src/vm/evm.sw:

和它自己的子库evm，位于src/vm/evm.sw中：

library;

// ...

使用库 (Using Libraries)

There are two types of Sway libraries, based on their location and how they can be imported.

根据位置和其导入方式，共计有两种类型的Sway库，

内部库 (Internal Libraries)

Internal libraries are located within the project's src directory alongside main.sw or in the appropriate folders as shown below:

内部库位于项目的src目录下，与main.sw并列，或位于适当的文件夹中，如下所示：

$ tree
.
├── Cargo.toml
├── Forc.toml
└── src
    ├── internal_lib.sw
    ├── main.sw
    └── internal_lib
        └── nested_lib.sw

As internal_lib is an internal library, it can be imported into main.sw as follows:

由于internal_lib是一个内部库，它可以被导入到main.sw中，方法如下：

• Use the mod keyword followed by the library name to make the internal library a dependancy 使用mod关键字，后面跟上库的名字，使内部库成为依赖

• Use the use keyword with a :: separating the name of the library and the imported item(s) 使用use关键字，用::分隔库名和导入的项目。

mod internal_lib; // Assuming the library name in `internal_lib.sw` is `internal_lib`

use internal_lib::mint;

// `mint` from `internal_library` is now available in this file

外部库 (External Libraries)

External libraries are located outside the main src directory as shown below:

外部库位于主src目录之外，如下所示：

$ tree
.
├── my_project
│   ├── Cargo.toml
│   ├── Forc.toml
│   └─── src
│       └── main.sw
│
└── external_lib
    ├── Cargo.toml
    ├── Forc.toml
    └─── src
        └── lib.sw

As external_lib is outside the src directory of my_project, it needs to be added as a dependency in the Forc.toml file of my_project, by adding the library path in the dependencies section as shown below, before it can be imported:

由于 external_lib在 my_project的 src目录之外，它需要在 my_project的 Forc.toml文件中被添加为一个依赖，在 dependencies部分添加库的路径，才能被导入，如下图所示，：

[dependencies]
external_library = { path = "../external_library" }

Once the library dependency is added to the toml file, you can import items from it as follows:

一旦库的依赖被添加到toml文件中，你就可以按以下方式导入项目：

• Make sure the item you want imported are declared with the pub keyword (if applicable, for instance: pub fn mint() {}) 确保你想导入的项目是用pub关键字声明的（如果适用，例如：pub fn mint() {})

• Use the use keyword to selectively import items from the library 使用use关键字，有选择地从库中导入项目

use external_library::mint;

// `mint` from `external_library` is now available in this file

Wildcard imports using * are supported, but it is generally recommended to use explicit imports where possible.

支持使用*的通配符导入，但一般建议尽可能使用显式/明确导入。

Note: the standard library is implicitly available to all Forc projects, that is, you are not required to manually specify std as an explicit dependency in Forc.toml. 注意：标准库对所有Forc项目都是隐式的，也就是说，你不需要在Forc.toml中手动指定std作为显式依赖。

参考Sway库 (Reference Sway Libraries)

The repository sway-libs is a collection of external libraries that you can import and make use of in your Fuel applications. These libraries are meant to be learning references of common use-cases valuable for dapp development.

sway-libs库是一个外部库的集合，你可以在你的Fuel应用中导入和使用。这些库的目的是为了学习参考对DApp开发有价值的常见用例。

Some Sway Libraries to try out: 一些可以尝试的Sway库：

• Binary Merkle Proof

• Non-Fungible Token

• String

• Signed Integers

• Unsigned Fixed Point Number

• StorageMapVec

示例 (Example)

You can import and use a Sway Library such as the NFT library just like any other external library.

你可以像其他外部库一样导入和使用Sway库，如NFT库。

use sway_libs::nft::{
    mint,
    transfer,
    owner_of,
    approve,
};

Once imported, you can use the following basic functionality of the library in your smart contract: 一旦导入，你可以在你的智能合约中使用该库的以下基本功能：

• Minting tokens 铸造代币

• Transfering tokens 转移代币

• Retrieving owner of a token 检索代币的所有者

• Approving users to transfer a token 批准用户转让代币