Merge branch 'main' into closes-897

CHANGELOG.md

@@ -62,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The `exists` method for the `Map` type: PR [#581](https://github.com/tact-lang/tact/pull/581), PR [#938](https://github.com/tact-lang/tact/pull/938)
 - The `storeBit` method for `Builder` type and the `loadBit` method for `Slice` type: PR [#699](https://github.com/tact-lang/tact/pull/699)
 - The `toSlice` method for structs and messages: PR [#630](https://github.com/tact-lang/tact/pull/630)
-- Wider range of serialization options for integers — `uint1` through `uint256` and `int1` through `int257`: PR [#558](https://github.com/tact-lang/tact/pull/558)
+- Wider range of serialization options for integers — `uint1` through `uint256` and `int1` through `int257`: PR [#558](https://github.com/tact-lang/tact/pull/558), PR [#937](https://github.com/tact-lang/tact/pull/937)
 - The `deepEquals` method for the `Map` type: PR [#637](https://github.com/tact-lang/tact/pull/637)
 - `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.

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

@@ -3,6 +3,8 @@ title: Integers
 description: "Arithmetic in smart contracts on TON is always done with integers and never with floats"
 ---
 
+import { Badge } from '@astrojs/starlight/components';
+
 Arithmetic in smart contracts on TON is always done with integers and never with floating-point numbers since the floats are [unpredictable](https://learn.microsoft.com/en-us/cpp/build/why-floating-point-numbers-may-lose-precision). Therefore, the big accent goes on integers and their handling.
 
 The only primitive number type in Tact is `Int{:tact}`, for $257$-bit signed integers.\
@@ -87,7 +89,7 @@ Motivation is very simple:
 * Storing $1000$ $257$-bit integers in state [costs](https://docs.ton.org/develop/smart-contracts/fees#how-to-calculate-fees) about $0.184$ TON per year.
 * Storing $1000$ $32$-bit integers only costs $0.023$ TON per year by comparison.
 
-### Serialization types
+### Common serialization types
 
 Name             | [TL-B][tlb]                 | Inclusive range             | Space taken
 :--------------: | :-------------------------: | :-------------------------: | :------------------------:
@@ -106,6 +108,19 @@ Name             | [TL-B][tlb]                 | Inclusive range             | S
 `int257{:tact}`  | [`int257`][tlb-builtin]     | $-2^{256}$ to $2^{256} - 1$ | $257$ bits = $32$ bytes + $1$ bit
 `coins{:tact}`   | [`VarUInteger 16`][varuint] | $0$ to $2^{120} - 1$        | between $4$ and $124$ bits, [see below](#serialization-coins)
 
+### Arbitrary bit-width types
+
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
+In addition to [common serialization types](#common-serialization-types), it's possible to specify arbitrary bit-width integers by using a prefix `int` or `uint` followed by digits. For example, writing `int7{:tact}` refers to a signed $7$-bit integer.
+
+The minimum allowed bit-width of an `Int{:tact}` type is $1$, while the maximum is $257$ for `int` prefixes (signed integers) and $256$ for `uint` prefixes (unsigned integers).
+
+Name             | [TL-B][tlb]            | Inclusive range                 | Space taken
+:--------------: | :--------------------: | :-----------------------------: | :---------:
+`uintX{:tact}`   | [`uintX`][tlb-builtin] | $0$ to $2^{X} - 1$              | $X$ bits, where $X$ is between $1$ and $256$
+`intX{:tact}`    | [`intX`][tlb-builtin]  | $-2^{X - 1}$ to $2^{X - 1} - 1$ | $X$ bits, where $X$ is between $1$ and $257$
+
 ### Variable `coins` type {#serialization-coins}
 
 In Tact, `coins{:tact}` is an alias to [`VarUInteger 16`][varuint] in [TL-B][tlb] representation, i.e. it takes a variable bit length depending on the optimal number of bytes needed to store the given integer and is commonly used for storing [nanoToncoin](/book/integers#nanotoncoin) amounts.
@@ -174,7 +189,7 @@ contract ComputeErrorsOhNo with Deployable {
 }
 ```
 
-Here, `oneByte` is serialized as a [`uint8`](#serialization-types), which occupies only one byte and ranges from $0$ to $2^{8} - 1$, which is $255$. And when used in runtime calculations no overflow happens and everything is calculated as a $257$-bit signed integers. But the very moment we decide to store the value of `tmp` back into `oneByte` we get an error with the [exit code 5](/book/exit-codes#5), which states the following: `Integer out of the expected range`.
+Here, `oneByte` is serialized as a [`uint8`](#common-serialization-types), which occupies only one byte and ranges from $0$ to $2^{8} - 1$, which is $255$. And when used in runtime calculations no overflow happens and everything is calculated as a $257$-bit signed integers. But the very moment we decide to store the value of `tmp` back into `oneByte` we get an error with the [exit code 5](/book/exit-codes#5), which states the following: `Integer out of the expected range`.
 
 :::caution
   Therefore, be **very** careful with numbers and always double-check calculations when using serialization.

docs/src/content/docs/book/maps.mdx

@@ -293,7 +293,7 @@ It's often useful to set an upper-bound restriction on such maps, so that you [d
 
 ## Serialization
 
-It's possible to do [integer serialization](/book/integers#serialization-types) of map keys, values or both to [preserve space and reduce storage costs](/book/integers#serialization):
+It's possible to do [integer serialization](/book/integers#common-serialization-types) of map keys, values or both to [preserve space and reduce storage costs](/book/integers#serialization):
 
 ```tact
 struct SerializedMapInside {