Cells, Builders 和 Slices

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

Builder 是一个不可变的原始类型，用于构建单元格，而 Slice 是一个可变的原始类型，用于解析单元格。

beginCell

fun beginCell(): Builder;

创建一个新的空Builder。

示例用法：

let fizz: Builder = beginCell();

emptyCell

fun emptyCell(): Cell;

创建并返回空 cell(不含数据和引用）。别名为 beginCell().endCell()。

示例用法：

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

fizz == buzz; // true

emptySlice

fun emptySlice(): Slice;

创建并返回一个空的 Slice (没有数据和引用)。与 emptyCell().asSlice() 同名。

示例用法：

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

fizz == buzz; // true

Cell.beginParse

extends fun beginParse(self: Cell): Slice;

Cell 的扩展函数。

打开 Cell 进行解析，并以 Cell 的形式返回。

示例用法：

let c: Cell = emptyCell();
let fizz: Slice = c.beginParse();

Cell.hash

extends fun hash(self: Cell): Int;

Cell 的扩展函数。

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

示例用法：

let c: Cell = emptyCell();
let fizz: Int = c.hash();

Cell.asSlice

extends fun asSlice(self: Cell): Slice;

Cell 的扩展函数。

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

示例用法：

let c: Cell = emptyCell();
let fizz: Slice = c.asSlice();

Builder.endCell

extends fun endCell(self: Builder): Cell;

Builder 的扩展函数。

将 Builder 转换为普通的 cell。

示例用法：

let b: Builder = beginCell();
let fizz: Cell = b.endCell();

Builder.storeUint

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

Builder 的扩展函数。

将一个无符号的 bits 位 value 存储到 Builder 的副本中，范围为 $0 ≤$ bits $≤ 256$ 。返回该副本。

尝试存储一个负数 value 或提供一个不足或超出范围的 bits 数量会抛出异常，错误代码为退出代码 5: Integer out of expected range。

示例用法：

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

Builder.storeInt

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

Builder 的扩展函数。

将一个有符号的 bits 位的 value 存储到 Builder 的副本中，范围是 $0 ≤$ bits $≤ 257$ 。返回该副本。

试图提供一个不足或超出范围的比特数时，会出现退出码5的异常：Integer out of expected range。

示例用法：

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

Builder.storeBool

extends fun storeBool(self: Builder, value: Bool): Builder;

Builder 的扩展函数。

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

示例用法：

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

Builder.storeBit

Available since Tact 1.5

extends fun storeBit(self: Builder, value: Bool): Builder;

Builder 的扩展函数。 Builder.storeBool() 的别名。

用法示例：

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

Builder.storeBuilder

extends fun storeBuilder(self: Builder, cell: Builder): Builder;

Builder 的扩展函数。

将 Builder cell 中的所有数据添加到Builder 的副本中。返回该副本。

示例用法：

let b: Builder = beginCell().storeCoins(42);
let fizz: Builder = beginCell().storeBuilder(b);
b.endCell() == fizz.endCell(); // true

Builder.storeSlice

extends fun storeSlice(self: Builder, cell: Slice): Builder;

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;

Builder 的扩展函数。

将一个无符号的 Int value 存储（序列化）到范围 $0 .. 2^{120} - 1$ 到 Builder 的副本中。 value 的序列化由一个 4 位无符号大端整数 l 组成，l 是满足 value $< 2^{8 _ l}$ 的最小整数 $l ≥ 0$ ，然后是一个 8 _ l 位无符号大端表示的 value。返回 Builder 的副本。

试图存储一个超出范围的值时，会出现退出码5的异常：Integer out of expected range。

这是保存 nanoToncoins 的最常见方式。

示例用法：

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

Builder.storeAddress

extends fun storeAddress(self: Builder, address: Address): Builder;

Builder 的扩展函数。

将地址存储在 Builder 的副本中。返回该副本。

示例用法：

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

Builder.storeRef

extends fun storeRef(self: Builder, cell: Cell): Builder;

Builder 的扩展函数。

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

由于单个 cell 最多可存储 $4$ 引用，如果尝试存储更多引用，则会出现退出码 8异常：Cell overflow。

示例用法：

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

Builder.storeMaybeRef

Available since Tact 1.5

extends fun storeMaybeRef(self: Builder, cell: Cell?): Builder;

Builder 的扩展函数。

如果cell不是null, 把 $1$ 作为一个位存储，然后在Builder 中使用 cell 。返回此复制。

如果 cell 是 null，则只将 $0$ 作为单个位存储到 Builder 的副本中。返回此复制。

由于单个 Cell 最多可以存储 $4$ 个引用，尝试存储更多引用将抛出异常，错误码为 exit code 8：Cell overflow。

用法示例：

let b: Builder = beginCell();
let fizz: Builder = b
    .storeMaybeRef(emptyCell()) // stores a single 1 bit, then an empty cell
    .storeMaybeRef(null);       // stores only a single 0 bit

Builder.refs

extends fun refs(self: Builder): Int;

Builder 的扩展函数。

以 Int 形式返回已存储在 Builder 中的cell引用的数目。

用法示例：

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

Builder.bits

extends fun bits(self: Builder): Int;

Builder 的扩展函数。

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

示例用法：

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

Builder.asSlice

extends fun asSlice(self: Builder): Slice;

Builder 的扩展函数。

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

示例用法：

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

Builder.asCell

extends fun asCell(self: Builder): Cell;

Builder 的扩展函数。

将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 的扩展突变函数。

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

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：Integer out of expected range。

尝试加载的数据超过 Slice 包含的数据时，会出现 exit code 9 异常：Cell underflow。

示例用法：

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

Slice.preloadUint

extends fun preloadUint(self: Slice, l: Int): Int;

Slice 的扩展函数。

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

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：Integer out of expected range。

尝试预载的数据超过 Slice 所包含的数据时，会出现 exit code 9异常：Cell underflow。

示例用法：

let 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 的扩展突变函数。

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

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：Integer out of expected range。

尝试加载的数据超过 Slice 所包含的数据时，会出现 exit code 9 异常：Cell underflow。

示例用法：

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

Slice.preloadInt

extends fun preloadInt(self: Slice, l: Int): Int;

Slice 的扩展函数。

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

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：Integer out of expected range。

尝试预载的数据超过 Slice 所包含的数据时，会出现 exit code 9异常：Cell underflow。

示例用法：

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

Slice.loadBits

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

Slice 的扩展突变函数。

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

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：Integer out of expected range。

尝试加载的数据超过 Slice 所包含的数据时，会出现 exit code 9 异常：Cell underflow。

示例用法：

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

Slice.preloadBits

extends fun preloadBits(self: Slice, l: Int): Slice;

Slice 的扩展函数。

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

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：Integer out of expected range。

尝试预载的数据超过 Slice 所包含的数据时，会出现 exit code 9异常：Cell underflow。

示例用法：

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

Slice.skipBits

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

Slice的扩展突变函数。

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

试图指定一个超出范围的 l 值时，会出现 exit code 5异常：Integer out of expected range。

尝试加载的数据超过 Slice 所包含的数据时，会出现 exit code 9 异常：Cell underflow。

示例用法：

let s: Slice = beginCell().storeInt(42, 7).asSlice();
s.skipBits(5);                   // all but first 5 bits
let fizz: Slice = s.loadBits(1); // load only 1 bit

Slice.loadBool

extends mutates fun loadBool(self: Slice): Bool;

Slice的扩展突变函数。

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

当 Boolslice不包含它时，尝试加载此类 Bool 会产生异常，退出码 8：Cell overflow。

尝试加载的数据超过 Slice 所包含的数据时，会出现 exit code 9 异常：Cell underflow。

示例用法：

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

Slice.loadBit

Available since Tact 1.5

extends mutates fun loadBit(self: Slice): Bool;

Slice 的扩展突变函数。别名为 Slice.loadBool()。

示例用法：

let s: Slice = beginCell().storeBit(true).asSlice();
let fizz: Bool = s.loadBit(); // true

Slice.loadCoins

extends mutates fun loadCoins(self: Slice): Int;

Slice 的扩展突变函数。

从Slice中加载并返回一个序列化的无符号Int值，范围为 $0 .. 2^{120} - 1$ 。此值通常代表 nanoToncoins 的金额。

当 Slice中不包含Int时，尝试加载此类Int 会产生异常，退出码为 8：Cell overflow。

尝试加载的数据超过 Slice 所包含的数据时，会出现 exit code 9 异常：Cell overflow。

用法示例：

let s: Slice = beginCell().storeCoins(42).asSlice();
let fizz: Int = s.loadCoins();

Slice.loadAddress

extends mutates fun loadAddress(self: Slice): Address;

Slice 的扩展突变函数。

从 Slice 加载并返回一个Address。

当Address[Slice不包含该地址时，尝试加载该地址 会产生异常，退出码 8：Cell overflow。

尝试加载的数据超过 Slice 所包含的数据时，会出现 exit code 9 异常：Cell underflow。

示例用法：

let s: Slice = beginCell().storeAddress(myAddress()).asSlice();
let fizz: Address = s.loadAddress();

Slice.loadRef

extends mutates fun loadRef(self: Slice): Cell;

Slice 的扩展突变函数。

从 Slice 中加载下一个引用作为 cell。

当 Cellslice不包含该引用时，尝试加载该引用会产生异常，退出码 8：Cell overflow。

尝试加载的数据超过 Slice 所包含的数据时，会出现 exit code 9 异常：Cell underflow。

示例用法：

let s1: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Cell = s1.loadRef();

let s2: Slice = beginCell()
    .storeRef(emptyCell())
    .storeRef(s1.asCell())
    .asSlice();
let ref1: Cell = s2.loadRef();
let ref2: Cell = s2.loadRef();
ref1 == ref2; // false

Slice.preloadRef

extends fun preloadRef(self: Slice): Cell;

Slice 的扩展函数。

预加载下一个引用从 Slice 为 cell 没有修改原来的 Slice

试图在 Slice 时预加载此引用 slice 不包含一个异常退出码 8：Cell overflow。

试图预加载更多数据超过 Slice 含有异常export code 9：Cell underflow。

示例用法：

let s1: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Cell = s1.preloadRef(); // didn't modify s1

let s2: Slice = beginCell()
    .storeRef(emptyCell())
    .storeRef(s1.asCell())
    .asSlice();
let ref1: Cell = s2.preloadRef();
let ref2: Cell = s2.preloadRef();
ref1 == ref2; // true

Slice.refs

extends fun refs(self: Slice): Int;

Slice 的扩展函数。

以 Int形式返回 Slice 中引用的个数。

示例用法：

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

Slice.bits

extends fun bits(self: Slice): Int;

slice的扩展函数。

以 Int形式返回 Slice 中的数据位数。

用法示例：

let s: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Int = s.bits();

Slice.empty

extends fun empty(self: Slice): Bool;

Slice 的扩展函数。

检查 Slice 是否为空（即不包含数据位和cell引用）。如果为空，则返回 true，否则返回 false。

用法示例：

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

Slice.dataEmpty

extends fun dataEmpty(slice: Slice): Bool;

Slice 的扩展函数。

检查slice 是否没有任何比特的数据。如果没有数据，则返回 true，否则返回 false。

使用示例

let 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的扩展函数。

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

用法示例：

let 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);

Slice 的扩展函数。

检查 Slice 是否为空（即不包含数据位和cell引用）。如果不是，则抛出异常退出码 9：Cell underflow。

使用示例：

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 的扩展函数。

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

用法示例：

let s: Slice = beginCell().asSlice();
let fizz: Int = s.hash();

Slice.asCell

extends fun asCell(self: Slice): Cell;

Slice 的扩展函数。

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

用法示例：

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

fizz == buzz; // true

Address.asSlice

extends fun asSlice(self: Address): Slice;

Address 的扩展函数。

将 Address 转换为Slice并返回。别名为 beginCell().storeAddress(self).asSlice()。

用法示例：

let 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 转换为 cell并返回。

用法示例：

struct GuessCoin {
    probably: Int as coins;
    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.toSlice

Available since Tact 1.5

extends fun toSlice(self: Struct): Slice;

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

将 Struct 转换为 Slice 并返回它。别名为self.toCell().asSlice()。

用法示例：

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

fun coinSlice(): Slice {
    let s: GuessCoin = GuessCoin{ probably: 42, nothing: 27 };
    let fizz: Slice = s.toSlice();

    return fizz; // "CS{Cell{000612a11b} bits: 0..24; refs: 0..0}"
}

Struct.fromCell

extends fun fromCell(self: Struct, cell: Cell): Struct;

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

将 cell 转换为指定的结构体，并返回该结构体。

试图传递布局与指定 Struct 不同的 cell，或加载的数据超过 cell 所包含的数据时，会出现 exit code 9异常：Cell underflow。

使用示例：

struct GuessCoin {
    probably: Int as coins;
    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 的扩展函数。

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

尝试传递布局与指定结构不同的 Slice，或加载比 Slice 包含的数据更多的数据时，会出现退出码 9异常：Cell underflow。

使用示例：

struct GuessCoin {
    probably: Int as coins;
    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 的扩展函数。

将 Message 转换为cell并返回。

用法示例：

message GuessCoin {
    probably: Int as coins;
    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.toSlice

Available since Tact 1.5

extends fun toSlice(self: Message): Slice;

任何 Message 类型的扩展函数。

将 Message 转换为 Slice 并返回它。别名为self.toCell().asSlice()。

用法示例：

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

fun coinSlice(): Slice {
    let s: GuessCoin = GuessCoin{ probably: 42, nothing: 27 };
    let fizz: Slice = s.toSlice();

    return fizz; // "CS{Cell{000eab37107712a11b} bits: 0..56; refs: 0..0}"
}

Message.fromCell

extends fun fromCell(self: Message, cell: Cell): Message;

任何消息类型 Message 的扩展函数。

将 cell 转换为指定的 Message，并返回该 Message。

尝试传递布局与指定 Message 不同的cell，或加载的数据超过cell所包含的数据时，会出现退出码 9的异常：Cell underflow。

使用示例：

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): Message;

任何 Message 类型的扩展函数。

将 Slice 转换为指定的 Message，并返回该 Message。

试图传递布局不同于指定 Message 的Slice，或加载的数据多于Slice所包含的数据时，会出现退出码 9的异常：Cell underflow。

使用示例

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;
}