Function custom 

pub fn custom(length: usize, alphabet: &[u8]) -> String

Available on crate feature nanoid only.

Generate a NanoID with a custom length and alphabet.

This entry point is permissive: an empty alphabet returns the empty string, and duplicate bytes in the alphabet are tolerated (the repeated characters appear with higher probability). Use try_custom when you want validation to surface those cases as an error.

Example

use id_forge::nanoid;

let id = nanoid::custom(8, b"0123456789ABCDEF");
assert_eq!(id.len(), 8);
assert!(id.chars().all(|c| "0123456789ABCDEF".contains(c)));

Examples found in repository

examples/bench.rs (line 50)

fn main() {
    println!("id-forge throughput (single thread, release build)");
    println!("---------------------------------------------------");

    let iters = 1_000_000;
    bench("Uuid::v4", iters, Uuid::v4);
    bench("Uuid::v7", iters, Uuid::v7);
    bench("Ulid::new", iters, Ulid::new);

    let sf = Snowflake::new(1);
    bench("Snowflake::next_id", iters, || sf.next_id());

    bench("nanoid::generate", iters / 5, nanoid::generate);
    bench("nanoid::with_length(8)", iters / 5, || {
        nanoid::with_length(8)
    });
    bench("nanoid::custom(16, hex)", iters / 5, || {
        nanoid::custom(16, b"0123456789abcdef")
    });
    bench("nanoid::custom(21, 17-char)", iters / 5, || {
        nanoid::custom(21, b"ABCDEFGHIJKLMNOPQ")
    });
}

examples/nanoid_short_url.rs (line 35)

fn main() {
    println!("== Default 21-char URL-safe IDs ==");
    for _ in 0..5 {
        println!("  {}", nanoid::generate());
    }

    println!("\n== Short codes (8 chars, URL-safe default) ==");
    for _ in 0..5 {
        println!("  {}", nanoid::with_length(8));
    }

    println!("\n== Readable alphabet (no 0/O/I/L/U), 10 chars ==");
    println!("  alphabet has {} chars", READABLE_32.len());
    for _ in 0..5 {
        println!("  {}", nanoid::custom(10, READABLE_32));
    }

    println!("\n== URL-safe lowercase, 12 chars ==");
    for _ in 0..5 {
        println!("  {}", nanoid::custom(12, URL_36));
    }

    println!("\n== Collision sweep at length 8 on URL_36 ==");
    let n = 100_000;
    let mut seen = HashSet::with_capacity(n);
    let mut collisions = 0usize;
    for _ in 0..n {
        if !seen.insert(nanoid::custom(8, URL_36)) {
            collisions += 1;
        }
    }
    println!("  drew {n} IDs of length 8");
    println!("  collisions = {collisions}");
    println!("  (URL_36^8 = {} ids/space)", (URL_36.len() as u64).pow(8));
}

examples/nanoid_validate.rs (line 55)

fn main() {
    println!("== try_custom: happy path ==");
    let id = nanoid::try_custom(16, b"0123456789abcdef").unwrap();
    println!("  {id}");

    println!("\n== try_custom: empty alphabet ==");
    match nanoid::try_custom(8, b"") {
        Ok(s) => println!("  unexpected ok: {s}"),
        Err(e) => println!("  Err: {e}"),
    }

    println!("\n== try_custom: duplicate byte ==");
    match nanoid::try_custom(8, b"abcda") {
        Ok(s) => println!("  unexpected ok: {s}"),
        Err(AlphabetError::Duplicate(b)) => {
            println!("  Err: duplicate byte 0x{b:02x} ({:?})", b as char);
        }
        Err(e) => println!("  Err: {e}"),
    }

    println!("\n== validate_alphabet for startup-time config check ==");
    let alphabets: &[(&str, &[u8])] = &[
        (
            "url-safe-64",
            b"_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
        ),
        ("hex", b"0123456789abcdef"),
        ("empty", b""),
        ("dup", b"aab"),
    ];
    for (label, alphabet) in alphabets {
        match nanoid::validate_alphabet(alphabet) {
            Ok(()) => println!("  {label:<14} OK ({} chars)", alphabet.len()),
            Err(e) => println!("  {label:<14} REJECTED: {e}"),
        }
    }

    println!("\n== Permissive `custom` tolerates duplicates ==");
    // Duplicates skew the output toward repeated chars. `custom`
    // accepts this by design; `try_custom` does not.
    let skewed = nanoid::custom(20, b"AAAAAA");
    println!("  custom(20, b\"AAAAAA\") = {skewed}");

    println!("\n== Cache a validated alphabet once at startup ==");
    let alphabet = b"0123456789ABCDEFGHJKMNPQRSTVWXYZ";
    nanoid::validate_alphabet(alphabet).expect("startup: config alphabet must be valid");
    // ... hot path now uses `custom` since the alphabet has already
    // been vetted; no per-call validation cost.
    for _ in 0..3 {
        println!("  {}", nanoid::custom(12, alphabet));
    }
}