Encodings

Integer

A whole number as bytes. Pick a base or bring your own digits
IDinteger04 / 20integer ยท 10 characters
Encoding / Integer

Integer

The whole text as one number. Pick your base.

Overhead
+141% on random bytes
Padding
none
Standard
Unsigned big-endian integer in a positional numeral
Family
1 in integer
family 1 / 20

Sample

Out
32309054545037006034346730529
Back
"hello world!"

Options

radixnumber
optional
Base from 2 to 36, digits 0-9 then a-z (default 10); up to 35 with bijective
digitsstring
optional
One symbol per digit, lowest first, in place of radix; case counts
bijectiveboolean
default false
No zero digit: the first symbol is 1, as in spreadsheet columns
widthnumber
optional
Bytes to fill with leading zeros; a number that needs more is refused

Access

Importimport { integer } from "@agntn/encodings/integer"
CLIencodings encode integer 'hello world!'
Tryplayground with the sample above

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.