feat(docs): Builder.storeMaybeRef, parseStdAddress and `parseVarA…

…ddress` (#950)

CHANGELOG.md

@@ -71,7 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `asm` bodies for module-level functions: PR [#769](https://github.com/tact-lang/tact/pull/769), PR [#825](https://github.com/tact-lang/tact/pull/825)
 - Corresponding stdlib functions for new TVM instructions from 2023.07 and 2024.04 upgrades: PR [#331](https://github.com/tact-lang/tact/pull/331). Added the `storeBuilder` extension function and `gasConsumed`, `getComputeFee`, `getStorageFee`, `getForwardFee`, `getSimpleComputeFee`, `getSimpleForwardFee`, `getOriginalFwdFee`, `myStorageDue` functions.
 - `slice`, `rawSlice`, `ascii` and `crc32` built-in functions: PR [#787](https://github.com/tact-lang/tact/pull/787), PR [#799](https://github.com/tact-lang/tact/pull/799)
-- `Builder.storeMaybeRef`, `parseStdAddress` and `parseVarAddress` stdlib functions: PR [#793](https://github.com/tact-lang/tact/pull/793)
+- `Builder.storeMaybeRef`, `parseStdAddress` and `parseVarAddress` stdlib functions: PR [#793](https://github.com/tact-lang/tact/pull/793), PR [#950](https://github.com/tact-lang/tact/pull/950)
 - The compiler development guide: PR [#833](https://github.com/tact-lang/tact/pull/833)
 - Constant evaluator now uses an interpreter: PR [#664](https://github.com/tact-lang/tact/pull/664). This allows calls to user-defined functions and references to declared global constants.
 

docs/src/content/docs/ref/core-advanced.mdx

@@ -3,6 +3,8 @@ title: Advanced
 description: "Advanced, niche or dangerous functions from the Core library of Tact"
 ---
 
+import { Badge } from '@astrojs/starlight/components';
+
 Various niche, dangerous or unstable features which can produce unexpected results and are meant to be used by the more experienced users.
 
 :::caution
@@ -251,6 +253,84 @@ nativeReserve(ton("0.1"), ReserveExact | ReserveBounceIfActionFail);
 //            amount of nanoToncoins to reserve
 ```
 
+## parseStdAddress
+
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
+```tact
+fun parseStdAddress(slice: Slice): StdAddress;
+```
+
+Converts a [`Slice{:tact}`][slice] containing an address into the `StdAddress{:tact}` [Struct][s] and returns it. The `StdAddress{:tact}` is a built-in [Struct][s] that consists of:
+
+Field       | Type                           | Description
+:---------- | :----------------------------- | :----------
+`workchain` | [`Int as int8{:tact}`][int]    | Workchain ID of the address, usually $0$ (basechain) or $-1$ (masterchain)
+`address`   | [`Int as uint256{:tact}`][int] | Address in the specified `workchain`
+
+Attempts to pass a [`Slice{:tact}`][slice] with layout different from the `StdAddress{:tact}` or to load more data than a given [`Slice{:tact}`][slice] contains throw an exception with [exit code 9](/book/exit-codes#9): `Cell underflow`.
+
+Usage example:
+
+```tact
+let addr = address("EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2");
+let parsedAddr = parseStdAddress(addr.asSlice());
+
+parsedAddr.workchain; // 0
+parsedAddr.address;   // 107...lots of digits...287
+
+// Using newAddress() function with the contents of StdAddress will yield the initial Address:
+let addr2: Address = newAddress(parsedAddr.workchain, parsedAddr.address);
+addr2 == addr; // true
+```
+
+:::note
+
+  For parsing addresses of variable length, see the [`parseVarAddress(){:tact}`](#parsevaraddress) function.
+
+:::
+
+## parseVarAddress
+
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
+```tact
+fun parseVarAddress(slice: Slice): VarAddress;
+```
+
+Converts a [`Slice{:tact}`][slice] containing an address of variable length into the `VarAddress{:tact}` [Struct][s] and returns it. The `VarAddress{:tact}` is a built-in [Struct][s] consisting of:
+
+Field       | Type                         | Description
+:---------- | :--------------------------- | :----------
+`workchain` | [`Int as int32{:tact}`][int] | Workchain ID of the variable length address
+`address`   | [`Slice{:tact}`][slice]      | Address in the specified `workchain`
+
+Attempts to pass a [`Slice{:tact}`][slice] with layout different from the `VarAddress{:tact}` or to load more data than a given [`Slice{:tact}`][slice] contains throw an exception with [exit code 9](/book/exit-codes#9): `Cell underflow`.
+
+Usage example:
+
+```tact
+let varAddrSlice = beginCell()
+    .storeUint(6, 3)     // to recognize the following as a VarAddress
+    .storeUint(123, 9)   // make address occupy 123 bits
+    .storeUint(234, 32)  // specify workchain ID of 234
+    .storeUint(345, 123) // specify address of 345
+    .asSlice();
+let parsedVarAddr = parseVarAddress(varAddrSlice);
+
+parsedVarAddr.workchain;             // 234
+parsedVarAddr.address;               // CS{Cell{002...2b3} bits: 44..167; refs: 0..0}
+parsedVarAddr.address.loadUint(123); // 345
+```
+
+:::caution
+
+  Variable-length addresses are intended for future extensions, and while validators must be ready to accept them in inbound messages, the standard (non-variable) addresses are used whenever possible.
+
+:::
+
 [p]: /book/types#primitive-types
 [bool]: /book/types#booleans
 [int]: /book/integers
+[slice]: /book/cells#slices
+[s]: /book/structs-and-messages#structs

docs/src/content/docs/ref/core-cells.mdx

@@ -3,6 +3,8 @@ title: Cells, Builders and Slices
 description: "Various Cell, Builder and Slice functions from the Core library of Tact"
 ---
 
+import { Badge } from '@astrojs/starlight/components';
+
 [`Cell{:tact}`][cell] is a low-level [primitive][p] that represents data in TON Blockchain. Cells consist of $1023$ bits of data with up to $4$ references to another cells. They are read-only and immutable, and cannot have cyclic references.
 
 [`Builder{:tact}`][builder] is an immutable [primitive][p] to construct cells, and [`Slice{:tact}`][slice] is a mutable [primitive][p] to parse them.
@@ -191,6 +193,8 @@ let buzz: Builder = b.storeBool(false); // writes 0
 
 ## Builder.storeBit
 
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
 ```tact
 extends fun storeBit(self: Builder, value: Bool): Builder;
 ```
@@ -286,6 +290,31 @@ let b: Builder = beginCell();
 let fizz: Builder = b.storeRef(emptyCell());
 ```
 
+## Builder.storeMaybeRef
+
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
+```tact
+extends fun storeMaybeRef(self: Builder, cell: Cell?): Builder;
+```
+
+Extension function for the [`Builder{:tact}`][builder].
+
+If the `cell` is not `null{:tact}`, stores $1$ as a single bit and then reference `cell` into the copy of the [`Builder{:tact}`][builder]. Returns that copy.
+
+If the `cell` is `null{:tact}`, only stores $0$ as a single bit into the copy of the [`Builder{:tact}`][builder]. Returns that copy.
+
+As a single [`Cell{:tact}`][cell] can store up to $4$ references, attempts to store more throw an exception with [exit code 8](/book/exit-codes#8): `Cell overflow`.
+
+Usage example:
+
+```tact
+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
 
 ```tact
@@ -525,6 +554,8 @@ let fizz: Bool = s.loadBool(); // true
 
 ## Slice.loadBit
 
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
 ```tact
 extends mutates fun loadBit(self: Slice): Bool;
 ```
@@ -817,6 +848,8 @@ fun coinCell(): Cell {
 
 ## Struct.toSlice
 
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
 ```tact
 extends fun toSlice(self: Struct): Slice;
 ```
@@ -939,6 +972,8 @@ fun coinCell(): Cell {
 
 ## Message.toSlice
 
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
 ```tact
 extends fun toSlice(self: Message): Slice;
 ```