---
title: "Integer"
description: "A whole number as bytes. Pick a base or bring your own digits"
canonical_url: "https://encodings.agntn.dev/encodings/integer"
---
# Integer

> A whole number as bytes. Pick a base or bring your own digits

<encoding-facts name="integer">



</encoding-facts>

The whole text is one number. `integer` turns it into big-endian bytes and back. No BigInt loop needed. `decimal` gives each byte its own number instead.

```ts
encode("decimal", "Hi");                   // "72 105"
encode("integer", "Hi");                   // "18537"
encode("integer", "Hello");                // "310939249775"
encode("integer", "Hello", { radix: 16 }); // "48656c6c6f"
```

## Choosing a base or custom digits

`radix` runs from 2 to 36 and defaults to 10. Its digits are `0-9` followed by `a-z`. Decoding accepts either case.

```ts
encode("integer", "Hello", { radix: 36 }); // "3yud78mn"
encode("integer", "Hello", { radix: 9 });  // "1081526044305"
```

Want base 62 or emoji digits? Use `digits` instead of `radix`. Put one symbol per digit, lowest first. Case counts in a custom set.

```ts
encode("integer", "Hi", { digits: "🌑🌒🌓🌔" }); // "🌒🌑🌓🌑🌒🌓🌓🌒"
```

Decoding skips ASCII whitespace. Wrap a big ugly number over lines. It's still one number.

## Why do leading zero bytes vanish?

A number has no digits for leading zero bytes. They're lost when you encode.

```ts
encode("integer", new Uint8Array([0, 1, 255])); // "511"
decode("integer", "511").bytes;                  // [1, 255]
```

That's a bad surprise if you need the original width. Set `width` when decoding to restore leading zero bytes. A number that needs more bytes is refused.

```ts
decode("integer", "255", { width: 4 }).bytes; // [0, 0, 0, 255]
decode("integer", "256", { width: 1 });       // throws: integer: the number takes 2 bytes, over width 1
```

## Bijective numerals and spreadsheet columns

`bijective: true` removes the zero digit. The first symbol means 1. With default digits, bijective bases go up to 35.

```ts
encode("integer", "Hello", { radix: 9, bijective: true }); // "981525944295"
decode("integer", "10", { bijective: true });              // throws: integer: "0" (U+0030) is not a digit in bijective base 10
```

A spreadsheet column is a number in disguise. Use uppercase letters as digits and turn on bijective mode.

```ts
const columns = { digits: "ABCDEFGHIJKLMNOPQRSTUVWXYZ", bijective: true };

decode("integer", "A", columns).bytes;    // [1]
decode("integer", "Z", columns).bytes;    // [26]
decode("integer", "AA", columns).bytes;   // [27]
decode("integer", "XFD", columns).bytes;  // [64, 0], so 16384
```

`XFD` is the last column Excel has. Now you know its number.

Zero encodes as `"0"`, or as an empty string in bijective mode. Empty bytes encode as `"0"`.

## Can identify spot a whole number?

Every run of digits is a whole number. That's not much of a clue. `identify` only considers `integer` when it decodes to at least eight bytes of readable text. So `3432` can still be hex. And `310939249775` isn't guessed as `integer`. Decode it by name.

```ts
encode("integer", "attack at dawn");                     // "1976620216402300889624482718775150"
identify("1976620216402300889624482718775150")[0]?.text; // "attack at dawn"
```

`peel` can confirm an integer layer too.

```ts
peel("MTk3NjYyMDIxNjQwMjMwMDg4OTYyNDQ4MjcxODc3NTE1MA==").map((layer) => layer.encoding);
// ["base64", "integer"], and the last layer's text is "attack at dawn"
```

`bigint` is an alias for `integer`. Need the codec alone? `@agntn/encodings/integer` exports `integer`, and its `decode` hands back a `Uint8Array` straight away.

In the CLI, `encodings encode integer Hello` prints `310939249775`. The options are flags: `--radix`, `--digits`, `--bijective` and `--width`.


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
