yabase/intid

Integer helpers for short URL-safe identifiers.

The byte-oriented codecs in yabase/facade are the right tool when the input is opaque bytes (hashes, public keys, raw payloads). For the very common short-ID case — DB autoincrement ids, sequence numbers, hash truncations — callers want Int -> compact string directly. Without these helpers every project re-implements the same Int -> big-endian bytes -> trim-leading-zero shim.

encode_int_* emits canonical form: no leading zero characters beyond what the value itself requires (encode_int_base58(0) == "1", the alphabet’s zero character; encode_int_base58(58) == "21", no leading "1").

decode_int_* is tolerant of leading zero characters (decode_int_base58("0042") and decode_int_base58("42") both return the same Int), so input from external sources that zero-pads is accepted without ceremony.

decode_int_* rejects the empty string with Error(InvalidLength(0)) rather than treating it as zero. Callers can therefore distinguish “no ID was supplied” from “the ID is zero” — important for URL routing, form parsing, and database lookups. The byte-oriented decoders in yabase/facade retain the Ok(<<>>) round-trip behavior for empty input.

Negative inputs are normalized to int.absolute_value before encoding — the magnitude is what gets stored. The decode side always returns a non-negative Int.

Bounded decode

decode_int_* accepts inputs of any length, so the decoded Int can exceed any fixed integer width — Erlang Int is a bignum. Realistic backing stores cap IDs at 64 bits (SQLite INTEGER, Postgres bigserial, MySQL BIGINT), so feeding an unbounded decode_int_* result into one of those columns crashes the driver as soon as a user supplies a slightly-too-long string. For the same reason, JavaScript-target callers cap at 53 bits (Number.MAX_SAFE_INTEGER).

Use decode_int_*_bounded(input:, max:) whenever the decoded value flows into a fixed-width sink. The bounded variants return Error(Overflow) if the decoded Int exceeds max. Common caps are exported as int64_max (signed 64-bit, 2^63 - 1) and int53_max (JS-safe integer, 2^53 - 1).

pub fn decode_int_base32_crockford(
  input: String,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base32_crockford_bounded(
  input input: String,
  max max: Int,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base32_rfc4648(
  input: String,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base32_rfc4648_bounded(
  input input: String,
  max max: Int,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base36(
  input: String,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base36_bounded(
  input input: String,
  max max: Int,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base58(
  input: String,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base58_bounded(
  input input: String,
  max max: Int,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base58_flickr(
  input: String,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base58_flickr_bounded(
  input input: String,
  max max: Int,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base62(
  input: String,
) -> Result(Int, encoding.CodecError)

pub fn decode_int_base62_bounded(
  input input: String,
  max max: Int,
) -> Result(Int, encoding.CodecError)

pub fn encode_int_base32_crockford(value: Int) -> String

pub fn encode_int_base32_rfc4648(value: Int) -> String

pub fn encode_int_base36(value: Int) -> String

pub fn encode_int_base58(value: Int) -> String

pub fn encode_int_base58_flickr(value: Int) -> String

pub fn encode_int_base62(value: Int) -> String

pub const int53_max: Int

pub const int64_max: Int