base32

Base32 Package

Crockford Base32 encoding and CRC-10 checksums for human-readable, error-correcting identifiers.

Features

• Crockford Base32 Encoding

  • Human-readable alphabet (excludes ambiguous characters: I, L, O, U)
  • Case-insensitive decoding
  • Automatic error correction (I→1, L→1, O→0)
  • Fixed-length and compact encoding modes
  • URL-safe output

• CRC-10 Checksums

  • 99.9%+ error detection rate
  • Detects single character errors (100%)
  • Detects transpositions (99.9%+)
  • Detects double errors (99.9%+)
  • Only 2 characters overhead

Installation

go get github.com/jasoet/pkg/v2

Quick Start

package main

import (
    "fmt"
    "github.com/jasoet/pkg/v2/base32"
)

func main() {
    // Encode a number
    id, err := base32.EncodeBase32(12345, 8)  // "0000C1S", nil
    if err != nil {
        panic(err)
    }

    // Add checksum for error detection
    idWithChecksum, err := base32.AppendChecksum(id)
    if err != nil {
        panic(err)
    }

    // Validate checksum
    if base32.ValidateChecksum(idWithChecksum) {
        fmt.Println("Valid ID!")
    }

    // Decode back
    value, _ := base32.DecodeBase32(id)
    fmt.Println(value)  // 12345
}

Use Cases

1. URL Shorteners

// Database ID to short code
databaseID := uint64(123456789)
shortCode := base32.EncodeBase32Compact(databaseID)
// https://short.url/3QTYY1

// Decode back
decoded, _ := base32.DecodeBase32(shortCode)

2. Order/Transaction IDs

// Generate order ID with timestamp and sequence
timestamp := uint64(time.Now().Unix())
sequence := uint64(12345)

timeCode, _ := base32.EncodeBase32(timestamp, 8)
seqCode, _ := base32.EncodeBase32(sequence, 4)

orderID, _ := base32.AppendChecksum("ORD-" + timeCode + "-" + seqCode)
// ORD-6HG4K2N0-00C1P9XY

3. License Keys

productID := uint64(42)
customerID := uint64(789)

product, _ := base32.EncodeBase32(productID, 2)
customer, _ := base32.EncodeBase32(customerID, 4)

licenseKey, _ := base32.AppendChecksum(product + customer)
// Format: 16-00NC-XY

4. Voucher/Coupon Codes

voucherID := uint64(9999)
code, _ := base32.EncodeBase32(voucherID, 4)
codeWithChecksum, _ := base32.AppendChecksum(code)
// 09ZZ-XY (easy to type, error-correcting)

5. IoT Device IDs

deviceSerial := uint64(123456)
deviceID := base32.EncodeBase32Compact(deviceSerial)
// Compact, human-readable device identifier

API Reference

Base32 Encoding

EncodeBase32(value uint64, length int) (string, error)

Encodes an unsigned integer to a fixed-length Base32 string.

encoded, err := base32.EncodeBase32(42, 4)     // "001A", nil
encoded, err := base32.EncodeBase32(12345, 6)  // "000C1S", nil

EncodeBase32Compact(value uint64) string

Encodes to the minimum number of characters needed (no error return).

encoded := base32.EncodeBase32Compact(0)      // "0"
encoded := base32.EncodeBase32Compact(12345)  // "C1S"

DecodeBase32(encoded string) (uint64, error)

Decodes a Base32 string to an unsigned integer.

value, err := base32.DecodeBase32("C1P9")  // 12345, nil
value, err := base32.DecodeBase32("c1p9")  // 12345, nil (case-insensitive)
value, err := base32.DecodeBase32("C1PO")  // 12345, nil (O→0 correction)

NormalizeBase32(input string) string

Normalizes Base32 input by:

• Converting to uppercase
• Removing dashes and spaces
• Correcting common mistakes (I→1, L→1, O→0)

base32.NormalizeBase32("abc-def")  // "ABCDEF"
base32.NormalizeBase32("1O 2I")    // "1021"

IsValidBase32Char(c rune) bool

Checks if a character is valid in Base32 encoding.

base32.IsValidBase32Char('A')  // true
base32.IsValidBase32Char('O')  // true (auto-corrected)
base32.IsValidBase32Char('U')  // false

Checksums

CalculateChecksum(data string) (string, error)

Computes a 2-character CRC-10 checksum.

checksum, err := base32.CalculateChecksum("ABC123")  // "XY", nil

AppendChecksum(data string) (string, error)

Adds checksum to the end of data.

withChecksum, err := base32.AppendChecksum("ABC123")  // "ABC123XY", nil

ValidateChecksum(input string) bool

Verifies checksum validity.

valid := base32.ValidateChecksum("ABC123XY")  // true
valid := base32.ValidateChecksum("ABC123ZZ")  // false

StripChecksum(input string) string

Removes the last 2 characters (checksum).

data := base32.StripChecksum("ABC123XY")  // "ABC123"

ExtractChecksum(input string) string

Extracts the last 2 characters (checksum).

checksum := base32.ExtractChecksum("ABC123XY")  // "XY"

Error Detection

The CRC-10 checksum provides excellent error detection:

Error Type	Detection Rate
Single character error	100%
Transposition (AB→BA)	99.9%+
Double errors	99.9%+
Insertion/deletion	High

Example

// Valid ID
validID, _ := base32.AppendChecksum("ABC123")

// Corrupted ID (A → X)
corrupted := "XBC123" + base32.ExtractChecksum(validID)
base32.ValidateChecksum(corrupted)  // false - detected!

// Transposition (AB → BA)
chars := []rune(validID)
chars[0], chars[1] = chars[1], chars[0]
transposed := string(chars)
base32.ValidateChecksum(transposed)  // false - detected!

Examples

Run comprehensive examples:

go run -tags=example ./base32/examples

See examples/main.go for detailed usage patterns.

Performance

Benchmarks on modern hardware:

BenchmarkEncodeBase32-8          50000000    25.3 ns/op
BenchmarkDecodeBase32-8          30000000    45.2 ns/op
BenchmarkCalculateChecksum-8     10000000   125.0 ns/op
BenchmarkValidateChecksum-8       8000000   160.0 ns/op

Alphabet Reference

Crockford Base32 Alphabet

0 1 2 3 4 5 6 7 8 9 A B C D E F G H J K M N P Q R S T V W X Y Z

Excluded characters:

• I - Looks like 1 (auto-corrected to 1)
• L - Looks like 1 (auto-corrected to 1)
• O - Looks like 0 (auto-corrected to 0)
• U - Could be confused with V

This design minimizes human transcription errors.

Best Practices

1. Always use checksums for user-facing IDs

   // ✓ Good
   id, err := base32.AppendChecksum(data)
   
   // ✗ Avoid
   id := data  // No error detection

2. Normalize user input

   userInput := "ab-cd-ef"
   normalized := base32.NormalizeBase32(userInput)

3. Use fixed-length encoding for databases

   // Consistent length for indexing
   id := base32.EncodeBase32(value, 10)

4. Use compact encoding for URLs

   // Shorter URLs
   shortCode := base32.EncodeBase32Compact(value)

Migration from tix-core

If migrating from github.com/jasoet/tix-core/encoding:

Before:

import "github.com/jasoet/tix-core/encoding"

After:

import "github.com/jasoet/pkg/v2/base32"

API is 100% compatible - only the import path and package name change.

Contributing

See the main pkg/v2 repository for contribution guidelines.

License

MIT License - see LICENSE for details.

---

Part of github.com/jasoet/pkg/v2 - Production-ready Go utility packages.