# Numbers (https://docs-kyrm16yq7-ton-core-docs.vercel.app/llms/tolk/types/numbers/content.md)



At runtime, there are only 257-bit signed integers. They are represented by the Tolk's general `int` type.

However, at the start and end of each execution, the contract's state is deserialized and serialized, respectively. To optimize space and reduce storage costs, it is possible to encode integer values using fewer bits.

Tolk provides additional integer types to accommodate (de)serialization:

| Name             | Inclusive range                       | Space taken                              | Examples                       |
| ---------------- | ------------------------------------- | ---------------------------------------- | ------------------------------ |
| Signed `intN`    | -2<sup>N-1</sup> to 2<sup>N-1</sup>-1 | `N` bits, where `N` is between 1 and 257 | `int32`, `int257`, `int7`      |
| Unsigned `uintN` | 0 to 2<sup>N</sup>-1                  | `N` bits, where `N` is between 1 and 256 | `uint16`, `uint256`, `uint119` |

There are also types of variable bit-width:

| Name                 | Inclusive range                       | Space taken            | Notes                                                                  |
| -------------------- | ------------------------------------- | ---------------------- | ---------------------------------------------------------------------- |
| Unsigned `coins`     | 0 to 2<sup>120</sup>-1                | Between 4 and 124 bits | They represent nanograms, where 10<sup>9</sup> nanograms equals 1 GRAM |
| Unsigned `varuint16` | Same as `coins`                       | Same as `coins`        | Rarely used                                                            |
| Unsigned `varuint32` | 0 to 2<sup>248</sup>-1                | Between 5 and 253 bits | Rarely used                                                            |
| Signed `varint16`    | -2<sup>119</sup> to 2<sup>119</sup>-1 | Same as `coins`        | Rarely used                                                            |
| Signed `varint32`    | -2<sup>247</sup> to 2<sup>247</sup>-1 | Between 5 and 253 bits | Rarely used                                                            |

<Callout type="caution">
  All these types are **257-bit integers at runtime**. [Overflows can occur at runtime](/llms/tvm/exit-codes/content.md), but they are more likely during serialization.

  For example, subtracting $300$ from a variable of type `uint8` does not cause a runtime overflow. Yet, attempting to store the result back to the same variable triggers [exit code 5: integer out of expected range](/llms/tvm/exit-codes/content.md).
</Callout>

## Literals [#literals]

All the following constants are of `int` type:

```tolk
// Binary literal
const TEN = 0b1010;

// Hex literal
const MAX_UINT8 = 0xFF;

// Allowed values range from -2^256 to 2^256-1
const MAX_INT = 115792089237316195423570985008687907853269984665640564039457584007913129639935;
```

### Numeric separators [#numeric-separators]

Integer literals may contain `_` separators to improve readability. They are ignored by the compiler.

```tolk
const A = 1_000_000;
const B = 0x_ABCD_EF01;
const C = 0b_1010_1011_0000;
```

## First-class types [#first-class-types]

All integer types can be nullable, combined within a union, and otherwise used in structural or multi-valued types:

```tolk
struct Demo {
    f1: int32?           // nullable
    f2: int32 | uint64   // union
    pair: (int8, coins)
}

fun demo(d: Demo) {
    if (d.f1 != null) {
        d.f1    // smart cast to `int32`
    }
    d.pair.1    // `coins`
}
```

## No floating-point numbers [#no-floating-point-numbers]

The virtual machine supports only signed 257-bit integers. Floating-point numbers do not exist.

Represent monetary GRAM values with `coins`:

```tolk
// 1.23 GRAM or 1,230,000,000 nanograms
const MIN_BALANCE = grams("1.23")
```

## Serialization [#serialization]

[Serialization](/llms/languages/tolk/types/overall-serialization/content.md) works as follows:

* `int` — not serializable; use `intN` and other types.
* `intN` — a fixed `N`-bit signed integer.
* `uintN` — a fixed `N`-bit unsigned integer.
* `coins` — an alias to `varuint16`.
* `varint16` — 4 bits of length followed by an 8 \* length-bit number.
* `varuint16` — unsigned version of `varint16`.
* `varint32` — 5 bits of length followed by an 8 \* length-bit number.
* `varuint32` — unsigned version of `varint32`.

### `intN` describes serialization, `int` does not [#intn-describes-serialization-int-does-not]

To automatically parse binary data, the compiler must load and store integers correctly. When designing a contract schema, fields are described in terms such as "`queryID` is unsigned 64-bit" and "`counterValue` is 32-bit". This is translates directly in Tolk:

```tolk
struct IncMessage {
    queryID: uint64
    counterValue: int32
}
```

As a result, `IncMessage` can be serialized to a cell and decoded back.

The general-purpose type `int` represents an integer with no serialization information. Consider this struct:

```tolk
struct Point {
    x: int
    y: int
}
```

It is valid and it is possible to create a variable `p` of type `Point`. However, a call `p.toCell()` would produce the following error:

```ansi
error: auto-serialization via toCell() is not available for type `Point`
       because field `Point.x` of type `int` can't be serialized
       because type `int` is not serializable, it doesn't define binary width
       hint: replace `int` with `int32` / `uint64` / `coins` / etc.
```

To make the struct serializable, replace `int` with a specific integer type:

```tolk
struct Point {
    x: int8
    y: int8
}
```

### Overflow occurs only at serialization [#overflow-occurs-only-at-serialization]

Consider the following code:

```tolk
var v: uint8 = 255;
v += 1;     // 256
```

The variable `v` there would neither overflow nor be clamped at runtime. Instead, it would be equal to 256 during subsequent execution steps.

There are no runtime bounds checks, and overflows of all integer types occur only during serialization, except for the general `int` type, which can [overflow when doing arithmetic](/llms/tvm/exit-codes/content.md).

```tolk
struct Resp {
    outValue: uint8
}

fun demo(resp: Resp) {
    // 256, no errors yet
    resp.outValue = v;

    // A runtime overflow error that is caused by serialization
    // of the struct containing an uint8 to a cell.
    resp.toCell();
}
```

### Generic `int` implicitly casts to and from any `intN` [#generic-int-implicitly-casts-to-and-from-any-intn]

All arithmetic operations on `intN` degrade to `int` and all [numeric literals](#literals) are of type `int`.

To prevent further errors, Tolk disallows direct assignments between `intN` and `intM` types, when `N` and `M` are not equal.

```tolk
fun takeAnyInt(a: int) { /* ... */ }
fun getAnyInt(): int { return 42 }

fun f(op: int32, qid: uint64) {
    op = qid;               // error
    op = qid as int32;      // ok

    op + query_id;          // ok, int
    if (op == qid) {}       // ok, not assignment

    takeAnyInt(op);         // ok
    op = getAnyInt();       // ok

    var amount: int32 = 1000;
    var percent: uint8 = 50;
    // ok, int
    var new = amount * percent / 100;
    // ok, int auto-casts to int32
    amount = new;
}
```

### Type `coins` and function `grams("0.05")` [#type-coins-and-function-grams005]

Similar to `int32`, Tolk has a dedicated `coins` type representing nanogram values.

The `coins` type has special serialization rules. It's serialized as variadic integer: small values consume fewer, large values consume more.

Arithmetic with `coins` degrades to `int`, similar to `intN`, except for addition or subtraction operations, where the `coins` type is preserved.

Values of type `int` can be cast back to `coins`, following the same rules as `intN`.

There is a `grams` built-in function, which calculates nanogram values at compile-time. It accepts only constants and literals, e.g., `grams(some_variable)` is invalid.

```tolk
const ONE_GRAM = grams("1");     // `coins`, value: 1000000000

fun calcCost() {
    val cost = grams("0.05");   // `coins`, value: 50000000
    return ONE_GRAM + cost;
}
```

The old `ton("0.05")` function is still available for backward compatibility, but `grams` is preferred.