# 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](https://fuellabs.github.io/sway/v0.38.0/book/introduction/standard_library.html) 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](https://fuellabs.github.io/sway/v0.38.0/book/introduction/standard_library.html). For example, the standard library offers an [implementation](https://github.com/FuelLabs/sway/blob/master/sway-lib-std/src/option.sw) 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>`](https://github.com/FuelLabs/sway/blob/master/sway-lib-std/src/option.sw) has the following structure:

在学习库的设计时，有一个很好的参考：[Sway标准库](https://fuellabs.github.io/sway/v0.38.0/book/introduction/standard_library.html)。例如，标准库提供了一个`enum Option<T>`的[实现](https://github.com/FuelLabs/sway/blob/master/sway-lib-std/src/option.sw)，它是一个通用类型，使用变量`Some(..)`表示一个值的存在，或者使用变量`None`表示一个值的不存在。实现`Option<T>` [的Sway文件](https://github.com/FuelLabs/sway/blob/master/sway-lib-std/src/option.sw)有以下结构：

* 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](https://fuellabs.github.io/sway/v0.38.0/book/introduction/standard_library.html#standard-library-prelude) so you never actually have to import it manually.

现在库`option`已经完全编好了，而且因为`Option<T>`是用`pub`关键字定义的，我们现在可以使用`use std::option::Option;`从任何Sway项目中导入`Option<T>`，并可以访问它的所有变体和方法。也就是说，`Option`在[标准库前置条件](https://fuellabs.github.io/sway/v0.38.0/book/introduction/standard_library.html#standard-library-prelude)中是自动可用的，所以你实际上从来不需要手动导入它。

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 <contact@fuel.sh>"]
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`](https://github.com/FuelLabs/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`库](https://github.com/FuelLabs/sway-libs/)是一个外部库的集合，你可以在你的Fuel应用中导入和使用。这些库的目的是为了学习参考对DApp开发有价值的常见用例。

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

* [Binary Merkle Proof](https://github.com/FuelLabs/sway-libs/tree/master/libs/merkle_proof)
* [Non-Fungible Token](https://github.com/FuelLabs/sway-libs/tree/master/libs/nft)
* [String](https://github.com/FuelLabs/sway-libs/tree/master/libs/string)
* [Signed Integers](https://github.com/FuelLabs/sway-libs/tree/master/libs/signed_integers)
* [Unsigned Fixed Point Number](https://github.com/FuelLabs/sway-libs/tree/master/libs/fixed_point)
* [StorageMapVec](https://github.com/FuelLabs/sway-libs/tree/master/libs/storagemapvec)

#### 示例 (Example)

You can import and use a Sway Library such as the [NFT](https://github.com/FuelLabs/sway-libs/tree/master/sway_libs/src/nft) library just like any other external library.

你可以像其他外部库一样导入和使用Sway库，如[NFT](https://github.com/FuelLabs/sway-libs/tree/master/sway_libs/src/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\
  批准用户转让代币


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://zenofchain.gitbook.io/sway-bian-cheng-yu-yan-geng-xin-zhong-the-sway-programming-languageupdatin/3.sway-bian-cheng-lei-xing-sway-program-types/3.2-ku-libraries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.