Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

/p/nt/cford32/v0

Directory · 6 Files
README.md Open

v0 - Unaudited This is an initial version of this package that has not yet been formally audited. A fully audited version will be published as a subsequent release. Use in production at your own risk.

cford32 - Crockford Base32 encoding

Modified base32 encoding using the Crockford alphabet. Designed to be human-readable, error-resistant, and pronounceable: the ambiguous characters I, L, O, U are excluded from the encoding, and decoding accepts I/L as 1 and O as 0. Output is never padded.

Usage

 1import "gno.land/p/nt/cford32/v0"
 2
 3// Byte slice encode/decode.
 4encoded := cford32.EncodeToString([]byte("hello"))  // uppercase, no padding
 5decoded, err := cford32.DecodeString(encoded)        // []byte("hello")
 6
 7// Lowercase variant.
 8lower := cford32.EncodeToStringLower([]byte("hello"))
 9
10// Compact uint64 encoding: 7 bytes for id < 2^34, else 13 bytes.
11enc := cford32.PutCompact(42)
12back, _ := cford32.Uint64(enc) // 42
13
14// Full fixed-width uint64 encoding (always 13 bytes).
15full := cford32.PutUint64(42)

API

 1// Errors.
 2type CorruptInputError int64
 3func (e CorruptInputError) Error() string
 4
 5// Length helpers.
 6func DecodedLen(n int) int
 7func EncodedLen(n int) int
 8
 9// Byte slice encoding.
10func Encode(dst, src []byte)                          // uppercase
11func EncodeLower(dst, src []byte)                     // lowercase
12func EncodeToString(src []byte) string                // uppercase
13func EncodeToStringLower(src []byte) string           // lowercase
14func AppendEncode(dst, src []byte) []byte
15func AppendEncodeLower(dst, src []byte) []byte
16
17// Byte slice decoding. Case-insensitive; ignores \r and \n.
18func Decode(dst, src []byte) (n int, err error)
19func DecodeString(s string) ([]byte, error)
20func AppendDecode(dst, src []byte) ([]byte, error)
21
22// uint64 encoding.
23func PutUint64(id uint64) [13]byte                    // full, uppercase
24func PutUint64Lower(id uint64) [13]byte               // full, lowercase
25func PutCompact(id uint64) []byte                     // 7 bytes if id < 2^34, else 13, lowercase
26func AppendCompact(id uint64, b []byte) []byte
27func Uint64(b []byte) (uint64, error)                 // accepts both compact (7) and full (13)
28
29// Streaming I/O.
30func NewEncoder(w io.Writer) io.WriteCloser
31func NewEncoderLower(w io.Writer) io.WriteCloser
32func NewDecoder(r io.Reader) io.Reader

Notes

  • Alphabet: 0123456789ABCDEFGHJKMNPQRSTVWXYZ (no I, L, O, U).
  • Decoding is case-insensitive; I/i/L/l decode as 1, and O/o decode as 0.
  • The compact uint64 encoding preserves lexicographic order with numeric order, making encoded IDs suitable as ordered keys.
  • The compact and full uint64 encodings are unambiguously distinguished by their first character: 0-f indicates compact (7 bytes), g-z indicates full (13 bytes).
  • Values in [0, 2^34) have BOTH a compact and a full encoding. Pick one scheme per key space and stick to it: mixing both for the same value breaks the lexicographic-order property. PutCompact rolls over from compact to full at 2^34 automatically, which is safe as long as everything in that space is generated the same way.
  • For sequential IDs, see gno.land/p/nt/seqid/v0.