Struct Uuid 

pub struct Uuid(/* private fields */);

Available on crate feature uuid only.

A 128-bit UUID.

The internal representation is 16 big-endian bytes per RFC 9562.

Example

use id_forge::uuid::Uuid;

let id = Uuid::v4();
assert_eq!(id.to_string().len(), 36);

Implementations

impl Uuid

pub const fn nil() -> Self

The Nil UUID: all 128 bits set to zero (RFC 9562 §5.9).

Example

use id_forge::uuid::Uuid;

assert_eq!(Uuid::nil().to_string(), "00000000-0000-0000-0000-000000000000");

Examples found in repository

examples/basic.rs (line 11)

fn main() {
    let v4 = Uuid::v4();
    println!("UUID v4:    {v4} (version={})", v4.version());
    println!("UUID v7:    {}", Uuid::v7());
    println!("UUID nil:   {}", Uuid::nil());

    let a = Ulid::new();
    let b = Ulid::new();
    println!("ULID a:     {a}");
    println!("ULID b:     {b} (monotonic: {})", b > a);

    let gen = Snowflake::new(1);
    let sf = gen.next_id();
    let (ts_offset, worker, seq) = Snowflake::parts(sf);
    println!(
        "Snowflake:  {sf}  (ts+epoch={}, worker={worker}, seq={seq})",
        ts_offset + gen.epoch_ms()
    );

    println!("NanoID 21:  {}", nanoid::generate());
    println!("NanoID 8:   {}", nanoid::with_length(8));

    assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
    assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
}

pub const fn max() -> Self

The Max UUID: all 128 bits set to one (RFC 9562 §5.10).

Example

use id_forge::uuid::Uuid;

assert_eq!(Uuid::max().to_string(), "ffffffff-ffff-ffff-ffff-ffffffffffff");

pub fn v4() -> Self

Construct a v4 (random) UUID per RFC 9562 §5.4.

122 random bits with the version nibble set to 0100 and the variant bits set to 10 (RFC 4122 layout).

Example

use id_forge::uuid::Uuid;

let id = Uuid::v4();
assert_eq!(id.version(), 4);

Examples found in repository

examples/basic.rs (line 8)

fn main() {
    let v4 = Uuid::v4();
    println!("UUID v4:    {v4} (version={})", v4.version());
    println!("UUID v7:    {}", Uuid::v7());
    println!("UUID nil:   {}", Uuid::nil());

    let a = Ulid::new();
    let b = Ulid::new();
    println!("ULID a:     {a}");
    println!("ULID b:     {b} (monotonic: {})", b > a);

    let gen = Snowflake::new(1);
    let sf = gen.next_id();
    let (ts_offset, worker, seq) = Snowflake::parts(sf);
    println!(
        "Snowflake:  {sf}  (ts+epoch={}, worker={worker}, seq={seq})",
        ts_offset + gen.epoch_ms()
    );

    println!("NanoID 21:  {}", nanoid::generate());
    println!("NanoID 8:   {}", nanoid::with_length(8));

    assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
    assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
}

pub fn v7() -> Self

Construct a v7 (time-ordered) UUID per RFC 9562 §5.7.

48-bit big-endian millisecond timestamp prefix, 74 random bits, with the version nibble set to 0111 and the RFC 4122 variant bits. Two v7 IDs generated in different milliseconds compare in timestamp order byte-wise.

Example

use id_forge::uuid::Uuid;

let id = Uuid::v7();
assert_eq!(id.version(), 7);

Examples found in repository

examples/basic.rs (line 10)

fn main() {
    let v4 = Uuid::v4();
    println!("UUID v4:    {v4} (version={})", v4.version());
    println!("UUID v7:    {}", Uuid::v7());
    println!("UUID nil:   {}", Uuid::nil());

    let a = Ulid::new();
    let b = Ulid::new();
    println!("ULID a:     {a}");
    println!("ULID b:     {b} (monotonic: {})", b > a);

    let gen = Snowflake::new(1);
    let sf = gen.next_id();
    let (ts_offset, worker, seq) = Snowflake::parts(sf);
    println!(
        "Snowflake:  {sf}  (ts+epoch={}, worker={worker}, seq={seq})",
        ts_offset + gen.epoch_ms()
    );

    println!("NanoID 21:  {}", nanoid::generate());
    println!("NanoID 8:   {}", nanoid::with_length(8));

    assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
    assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
}

pub const fn from_bytes(bytes: &[u8; 16]) -> Self

Wrap a 16-byte big-endian representation.

The bytes are taken as-is; no version or variant bits are touched. Use this to round-trip an externally generated UUID or to reconstruct one from storage.

Example

use id_forge::uuid::Uuid;

let id = Uuid::v4();
let copy = Uuid::from_bytes(id.as_bytes());
assert_eq!(id, copy);

pub const fn as_bytes(&self) -> &[u8; 16]

Return the raw 16-byte big-endian representation.

pub const fn version(&self) -> u8

Return the version nibble (the high 4 bits of byte 6).

4 for v4, 7 for v7, 0 for Uuid::nil, 15 for Uuid::max.

Examples found in repository

examples/basic.rs (line 9)

fn main() {
    let v4 = Uuid::v4();
    println!("UUID v4:    {v4} (version={})", v4.version());
    println!("UUID v7:    {}", Uuid::v7());
    println!("UUID nil:   {}", Uuid::nil());

    let a = Ulid::new();
    let b = Ulid::new();
    println!("ULID a:     {a}");
    println!("ULID b:     {b} (monotonic: {})", b > a);

    let gen = Snowflake::new(1);
    let sf = gen.next_id();
    let (ts_offset, worker, seq) = Snowflake::parts(sf);
    println!(
        "Snowflake:  {sf}  (ts+epoch={}, worker={worker}, seq={seq})",
        ts_offset + gen.epoch_ms()
    );

    println!("NanoID 21:  {}", nanoid::generate());
    println!("NanoID 8:   {}", nanoid::with_length(8));

    assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
    assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
}

pub fn parse_str(input: &str) -> Result<Self, ParseError>

Parse a UUID from its canonical 36-character hyphenated form (e.g. f47ac10b-58cc-4372-a567-0e02b2c3d479).

Parsing is case-insensitive. Returns ParseError if the input is not exactly 36 characters, has hyphens in the wrong positions, or contains a non-hex digit.

Example

use id_forge::uuid::Uuid;

let id = Uuid::parse_str("f47ac10b-58cc-4372-a567-0e02b2c3d479").unwrap();
assert_eq!(id.to_string(), "f47ac10b-58cc-4372-a567-0e02b2c3d479");

Examples found in repository

examples/basic.rs (line 29)

fn main() {
    let v4 = Uuid::v4();
    println!("UUID v4:    {v4} (version={})", v4.version());
    println!("UUID v7:    {}", Uuid::v7());
    println!("UUID nil:   {}", Uuid::nil());

    let a = Ulid::new();
    let b = Ulid::new();
    println!("ULID a:     {a}");
    println!("ULID b:     {b} (monotonic: {})", b > a);

    let gen = Snowflake::new(1);
    let sf = gen.next_id();
    let (ts_offset, worker, seq) = Snowflake::parts(sf);
    println!(
        "Snowflake:  {sf}  (ts+epoch={}, worker={worker}, seq={seq})",
        ts_offset + gen.epoch_ms()
    );

    println!("NanoID 21:  {}", nanoid::generate());
    println!("NanoID 8:   {}", nanoid::with_length(8));

    assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
    assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
}

Trait Implementations

impl Clone for Uuid

fn clone(&self) -> Uuid

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Uuid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Uuid

fn default() -> Self

Returns the “default value” for a type.

impl Display for Uuid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for Uuid

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Uuid

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Uuid

fn cmp(&self, other: &Uuid) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Uuid

fn eq(&self, other: &Uuid) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Uuid

fn partial_cmp(&self, other: &Uuid) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Uuid

impl Eq for Uuid

impl StructuralPartialEq for Uuid