randoid

Crates.iorandoid
lib.rsrandoid
version0.3.0
sourcesrc
created_at2023-01-15 06:22:25.281939
updated_at2023-01-30 08:12:54.201633
descriptionImplementation of nanoid ids that doesn't requre allocation
homepage
repositoryhttps://github.com/tmccombs/randoid
max_upload_size
id759234
size32,934
Thayne McCombs (tmccombs)

documentation

README

randoid

Rust nanoid implementation

This is a rust implementation of nanoids.

It generates unique IDs as strings that are more compact than UUIDs.

By default, it generates strings of 21 characters from an alphabet of 64 symbols (a-z, A-Z, 0-9, "_", and "-").

Features

This particular implementation of nanoid has the following features (many of which differ from the nanoid crate):

  • no_std support
  • can be used without allocating (by writing characters directly to output)
  • Allows using any Rng implementation as a source of random data.
  • Implementation is optimized for the size of the alphabet being a power of 2
  • smartstring support, if the smarstring features is enabled (as an additive feature).

Limitations

  • Requires knowing the size of the alphabet at compile time (the main reason for this is it can help the compiler optimize it better)
  • Size of alphabet must be a power of 2
  • Use of generics could increase compilation time

If you want a more generalized alphabet that doesn't have a size that is a power of two and/or isn't know in advance, then rand::distributions::Slice is probably sufficient. For example:

use rand::{Rng, distributions::Slice, thread_rng};

let alphabet = ['1', '2', '3', '4', '5', '6', '7', '9', '0', 'a', 'b', 'c'];
let id: String = thread_rng().sample_iter(&Slice::new(&alphabet).unwrap()).take(21).collect();

Feature Flags

  • alloc: Requires use of the alloc crate, and allows creating an id as a String
  • std: Use full std library
  • std-rand: Inlcude rand/std and rand/std_rng features, and add support for using thread_rng() as the default source of random data.
  • smartstring: Add a function for creating an id as a SmartString

Usage

Install

[dependencies]
randoid = "0.3.0"

Simple

use randoid::{randoid, Generator};

// All of the below generate a string like "9wxwPU-kQU-RDjYdxj6Eq"
let id = randoid();
let id = randoid!();
let id = Generator::default().gen();

Custom length


use randoid::{randoid, Generator};

// The below generate a string like "M_P_lJcWfI"
let id = randoid!(10);
let id = Generator::with_size(10).gen();

Custom alphabet

use randoid::{randoid, Generator};

let id = randoid!(21, ['a', 'b', 'c', 'd']);
let id = Generator::with_alphabet(&randoid::alphabet::HEX).gen();

Custom random number generator

use randoid::{randoid, Generator};
use rand::rngs::OsRng;

let id = randoid!(21, &randoid::alphabet::DEFAULT, OsRng);
let id = Generator::with_random(OsRng).gen();

About the name

"nanoid" was already taken by a similar library. I considered something like "nano-id" or "nanoid2", but thought those were too similar. Since the IDs are generated randomly, I decided on "randoid" as an abbreviation of "RANDOm ID".

Acknowledgments

The original nanoid of course.

Also, https://github.com/nikolay-govorov/nanoid, as inspiration for this project.

Commit count: 28

cargo fmt