`enc`

Pure-ilusm encoding utilities - convert between bytes and characters using a u8.bin byte table, encode strings as standard Base64 or URL-safe Base64url (no padding), decode Base64, encode as Base32, hex-encode bytes to uppercase hex string, decode a hex string to bytes, percent-encode a string for URLs (RFC 3986 unreserved chars passthrough), and decode percent-encoded strings including + as space.

Load with: use enc

What this module does

enc is a self-contained encoding library written entirely in ilusm. It loads a 255-byte binary table (u8.bin) on first use and caches it for subsequent calls, giving it a fast path for byte↔character conversions. This table is the foundation for all higher-level operations: Base64 uses it to read byte values; URL encoding uses it to compute hex digits from byte values.

Quick example

use enc

# Base64
encoded = enc.b64("Hello, World!")  # "SGVsbG8sIFdvcmxkIQ=="
decoded = enc.ub4(encoded)          # "Hello, World!"

# Base64url (URL-safe, no padding)
token = enc.encb6("my-binary-data")  # uses - and _ instead of + and /

# Hex
h = enc.hex("ABC")  # "414243"
s = enc.uhx("414243")  # "ABC"

# URL percent-encoding
safe = enc.ue("hello world/foo?bar=1")  # "hello%20world%2Ffoo%3Fbar%3D1"
raw  = enc.ud("hello%20world")          # "hello world"

# Base32
b32 = enc.b32("foobar")  # "MZXW6YTBOI======"

# Byte ↔ character
prn(enc.ord("A"))    # 65
prn(enc.chr(65))     # "A"

Functions

Base64

enc_btoa(s) / enc.b64(s)

Encodes string s to standard Base64 with = padding.

enc_atob(s) / enc.ub4(s) / enc.ub64(s) / enc.encub(s)

Decodes a standard Base64 string back to the original bytes. Whitespace in the input is ignored.

enc.encb6(s)

Encodes to URL-safe Base64url: replaces + with -, / with _, and strips padding =.

Base32 and hex

enc.b32(s)

Encodes string s as RFC 4648 Base32 (uppercase, =-padded).

enc.hex(s)

Encodes every byte of s as two uppercase hex digits. Returns a hex string of length 2 × len(s).

enc.uhx(s)

Decodes a hex string back to bytes. Input length must be even.

URL encoding

enc_pesc(s) / enc.ue(s) / enc.encur(s)

Percent-encodes s per RFC 3986. Unreserved characters (A–Z a–z 0–9 - . _ ~) pass through; all others become %XX.

enc_pds(s) / enc.ud(s)

Decodes a percent-encoded string. Also converts + to space (form-encoding compatibility).

Byte/character primitives

enc_chr(v) / enc.chr(v)

Returns the character for byte value v (0–255) using the u8.bin table. Byte 0 (null) is not supported in stage-0.

enc_byte(c) / enc_ord(c) / enc.ord(c)

Returns the byte value (1–255) of single-character string c.

enc_mod(a, m) / enc.mod(a, m)

Integer modulo a mod m implemented without the % operator (for bootstrap compatibility).

Notes

Loads lib/stdlib/u8.bin (255 bytes, values 1–255) on first use and caches it. The file must be present alongside the stdlib.
Requires trl.