Crate base_d 

base-d

A universal, multi-alphabet encoding library for Rust.

Encode binary data to 33+ alphabets including RFC standards, ancient scripts, emoji, playing cards, and more. Supports three encoding modes: mathematical base conversion, RFC 4648 chunked encoding, and direct byte-range mapping.

Quick Start

use base_d::{AlphabetsConfig, Alphabet, encode, decode};

// Load built-in alphabets
let config = AlphabetsConfig::load_default()?;
let base64_config = config.get_alphabet("base64").unwrap();

// Create alphabet
let chars: Vec<char> = base64_config.chars.chars().collect();
let padding = base64_config.padding.as_ref().and_then(|s| s.chars().next());
let alphabet = Alphabet::new_with_mode(
    chars,
    base64_config.mode.clone(),
    padding
)?;

// Encode and decode
let data = b"Hello, World!";
let encoded = encode(data, &alphabet);
let decoded = decode(&encoded, &alphabet)?;
assert_eq!(data, &decoded[..]);

Features

• 33 Built-in Alphabets: RFC standards, emoji, ancient scripts, and more
• 3 Encoding Modes: Mathematical, chunked (RFC-compliant), byte-range
• Streaming Support: Memory-efficient processing for large files
• Custom Alphabets: Define your own via TOML configuration
• User Configuration: Load alphabets from ~/.config/base-d/alphabets.toml

Encoding Modes

Mathematical Base Conversion

Treats data as a large number. Works with any alphabet size.

use base_d::{Alphabet, EncodingMode, encode};

let chars: Vec<char> = "😀😁😂🤣😃😄😅😆".chars().collect();
let alphabet = Alphabet::new_with_mode(
    chars,
    EncodingMode::BaseConversion,
    None
)?;

let encoded = encode(b"Hi", &alphabet);

Chunked Mode (RFC 4648)

Fixed-size bit groups, compatible with standard base64/base32.

use base_d::{Alphabet, EncodingMode, encode};

let chars: Vec<char> = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
    .chars().collect();
let alphabet = Alphabet::new_with_mode(
    chars,
    EncodingMode::Chunked,
    Some('=')
)?;

let encoded = encode(b"Hello", &alphabet);
assert_eq!(encoded, "SGVsbG8=");

Byte Range Mode

Direct 1:1 byte-to-emoji mapping. Zero encoding overhead.

use base_d::{Alphabet, EncodingMode, encode};

let alphabet = Alphabet::new_with_mode_and_range(
    Vec::new(),
    EncodingMode::ByteRange,
    None,
    Some(127991)  // U+1F3F7
)?;

let data = b"Hi";
let encoded = encode(data, &alphabet);
assert_eq!(encoded.chars().count(), 2);  // 1:1 mapping

Streaming

For large files, use streaming to avoid loading entire file into memory:

use base_d::{AlphabetsConfig, StreamingEncoder};
use std::fs::File;

let config = AlphabetsConfig::load_default()?;
let alphabet_config = config.get_alphabet("base64").unwrap();

// ... create alphabet from config

let mut input = File::open("large_file.bin")?;
let output = File::create("encoded.txt")?;

let mut encoder = StreamingEncoder::new(&alphabet, output);
encoder.encode(&mut input)?;

Structs

Alphabet

Represents an encoding alphabet with its characters and configuration.

AlphabetConfig

Configuration for a single alphabet loaded from TOML.

AlphabetsConfig

Collection of alphabet configurations loaded from TOML files.

StreamingDecoder

Streaming decoder for processing large amounts of encoded data efficiently.

StreamingEncoder

Streaming encoder for processing large amounts of data efficiently.

Enums

DecodeError

Errors that can occur during decoding.

EncodingMode

Encoding strategy for converting binary data to text.

Functions

decode

Decodes a string back to binary data using the specified alphabet.

encode

Encodes binary data using the specified alphabet.