nanoid 0.5.0

# Nano ID

[![Package version](https://img.shields.io/crates/v/nanoid.svg)](https://crates.io/crates/nanoid)
[![License](https://img.shields.io/badge/license-MIT%20License-blue.svg)](https://github.com/mrdimidium/nanoid/blob/main/LICENSE)
[![Build](https://github.com/mrdimidium/nanoid/actions/workflows/test.yml/badge.svg)](https://github.com/mrdimidium/nanoid/actions/workflows/test.yml)

A tiny, secure, URL-friendly, unique string ID generator for Rust

```rust
use nanoid::nanoid;

fn main() {
   let id = nanoid!(); //=> "Yo1Tr9F3iF-LFHX9i9GvA"
}
```

**Safe.** It uses cryptographically strong random APIs
and guarantees a proper distribution of symbols.

**Compact.** It uses a larger alphabet than UUID (`A-Za-z0-9_-`)
and has a similar number of unique IDs in just 21 symbols instead of 36.

## Usage

### Install

```toml
[dependencies]
nanoid = "0.5.0"
```

### Simple

The main module uses URL-friendly symbols (`A-Za-z0-9_-`) and returns an ID
with 21 characters.

```rust
use nanoid::nanoid;

fn main() {
   let id = nanoid!(); //=> "Yo1Tr9F3iF-LFHX9i9GvA"
}
```

Symbols `-,.()` are not encoded in the URL. If used at the end of a link
they could be identified as a punctuation symbol.

### Custom length

If you want to reduce ID length (and increase collisions probability),
you can pass the length as an argument generate function:

```rust
use nanoid::nanoid;

fn main() {
   let id = nanoid!(10); //=> "IRFa-VaY2b"
}
```

### Custom Alphabet or Length

If you want to change the ID's alphabet or length, you can simply pass the
custom alphabet to the `nanoid!()` macro as the second parameter:

```rust
use nanoid::nanoid;

fn main() {
    let alphabet: [char; 16] = [
        '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'a', 'b', 'c', 'd', 'e', 'f'
    ];

   let id = nanoid!(10, &alphabet); //=> "4f90d13a42"
}
```

Alphabet must contain 256 symbols or less.
Otherwise, the generator will not be secure.

### Custom Random Bytes Generator

You can replace the default safe random generator by passing your own
function as the third argument to `nanoid!()`. For instance, to use a
seed-based generator.

```rust
use nanoid::nanoid;

fn random_byte () -> u8 { 0 }

fn main() {
    fn random (size: usize) -> Vec<u8> {
        let mut bytes: Vec<u8> = vec![0; size];

        for i in 0..size {
            bytes[i] = random_byte();
        }

        bytes
    }

    nanoid!(10, &['a', 'b', 'c', 'd', 'e', 'f'], random); //=> "fbaefaadeb"
}
```

`random` function must accept the array size and return an vector
with random numbers.

If you want to use the same URL-friendly symbols with a custom random
source, the default alphabet is exposed as `nanoid::alphabet::SAFE`:

```rust
use nanoid::nanoid;

fn random (size: usize) -> Vec<u8> {
    let result: Vec<u8> = vec![0; size];

    result
}

fn main() {
    nanoid!(10, &nanoid::alphabet::SAFE, random); //=> "93ce_Ltuub"
}
```

### Seeded Random Generator

You can use a seeded random generator for reproducible IDs.
This is useful for testing or when you need deterministic output.

```rust
use nanoid::nanoid;
use rand::{rngs::StdRng, Rng, SeedableRng};

fn main() {
    let mut rng = StdRng::seed_from_u64(42);

    let id = nanoid!(10, &nanoid::alphabet::SAFE, |size| {
        let mut bytes = vec![0u8; size];
        rng.fill(&mut bytes[..]);
        bytes
    });

    println!("{}", id); //=> "wyBwxRa4Xf"
}
```

The random generator accepts `Fn` and `FnMut` closures, allowing you to use
stateful random generators. This enables use cases like:

- Seeded RNGs for reproducible IDs
- Custom stateful generators
- Integration with external random sources


### Other Programming Languages

Reference implementation on [JavaScript](https://github.com/ai/nanoid).

Nano ID was ported to many languages. You can use these ports to have
the same ID generator on the client and server side.

- [C](https://github.com/lukateras/nanoid.h)
- [C#](https://github.com/codeyu/nanoid-net)
- [C++](https://github.com/mcmikecreations/nanoid_cpp)
- [Clojure and ClojureScript](https://github.com/zelark/nano-id)
- [ColdFusion/CFML](https://github.com/JamoCA/cfml-nanoid)
- [Crystal](https://github.com/mamantoha/nanoid.cr)
- [Dart & Flutter](https://github.com/pd4d10/nanoid-dart)
- [Elixir](https://github.com/railsmechanic/nanoid)
- [Gleam](https://github.com/0xca551e/glanoid)
- [Go](https://github.com/matoous/go-nanoid)
- [Haskell](https://github.com/MichelBoucey/NanoID)
- [Haxe](https://github.com/flashultra/uuid)
- [Janet](https://sr.ht/~statianzo/janet-nanoid/)
- [Java](https://github.com/wosherco/jnanoid-enhanced)
- [Kotlin](https://github.com/viascom/nanoid-kotlin)
- [MySQL/MariaDB](https://github.com/viascom/nanoid-mysql-mariadb)
- [Nim](https://github.com/icyphox/nanoid.nim)
- [OCaml](https://github.com/routineco/ocaml-nanoid)
- [Perl](https://github.com/tkzwtks/Nanoid-perl)
- [PHP](https://github.com/hidehalo/nanoid-php)
- Python [native](https://github.com/puyuan/py-nanoid) implementation
  with [dictionaries](https://pypi.org/project/nanoid-dictionary)
  and [fast](https://github.com/oliverlambson/fastnanoid) implementation (written in Rust)
- Postgres [Extension](https://github.com/spa5k/uids-postgres)
  and [Native Function](https://github.com/viascom/nanoid-postgres)
- [R](https://github.com/hrbrmstr/nanoid) (with dictionaries)
- [Ruby](https://github.com/radeno/nanoid.rb)
- [Rust](https://github.com/nikolay-govorov/nanoid)
- [Swift](https://github.com/ShivaHuang/swift-nanoid)
- [Unison](https://share.unison-lang.org/latest/namespaces/hojberg/nanoid)
- [V](https://github.com/invipal/nanoid)
- [Zig](https://github.com/SasLuca/zig-nanoid)