feat(docs): variable integer serialization types

CHANGELOG.md

@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The `replace` and `replaceGet` methods for the `Map` type: PR [#941](https://github.com/tact-lang/tact/pull/941)
 - Utility for logging errors in code that was supposed to be unreachable: PR [#991](https://github.com/tact-lang/tact/pull/991)
 - Ability to specify a compile-time message opcode expression: PR [#1188](https://github.com/tact-lang/tact/pull/1188)
-- The `VarInt16`, `VarInt32`, `VarUint16`, `VarUint32` integer serialization types: PR [#1186](https://github.com/tact-lang/tact/pull/1186)
+- The `VarInt16`, `VarInt32`, `VarUint16`, `VarUint32` integer serialization types: PR [#1186](https://github.com/tact-lang/tact/pull/1186), PR [#1274](https://github.com/tact-lang/tact/pull/1274)
 - `unboc`: a standalone CLI utility to expose Tact's TVM disassembler: PR [#1259](https://github.com/tact-lang/tact/pull/1259)
 - Added alternative parser: PR [#1258](https://github.com/tact-lang/tact/pull/1258)
 

docs/cspell.json

@@ -166,6 +166,8 @@
     "uncons",
     "uninit",
     "unixfs",
+    "varint",
+    "varuint",
     "vogons",
     "workchain",
     "workchain",

docs/grammars/grammar-tact.json

@@ -402,7 +402,7 @@
         "comment": "Serialization",
         "patterns": [
           {
-            "match": "(?<!\\.)\\b(as)\\s+(coins|remaining|bytes32|bytes64|int257|u?int(?:2[0-5][0-6]|1[0-9][0-9]|[1-9][0-9]?))\\b",
+            "match": "(?<!\\.)\\b(as)\\s+(coins|varu?int(?:32|16)|remaining|bytes(?:64|32)|int257|u?int(?:2[0-5][0-6]|1[0-9][0-9]|[1-9][0-9]?))\\b",
             "captures": {
               "1": {
                 "name": "keyword.other.as.tact storage.modifier.tact"

docs/src/content/docs/book/integers.mdx

@@ -158,6 +158,47 @@ struct Scrooge {
 }
 ```
 
+### Variable integer types {#serialization-varint}
+
+<Badge text="Available since Tact 1.6 (not released yet)" variant="tip" size="medium"/><p/>
+
+Name               | [TL-B][tlb]                 | Inclusive range             | Space taken
+:----------------: | :-------------------------: | :-------------------------: | :-------------------------
+`varuint16{:tact}` | [`VarUInteger 16`][varuint] | $0$ to $2^{120} - 1$        | between $4$ and $124$ bits
+`varint16{:tact}`  | `VarInteger 16`             | $-2^{119}$ to $2^{119} - 1$ | between $4$ and $124$ bits
+`varuint32{:tact}` | [`VarUInteger 32`][varuint] | $0$ to $2^{248} - 1$        | between $5$ and $253$ bits
+`varint32{:tact}`  | `VarInteger 32`             | $-2^{247}$ to $2^{247} - 1$ | between $5$ and $253$ bits
+
+The `varuint16{:tact}` format is equivalent to [`coins{:tact}`](#serialization-coins). Its signed variant, `varint16{:tact}`, has the same memory layout except for the signed `value` field, which allows a different range of values: from $-2^{119}$ to $2^{119} - 1$, including both ends.
+
+To store greater values, use `varuint32{:tact}` and `varint32{:tact}` formats. These are serialized almost identical to `coins{:tact}` and lesser variable integer formats, but use a $5$-bit `len` field for storing the byte length. This allows the `value` to use up to $248$ bits for storing the actual number, meaning that both `varuint32{:tact}` and `varint32{:tact}` can occupy up to $253$ bits in total.
+
+Examples:
+
+```tact
+struct BradBit {
+    // len: 00000, 5 bits
+    // value: none!
+    // in total: 5 bits
+    a: Int as varuint32 = 0; // 00000
+
+    // len: 00001, 5 bits
+    // value: 00000001, 8 bits
+    // in total: 13 bits
+    b: Int as varuint32 = 1; // 00001 00000001
+
+    // len: 00010, 5 bits
+    // value: 00000001 00000010, 16 bits
+    // in total: 21 bits
+    c: Int as varuint32 = 258; // 00010 00000001 00000010
+
+    // len: 11111, 5 bits
+    // value: two hundred and forty-eight 1's in binary
+    // in total: 253 bits
+    d: Int as varuint32 = pow(2, 248) - 1; // two hundred and forty-eight 1's in binary
+}
+```
+
 :::note
 
   Read more on serialization here: [Compatibility with FunC](/book/func#convert-serialization)