细胞、建造者和切片

Cell是 TON 区块链中表示数据的低级基元。 单元由 $1023$ 位数据组成，最多可 $4$ 引用另一个单元。 它们是只读的、不可变的，并且不能循环引用。

Builder是一个不可变的基元，用于构建单元格；Slice是一个可变的基元，用于解析单元格。

注意

在手动构建和解析单元格时要非常小心，并始终确保记录其所需的布局：用于序列化和反序列化的值和类型的严格顺序。

为此，建议高级用户使用类型语言 - 二进制（TL-B）模式。

建议每位用户使用 Structs 及其 方法，如 Struct.toCell() 和 Struct.fromCell()，而不是手动构建和解析单元格，因为 Structs 和 Messages 最接近于您的合约的活 TL-B 架构。

beginCell

fun beginCell()：生成器

创建一个新的空Builder。

使用示例

让 fizz：Builder = beginCell()；

空单元格

fun emptyCell()：单元格；

创建并返回空 [单元格][单元格]（不含数据和引用）。 别名为 beginCell().endCell()。

使用示例

让 fizz：Cell = emptyCell();
let buzz：Cell = beginCell().endCell();

fizz == buzz; // true

空切片

fun emptySlice()：Slice；

创建并返回空 [片][片]（不含数据和引用）。 与 emptyCell().asSlice() 同名。

使用示例

让 fizz：Slice = emptySlice();
let buzz：Slice = emptyCell().asSlice();

fizz == buzz; // true

Cell.beginParse

extends fun beginParse(self: Cell)：Slice；

[单元格][单元格]的扩展函数。

打开[单元格][单元格]进行解析，并以[切片][切片]的形式返回。

使用示例

让 c：Cell = emptyCell();
let fizz：Slice = c.beginParse()；

单元格哈希值

extends fun hash(self: Cell)：Int；

[单元格][单元格]的扩展函数。

计算并返回给定[单元格][单元格]的[标准单元格表示][st-repr]的SHA-256哈希值的Int值。

使用示例

让 c：Cell = emptyCell();
let fizz：Int = c.hash()；

Cell.asSlice

extends fun asSlice(self: Cell)：Slice；

[单元格][单元格]的扩展函数。

将单元格转换为Slice并返回。 self.beginParse()的别名。

使用示例

让 c：Cell = emptyCell();
let fizz：Slice = c.asSlice()；

Builder.endCell

extends fun endCell(self: Builder)：Cell；

[生成器][生成器]的扩展函数。

将 [构造器][构造器] 转换为普通的 [单元格][单元格]。

使用示例

let b: Builder = beginCell();
let fizz：单元格 = b.endCell()；

Builder.storeUint

extends fun storeUint(self: Builder, value: Int, bits: Int)：Builder；

[生成器][生成器]的扩展函数。

将 $0 \leq \text{bits} \leq 256$ 的无符号 bits 位 value 存储到 Builder 的副本中。返回该副本。

试图存储负 value 或提供不足或超界 bits 数时，会出现 退出代码 5 异常：“整数超出预期范围”。

使用示例

let b: Builder = beginCell();
let fizz：Builder = b.storeUint(42, 6)；

Builder.storeInt

extends fun storeInt(self: Builder, value: Int, bits: Int)：Builder；

[生成器][生成器]的扩展函数。

将$0 ≤$ bits $≤ 257$的有符号bits-位值存储到builder的副本中。 返回该副本。

试图提供一个不足或超出范围的比特数时，会出现退出代码5的异常：整数超出预期范围”。

使用示例

let b: Builder = beginCell();
let fizz：Builder = b.storeUint(42, 7)；

Builder.storeBool

extends fun storeBool(self: Builder, value: Bool)：Builder；

[生成器][生成器]的扩展函数。

将Boolvalue存储到Builder的副本中。 如果 value 是 true，则写入 $1$ 作为单个位，否则写入 $0$。 返回 [生成器][生成器] 的副本。

使用示例

let b: Builder = beginCell();
let fizz：Builder = b.storeBool(true); // writes 1
let buzz：Builder = b.storeBool(false); // writes 0

Builder.storeSlice

extends fun storeSlice(self: Builder, cell: Slice)：Builder；

[生成器][生成器]的扩展函数。

将slicecell存储到builder的副本中。 返回该副本。

使用示例

let b: Builder = beginCell();
let s：Slice = emptyCell().asSlice();
let fizz：Builder = b.storeSlice(s)；

Builder.storeCoins

extends fun storeCoins(self: Builder, value: Int)：Builder；

[生成器][生成器]的扩展函数。

存储（序列化）一个范围为 $0 \ldots 2^{120} - 1$ 的无符号 Int value 到 Builder 的副本中。value 的序列化由 $4$ 位无符号大端整数 $l$ 组成，它是最小的整数 $l \geq 0$，使得 $\text{value} < 2^{8l}$，然后是 value 的 $8l$ 位无符号大端表示。返回 Builder 的副本。

试图存储一个超出范围的值时，会出现退出代码5的异常：超出预期范围的整数。

这是最常见的[纳米通币]存储方式（/book/integers#nanotoncoin）。

使用示例

let b: Builder = beginCell();
let fizz：Builder = b.storeCoins(42)；

Useful links:

特殊的 “硬币 “序列化类型

Builder.storeAddress

extends fun storeAddress(self: Builder, address: Address)：Builder；

[生成器][生成器]的扩展函数。

将地址存储在 [生成器][生成器] 的副本中。 返回该副本。

使用示例

let b: Builder = beginCell();
let fizz：Builder = b.storeAddress(myAddress())；

Builder.storeRef

extends fun storeRef(self: Builder, cell: Cell)：Builder；

[生成器][生成器]的扩展函数。

将引用 cell 存储到Builder的副本中。 返回该副本。

由于单个 [单元格][单元格] 最多可存储 $4$ 引用，如果尝试存储更多引用，则会出现退出代码 8异常：单元格溢出”。

使用示例

let b: Builder = beginCell();
let fizz：Builder = b.storeRef(emptyCell())；

建造者参考资料

extends fun refs(self: Builder)：Int；

[生成器][生成器]的扩展函数。

以 Int形式返回已存储在 [构造器][构造器] 中的单元格引用的数目。

使用示例

let b: Builder = beginCell();
let fizz：Int = b.refs(); // 0

构建器位

extends fun bits(self: Builder)：Int；

[生成器][生成器]的扩展函数。

以Int形式返回已存储在builder中的数据位数。

使用示例

let b: Builder = beginCell();
let fizz：Int = b.bits(); // 0

Builder.asSlice

extends fun asSlice(self: Builder)：Slice；

[生成器][生成器]的扩展函数。

将builder转换为slice并返回。 别名为 self.endCell().beginParse()。

使用示例

let b: Builder = beginCell();
let fizz：Slice = b.asSlice()；

Builder.asCell

extends fun asCell(self: Builder)：Cell；

[生成器][生成器]的扩展函数。

将Builder转换为Cell并返回。 别名为 self.endCell()。

使用示例

let b: Builder = beginCell();
let fizz：Cell = b.asCell()；

Slice.loadUint

extends mutates fun loadUint(self: Slice, l: Int)：Int；

[切片][切片]的扩展突变函数。

从 Slice中加载并返回一个无符号的 l 位 Int，条件是 $0 ≤$ l $≤ 256$。

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：超出预期范围的整数。

尝试加载的数据超过 [片][片] 包含的数据时，会出现 exit code 9 异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeUint(42, 7).asSlice();
let fizz：Int = s.loadUint(7)；

Slice.preloadUint

extends fun preloadUint(self: Slice, l: Int)：Int；

[切片][切片]的扩展函数。

为 $0 ≤$ l $≤ 256$ 从 Slice中预载并返回一个无符号的 l 位 Int。 不会修改 [切片][切片]。

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：超出预期范围的整数。

尝试预载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeUint(42, 7).asSlice();
let fizz：Int = s.preloadUint(7)；

Slice.loadInt

extends mutates fun loadInt(self: Slice, l: Int)：Int；

[切片][切片]的扩展突变函数。

从 Slice中加载并返回一个有符号的 l 位 Int，值为 $0 ≤$ l $≤ 257$。

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：超出预期范围的整数。

尝试加载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9 异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeInt(42, 7).asSlice();
let fizz：Int = s.loadInt(7)；

Slice.preloadInt

extends fun preloadInt(self: Slice, l: Int)：Int；

[切片][切片]的扩展函数。

为 $0 ≤$ l $≤ 257$ 从 Slice中预载并返回一个有符号的 l 位 Int。 不会修改 [切片][切片]。

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：超出预期范围的整数。

尝试预载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeInt(42, 7).asSlice();
let fizz：Int = s.preloadInt(7)；

Slice.loadBits

extends mutates fun loadBits(self: Slice, l: Int)：Slice；

[切片][切片]的扩展突变函数。

从 [片][片] 中加载 $0 ≤$ l $≤ 1023$ 位，并作为单独的 [片][片] 返回。

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：超出预期范围的整数。

尝试加载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9 异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeInt(42, 7).asSlice();
let fizz：Slice = s.loadBits(7)；

Slice.preloadBits

extends fun preloadBits(self: Slice, l: Int)：Slice；

[切片][切片]的扩展函数。

从 [片][片] 中预载 $0 ≤$ l $≤ 1023$ 位，并将其作为单独的 [片][片] 返回。 不修改原始 [切片][切片]。

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：超出预期范围的整数。

尝试预载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeInt(42, 7).asSlice();
let fizz：Slice = s.preloadBits(7)；

Slice.skipBits

extends mutates fun skipBits(self: Slice, l: Int)；

[片][片]的扩展突变函数。

从 [片][片] 中加载除第一个 0 ≤$`l`$≤ 1023$ 位以外的所有位。

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：超出预期范围的整数。

尝试加载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9 异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeInt(42, 7).asSlice();
s.skipBits(5); // 除了前 5 位之外的所有位
let fizz：Slice = s.loadBits(1); // 只加载 1 位

Slice.loadBool

extends mutates fun loadBool(self: Slice)：Bool；

[片][片]的扩展突变函数。

从Slice加载单个位并返回Bool值。 如果加载的位等于 $1$，则读取 true，否则读取 false。

当 Boolslice不包含它时，尝试加载此类 Bool 会产生异常，退出代码 8：单元格溢出”。

尝试加载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9 异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeBool(true).asSlice();
let fizz：Bool = s.loadBool(); // true

Slice.loadCoins

extends mutates fun loadCoins(self: Slice)：Int；

[切片][切片]的扩展突变函数。

加载并返回序列化的一个范围为 $0 ... 2^{120} - 1$ 的无符号 Int值，来自 [片][片]。该值通常代表以纳吨币为单位的金额。

当 Slice中不包含Int时，尝试加载此类Int会产生异常，退出代码为 8：“单元格溢出”。

尝试加载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9 异常：“单元格下溢”。

使用示例

让 s：Slice = beginCell().storeCoins(42).asSlice();
let fizz：Int = s.loadCoins()；

Useful links:

特殊的 “硬币 “序列化类型

Slice.loadAddress

extends mutates fun loadAddress(self: Slice)：地址；

Slice的扩展突变函数。

从Slice加载并返回一个[Address][address]。

当Slice不包含该地址时，尝试加载该[Address][address]会产生异常，退出代码 8：“单元格溢出”。

尝试加载的数据超过 Slice 所包含的数据时，会出现 退出代码 9 异常：“单元格下溢”。

使用示例

让 s：Slice = beginCell().storeAddress(myAddress()).asSlice();
let fizz：地址 = s.loadAddress()；

Slice.loadRef

extends mutates fun loadRef(self: Slice)：Cell；

[切片][切片]的扩展突变函数。

从 [切片][切片] 中加载下一个引用作为 [单元格][单元格]。

当 [切片][切片]不包含该引用时，尝试加载该引用会产生异常，退出代码 8：“单元格溢出”。

尝试加载的数据超过 [片][片] 所包含的数据时，会出现 exit code 9 异常：单元格下溢”。

使用示例

让 s：Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz：Cell = s.loadRef();

let s：Slice = beginCell()
    .storeRef(emptyCell())
    .storeRef(emptyCell())
    .asSlice();
let ref1: Cell = s.loadRef();
let ref2: Cell = s.loadRef()；

Slice.refs

extends fun refs(self: Slice)：Int；

[切片][切片]的扩展函数。

以 Int形式返回 [片][片] 中引用的个数。

使用示例

让 s：Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz：Int = s.refs().asSlice(); let fizz: Int = s.refs().asSlice()

Slice.bits

extends fun bits(self: Slice)：Int；

[切片][切片]的扩展函数。

以 Int形式返回 [片][片] 中的数据位数。

使用示例

让 s：Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz：Int = s.bits()；

Slice.empty

extends fun empty(self: Slice)：Bool；

[切片][切片]的扩展函数。

检查 [片][片] 是否为空（即不包含数据位和单元格引用）。 如果为空，则返回 true，否则返回 false。

使用示例

让 s：Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz：Bool = s.empty(); // false
let buzz：Bool = beginCell().asSlice().empty(); // true

注意

与 Slice.endParse()不同，即使 Slice为空，该函数也不会抛出任何异常。

Slice.dataEmpty

extends fun dataEmpty(slice: Slice)：Bool；

[切片][切片]的扩展函数。

检查 [片][片] 是否没有数据位。 如果没有数据，则返回 true，否则返回 false。

使用示例

让 s：Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz：Bool = s.dataEmpty(); // true

let s2：Slice = beginCell().storeInt(42, 7).asSlice();
let buzz：Bool = s2.dataEmpty(); // false

Slice.refsEmpty

extends fun refsEmpty(slice: Slice)：Bool；

[切片][切片]的扩展函数。

检查 Slice是否没有引用。 如果没有引用，则返回 true，否则返回 false。

使用示例

让 s：Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz：Bool = s.refsEmpty(); // false
let buzz：Bool = beginCell().asSlice().refsEmpty(); // true

Slice.endParse

extends fun endParse(self: Slice)；

[切片][切片]的扩展函数。

检查 [片][片] 是否为空（即不包含数据位和单元格引用）。 如果不是，则抛出异常退出代码 9：单元格下溢。

使用示例

let emptyOne: Slice = emptySlice();
emptyOne.endParse(); // nothing, as it's empty

let paul: Slice = "Fear is the mind-killer".asSlice();
try {
    paul.endParse(); // throws exit code 9
}

Slice.hash

extends fun hash(self: Slice)：Int；

[切片][切片]的扩展函数。

计算并返回给定Slice的[标准Cell表示][st-repr]的SHA-256哈希值的Int值。

使用示例

让 s：Slice = beginCell().asSlice();
let fizz：Int = s.hash()；

Slice.asCell

extends fun asCell(self: Slice)：Cell；

[切片][切片]的扩展函数。

将 Slice转换为 Cell并返回。 别名为 beginCell().storeSlice(self).endCell()。

使用示例

让 s：Slice = beginCell().asSlice();
let fizz：Cell = s.asCell();
let buzz：Cell = beginCell().storeSlice(s).endCell();

fizz == buzz; // true

地址.asSlice

extends fun asSlice(self: Address)：Slice；

地址的扩展函数。

将地址转换为[片][片]并返回。 别名为 beginCell().storeAddress(self).asSlice()。

使用示例

让 a：Address = myAddress();
let fizz：Slice = a.asSlice();
let buzz：Slice = beginCell().storeAddress(a).asSlice();

fizz == buzz; // true

Struct.toCell

extends fun toCell(self: Struct)：Cell；

任何结构类型 Struct的扩展函数。

将 Struct 转换为 [单元格][单元格]并返回。

使用示例

struct GuessCoin {
    probably：
    nothing: Int as coins;
}

fun coinCell()：Cell {
    let s：GuessCoin = GuessCoin{ probably: 42, nothing: 27 };
    let fizz：Cell = s.toCell();

    return fizz; // "x{12A11B}"
}

Struct.fromCell

extends fun fromCell(self: Struct, cell: Cell)：Struct；

任何结构类型 Struct的扩展函数。

将 [单元格][单元格] 转换为指定的 结构体，并返回该 结构体。

试图传递布局与指定 Struct 不同的 [单元格][单元格]，或加载的数据超过 [单元格][单元格] 所包含的数据时，会出现 exit code 9异常：单元格下溢”。

使用示例

struct GuessCoin {
    probably：
    nothing: Int as coins;
}

fun directParse(payload: Cell)：GuessCoin {
    return GuessCoin.fromCell(payload);
}

fun cautiousParse(payload: Cell)：GuessCoin?{
    let coin: GuessCoin?= null;
    try {
        coin = GuessCoin.fromCell(payload);
    } catch (e) {
        dump("Cell payload doesn't match GuessCoin Struct!");
    }
    return coin;
}

Struct.fromSlice

extends fun fromSlice(self: Struct, cell: Slice)：Struct；

任何结构类型 Struct的扩展函数。

将 片转换为指定的 Struct，并返回该 Struct。

尝试传递布局与指定 结构不同的 [片][片]，或加载比 [片][片] 包含的数据更多的数据时，会出现退出代码 9异常：单元下溢”。

使用示例

struct GuessCoin {
    probably：
    nothing: Int as coins;
}

fun directParse(payload: Slice)：GuessCoin {
    return GuessCoin.fromSlice(payload);
}

fun cautiousParse(payload: Slice)：GuessCoin?{
    let coin: GuessCoin?= null;
    try {
        coin = GuessCoin.fromSlice(payload);
    } catch (e) {
        dump("Slice payload doesn't match GuessCoin Struct!");
    }
    return coin;
}

Message.toCell

extends fun toCell(self: Message)：Cell；

任何报文类型 [报文][信息] 的扩展函数。

将信息转换为[单元格][单元格]并返回。

使用示例

message GuessCoin {
    probably：
    nothing: Int as coins;
}

fun coinCell()：Cell {
    let s：GuessCoin = GuessCoin{ probably: 42, nothing: 27 };
    let fizz：Cell = s.toCell();

    return fizz; // "x{AB37107712A11B}"
}

Message.fromCell

extends fun fromCell(self: Message, cell: Cell)：消息；

任何报文类型 [报文][信息] 的扩展函数。

将 [单元格][单元格] 转换为指定的 [信息][消息]，并返回该 [信息][消息]。

尝试传递布局与指定信息不同的[单元格][单元格]，或加载的数据超过[单元格][单元格]所包含的数据时，会出现退出代码 9的异常：单元格下溢”。

使用示例

message(0x777) TripleAxe {
    prize：Int as uint32;
}

fun directParse(payload: Cell)：TripleAxe {
    return TripleAxe.fromCell(payload);
}

fun cautiousParse(payload: Cell)：TripleAxe?{
    let coin: TripleAxe? = null;
    try {
        coin = TripleAxe.fromCell(payload);
    } catch (e) {
        dump("Cell payload doesn't match TripleAxe Message!");
    }
    return coin;
}

Message.fromSlice

extends fun fromSlice(self: Message, cell: Slice)：消息；

任何报文类型 [报文][信息] 的扩展函数。

将 [片][片] 转换为指定的 [信息][消息]，并返回该 [信息][消息]。

试图传递布局不同于指定[信息][消息]的[片][片]，或加载的数据多于[片][片]所包含的数据时，会出现退出代码 9的异常：单元下溢”。

使用示例

message(0x777) TripleAxe {
    prize：Int as uint32;
}

fun directParse(payload: Slice)：TripleAxe {
    return TripleAxe.fromSlice(payload);
}

fun cautiousParse(payload: Slice)：TripleAxe?{
    let coin: TripleAxe? = null;
    try {
        coin = TripleAxe.fromSlice(payload);
    } catch (e) {
        dump("Slice payload doesn't match TripleAxe Message!");
    }
    return coin;
}