pub struct Uuid(/* private fields */);uuid only.Expand description
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§
Source§impl Uuid
impl Uuid
Sourcepub const fn nil() -> Self
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?
7fn main() {
8 let v4 = Uuid::v4();
9 println!("UUID v4: {v4} (version={})", v4.version());
10 println!("UUID v7: {}", Uuid::v7());
11 println!("UUID nil: {}", Uuid::nil());
12
13 let a = Ulid::new();
14 let b = Ulid::new();
15 println!("ULID a: {a}");
16 println!("ULID b: {b} (monotonic: {})", b > a);
17
18 let gen = Snowflake::new(1);
19 let sf = gen.next_id();
20 let (ts_offset, worker, seq) = Snowflake::parts(sf);
21 println!(
22 "Snowflake: {sf} (ts+epoch={}, worker={worker}, seq={seq})",
23 ts_offset + gen.epoch_ms()
24 );
25
26 println!("NanoID 21: {}", nanoid::generate());
27 println!("NanoID 8: {}", nanoid::with_length(8));
28
29 assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
30 assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
31}More examples
13fn main() {
14 println!("== UUID v4 ==");
15
16 let a = Uuid::v4();
17 let b = Uuid::v4();
18 println!("a = {a}");
19 println!("b = {b}");
20 println!("a == b = {}", a == b);
21 println!("a.version() = {}", a.version());
22
23 println!("\n== Nil and Max ==");
24 println!("nil = {}", Uuid::nil());
25 println!("max = {}", Uuid::max());
26
27 println!("\n== parse_str round-trip ==");
28 let canonical = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
29 let parsed = Uuid::parse_str(canonical).expect("canonical UUID parses");
30 println!("parse(\"{canonical}\") = {parsed}");
31 println!("round-trip ok = {}", parsed.to_string() == canonical);
32
33 println!("\n== Case-insensitive parse ==");
34 let upper = "F47AC10B-58CC-4372-A567-0E02B2C3D479";
35 let lower_round = Uuid::parse_str(upper).unwrap();
36 println!("upper input -> {lower_round} (Display is always lowercase)");
37
38 println!("\n== ParseError variants ==");
39 show_err("too short", Uuid::parse_str("abc"));
40 show_err(
41 "missing hyphen",
42 Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
43 );
44 show_err(
45 "non-hex digit",
46 Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
47 );
48
49 println!("\n== Byte storage round-trip ==");
50 let id = Uuid::v4();
51 let bytes: [u8; 16] = *id.as_bytes();
52 let restored = Uuid::from_bytes(&bytes);
53 println!("id = {id}");
54 println!("restored = {restored}");
55 println!("equal = {}", id == restored);
56}Sourcepub const fn max() -> Self
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");Examples found in repository?
13fn main() {
14 println!("== UUID v4 ==");
15
16 let a = Uuid::v4();
17 let b = Uuid::v4();
18 println!("a = {a}");
19 println!("b = {b}");
20 println!("a == b = {}", a == b);
21 println!("a.version() = {}", a.version());
22
23 println!("\n== Nil and Max ==");
24 println!("nil = {}", Uuid::nil());
25 println!("max = {}", Uuid::max());
26
27 println!("\n== parse_str round-trip ==");
28 let canonical = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
29 let parsed = Uuid::parse_str(canonical).expect("canonical UUID parses");
30 println!("parse(\"{canonical}\") = {parsed}");
31 println!("round-trip ok = {}", parsed.to_string() == canonical);
32
33 println!("\n== Case-insensitive parse ==");
34 let upper = "F47AC10B-58CC-4372-A567-0E02B2C3D479";
35 let lower_round = Uuid::parse_str(upper).unwrap();
36 println!("upper input -> {lower_round} (Display is always lowercase)");
37
38 println!("\n== ParseError variants ==");
39 show_err("too short", Uuid::parse_str("abc"));
40 show_err(
41 "missing hyphen",
42 Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
43 );
44 show_err(
45 "non-hex digit",
46 Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
47 );
48
49 println!("\n== Byte storage round-trip ==");
50 let id = Uuid::v4();
51 let bytes: [u8; 16] = *id.as_bytes();
52 let restored = Uuid::from_bytes(&bytes);
53 println!("id = {id}");
54 println!("restored = {restored}");
55 println!("equal = {}", id == restored);
56}Sourcepub fn v4() -> Self
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?
7fn main() {
8 let v4 = Uuid::v4();
9 println!("UUID v4: {v4} (version={})", v4.version());
10 println!("UUID v7: {}", Uuid::v7());
11 println!("UUID nil: {}", Uuid::nil());
12
13 let a = Ulid::new();
14 let b = Ulid::new();
15 println!("ULID a: {a}");
16 println!("ULID b: {b} (monotonic: {})", b > a);
17
18 let gen = Snowflake::new(1);
19 let sf = gen.next_id();
20 let (ts_offset, worker, seq) = Snowflake::parts(sf);
21 println!(
22 "Snowflake: {sf} (ts+epoch={}, worker={worker}, seq={seq})",
23 ts_offset + gen.epoch_ms()
24 );
25
26 println!("NanoID 21: {}", nanoid::generate());
27 println!("NanoID 8: {}", nanoid::with_length(8));
28
29 assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
30 assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
31}More examples
13fn main() {
14 println!("== UUID v4 ==");
15
16 let a = Uuid::v4();
17 let b = Uuid::v4();
18 println!("a = {a}");
19 println!("b = {b}");
20 println!("a == b = {}", a == b);
21 println!("a.version() = {}", a.version());
22
23 println!("\n== Nil and Max ==");
24 println!("nil = {}", Uuid::nil());
25 println!("max = {}", Uuid::max());
26
27 println!("\n== parse_str round-trip ==");
28 let canonical = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
29 let parsed = Uuid::parse_str(canonical).expect("canonical UUID parses");
30 println!("parse(\"{canonical}\") = {parsed}");
31 println!("round-trip ok = {}", parsed.to_string() == canonical);
32
33 println!("\n== Case-insensitive parse ==");
34 let upper = "F47AC10B-58CC-4372-A567-0E02B2C3D479";
35 let lower_round = Uuid::parse_str(upper).unwrap();
36 println!("upper input -> {lower_round} (Display is always lowercase)");
37
38 println!("\n== ParseError variants ==");
39 show_err("too short", Uuid::parse_str("abc"));
40 show_err(
41 "missing hyphen",
42 Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
43 );
44 show_err(
45 "non-hex digit",
46 Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
47 );
48
49 println!("\n== Byte storage round-trip ==");
50 let id = Uuid::v4();
51 let bytes: [u8; 16] = *id.as_bytes();
52 let restored = Uuid::from_bytes(&bytes);
53 println!("id = {id}");
54 println!("restored = {restored}");
55 println!("equal = {}", id == restored);
56}Sourcepub fn v7() -> Self
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?
7fn main() {
8 let v4 = Uuid::v4();
9 println!("UUID v4: {v4} (version={})", v4.version());
10 println!("UUID v7: {}", Uuid::v7());
11 println!("UUID nil: {}", Uuid::nil());
12
13 let a = Ulid::new();
14 let b = Ulid::new();
15 println!("ULID a: {a}");
16 println!("ULID b: {b} (monotonic: {})", b > a);
17
18 let gen = Snowflake::new(1);
19 let sf = gen.next_id();
20 let (ts_offset, worker, seq) = Snowflake::parts(sf);
21 println!(
22 "Snowflake: {sf} (ts+epoch={}, worker={worker}, seq={seq})",
23 ts_offset + gen.epoch_ms()
24 );
25
26 println!("NanoID 21: {}", nanoid::generate());
27 println!("NanoID 8: {}", nanoid::with_length(8));
28
29 assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
30 assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
31}More examples
14fn main() {
15 println!("== UUID v7 time-ordered IDs ==");
16
17 let mut ids = Vec::new();
18 for i in 0..5 {
19 let id = Uuid::v7();
20 println!("#{i} {id}");
21 ids.push(id);
22 sleep(Duration::from_millis(2));
23 }
24
25 println!("\n== Byte-wise sort matches creation order ==");
26 let mut sorted = ids.clone();
27 sorted.sort();
28 println!("same order = {}", sorted == ids);
29
30 println!("\n== Version field ==");
31 println!("first.version() = {}", ids[0].version());
32
33 println!("\n== As a database primary key ==");
34 // v7 IDs cluster recent inserts in B-tree leaves — better cache
35 // locality than v4 for time-windowed queries.
36 let rows: Vec<(Uuid, &str)> = vec![
37 (Uuid::v7(), "alice signed up"),
38 (Uuid::v7(), "bob signed up"),
39 (Uuid::v7(), "carol signed up"),
40 ];
41 println!("Insert order (recent rows live near the tip of the index):");
42 for (id, evt) in &rows {
43 println!(" {id} {evt}");
44 }
45}Sourcepub const fn from_bytes(bytes: &[u8; 16]) -> Self
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);Examples found in repository?
13fn main() {
14 println!("== UUID v4 ==");
15
16 let a = Uuid::v4();
17 let b = Uuid::v4();
18 println!("a = {a}");
19 println!("b = {b}");
20 println!("a == b = {}", a == b);
21 println!("a.version() = {}", a.version());
22
23 println!("\n== Nil and Max ==");
24 println!("nil = {}", Uuid::nil());
25 println!("max = {}", Uuid::max());
26
27 println!("\n== parse_str round-trip ==");
28 let canonical = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
29 let parsed = Uuid::parse_str(canonical).expect("canonical UUID parses");
30 println!("parse(\"{canonical}\") = {parsed}");
31 println!("round-trip ok = {}", parsed.to_string() == canonical);
32
33 println!("\n== Case-insensitive parse ==");
34 let upper = "F47AC10B-58CC-4372-A567-0E02B2C3D479";
35 let lower_round = Uuid::parse_str(upper).unwrap();
36 println!("upper input -> {lower_round} (Display is always lowercase)");
37
38 println!("\n== ParseError variants ==");
39 show_err("too short", Uuid::parse_str("abc"));
40 show_err(
41 "missing hyphen",
42 Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
43 );
44 show_err(
45 "non-hex digit",
46 Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
47 );
48
49 println!("\n== Byte storage round-trip ==");
50 let id = Uuid::v4();
51 let bytes: [u8; 16] = *id.as_bytes();
52 let restored = Uuid::from_bytes(&bytes);
53 println!("id = {id}");
54 println!("restored = {restored}");
55 println!("equal = {}", id == restored);
56}Sourcepub const fn as_bytes(&self) -> &[u8; 16]
pub const fn as_bytes(&self) -> &[u8; 16]
Return the raw 16-byte big-endian representation.
§Example
use id_forge::uuid::Uuid;
let id = Uuid::nil();
assert_eq!(id.as_bytes(), &[0u8; 16]);Examples found in repository?
13fn main() {
14 println!("== UUID v4 ==");
15
16 let a = Uuid::v4();
17 let b = Uuid::v4();
18 println!("a = {a}");
19 println!("b = {b}");
20 println!("a == b = {}", a == b);
21 println!("a.version() = {}", a.version());
22
23 println!("\n== Nil and Max ==");
24 println!("nil = {}", Uuid::nil());
25 println!("max = {}", Uuid::max());
26
27 println!("\n== parse_str round-trip ==");
28 let canonical = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
29 let parsed = Uuid::parse_str(canonical).expect("canonical UUID parses");
30 println!("parse(\"{canonical}\") = {parsed}");
31 println!("round-trip ok = {}", parsed.to_string() == canonical);
32
33 println!("\n== Case-insensitive parse ==");
34 let upper = "F47AC10B-58CC-4372-A567-0E02B2C3D479";
35 let lower_round = Uuid::parse_str(upper).unwrap();
36 println!("upper input -> {lower_round} (Display is always lowercase)");
37
38 println!("\n== ParseError variants ==");
39 show_err("too short", Uuid::parse_str("abc"));
40 show_err(
41 "missing hyphen",
42 Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
43 );
44 show_err(
45 "non-hex digit",
46 Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
47 );
48
49 println!("\n== Byte storage round-trip ==");
50 let id = Uuid::v4();
51 let bytes: [u8; 16] = *id.as_bytes();
52 let restored = Uuid::from_bytes(&bytes);
53 println!("id = {id}");
54 println!("restored = {restored}");
55 println!("equal = {}", id == restored);
56}Sourcepub const fn version(&self) -> u8
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.
§Example
use id_forge::uuid::Uuid;
assert_eq!(Uuid::v4().version(), 4);
assert_eq!(Uuid::v7().version(), 7);
assert_eq!(Uuid::nil().version(), 0);Examples found in repository?
7fn main() {
8 let v4 = Uuid::v4();
9 println!("UUID v4: {v4} (version={})", v4.version());
10 println!("UUID v7: {}", Uuid::v7());
11 println!("UUID nil: {}", Uuid::nil());
12
13 let a = Ulid::new();
14 let b = Ulid::new();
15 println!("ULID a: {a}");
16 println!("ULID b: {b} (monotonic: {})", b > a);
17
18 let gen = Snowflake::new(1);
19 let sf = gen.next_id();
20 let (ts_offset, worker, seq) = Snowflake::parts(sf);
21 println!(
22 "Snowflake: {sf} (ts+epoch={}, worker={worker}, seq={seq})",
23 ts_offset + gen.epoch_ms()
24 );
25
26 println!("NanoID 21: {}", nanoid::generate());
27 println!("NanoID 8: {}", nanoid::with_length(8));
28
29 assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
30 assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
31}More examples
14fn main() {
15 println!("== UUID v7 time-ordered IDs ==");
16
17 let mut ids = Vec::new();
18 for i in 0..5 {
19 let id = Uuid::v7();
20 println!("#{i} {id}");
21 ids.push(id);
22 sleep(Duration::from_millis(2));
23 }
24
25 println!("\n== Byte-wise sort matches creation order ==");
26 let mut sorted = ids.clone();
27 sorted.sort();
28 println!("same order = {}", sorted == ids);
29
30 println!("\n== Version field ==");
31 println!("first.version() = {}", ids[0].version());
32
33 println!("\n== As a database primary key ==");
34 // v7 IDs cluster recent inserts in B-tree leaves — better cache
35 // locality than v4 for time-windowed queries.
36 let rows: Vec<(Uuid, &str)> = vec![
37 (Uuid::v7(), "alice signed up"),
38 (Uuid::v7(), "bob signed up"),
39 (Uuid::v7(), "carol signed up"),
40 ];
41 println!("Insert order (recent rows live near the tip of the index):");
42 for (id, evt) in &rows {
43 println!(" {id} {evt}");
44 }
45}13fn main() {
14 println!("== UUID v4 ==");
15
16 let a = Uuid::v4();
17 let b = Uuid::v4();
18 println!("a = {a}");
19 println!("b = {b}");
20 println!("a == b = {}", a == b);
21 println!("a.version() = {}", a.version());
22
23 println!("\n== Nil and Max ==");
24 println!("nil = {}", Uuid::nil());
25 println!("max = {}", Uuid::max());
26
27 println!("\n== parse_str round-trip ==");
28 let canonical = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
29 let parsed = Uuid::parse_str(canonical).expect("canonical UUID parses");
30 println!("parse(\"{canonical}\") = {parsed}");
31 println!("round-trip ok = {}", parsed.to_string() == canonical);
32
33 println!("\n== Case-insensitive parse ==");
34 let upper = "F47AC10B-58CC-4372-A567-0E02B2C3D479";
35 let lower_round = Uuid::parse_str(upper).unwrap();
36 println!("upper input -> {lower_round} (Display is always lowercase)");
37
38 println!("\n== ParseError variants ==");
39 show_err("too short", Uuid::parse_str("abc"));
40 show_err(
41 "missing hyphen",
42 Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
43 );
44 show_err(
45 "non-hex digit",
46 Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
47 );
48
49 println!("\n== Byte storage round-trip ==");
50 let id = Uuid::v4();
51 let bytes: [u8; 16] = *id.as_bytes();
52 let restored = Uuid::from_bytes(&bytes);
53 println!("id = {id}");
54 println!("restored = {restored}");
55 println!("equal = {}", id == restored);
56}Sourcepub fn parse_str(input: &str) -> Result<Self, ParseError>
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?
7fn main() {
8 let v4 = Uuid::v4();
9 println!("UUID v4: {v4} (version={})", v4.version());
10 println!("UUID v7: {}", Uuid::v7());
11 println!("UUID nil: {}", Uuid::nil());
12
13 let a = Ulid::new();
14 let b = Ulid::new();
15 println!("ULID a: {a}");
16 println!("ULID b: {b} (monotonic: {})", b > a);
17
18 let gen = Snowflake::new(1);
19 let sf = gen.next_id();
20 let (ts_offset, worker, seq) = Snowflake::parts(sf);
21 println!(
22 "Snowflake: {sf} (ts+epoch={}, worker={worker}, seq={seq})",
23 ts_offset + gen.epoch_ms()
24 );
25
26 println!("NanoID 21: {}", nanoid::generate());
27 println!("NanoID 8: {}", nanoid::with_length(8));
28
29 assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
30 assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
31}More examples
13fn main() {
14 println!("== UUID v4 ==");
15
16 let a = Uuid::v4();
17 let b = Uuid::v4();
18 println!("a = {a}");
19 println!("b = {b}");
20 println!("a == b = {}", a == b);
21 println!("a.version() = {}", a.version());
22
23 println!("\n== Nil and Max ==");
24 println!("nil = {}", Uuid::nil());
25 println!("max = {}", Uuid::max());
26
27 println!("\n== parse_str round-trip ==");
28 let canonical = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
29 let parsed = Uuid::parse_str(canonical).expect("canonical UUID parses");
30 println!("parse(\"{canonical}\") = {parsed}");
31 println!("round-trip ok = {}", parsed.to_string() == canonical);
32
33 println!("\n== Case-insensitive parse ==");
34 let upper = "F47AC10B-58CC-4372-A567-0E02B2C3D479";
35 let lower_round = Uuid::parse_str(upper).unwrap();
36 println!("upper input -> {lower_round} (Display is always lowercase)");
37
38 println!("\n== ParseError variants ==");
39 show_err("too short", Uuid::parse_str("abc"));
40 show_err(
41 "missing hyphen",
42 Uuid::parse_str("f47ac10b_58cc-4372-a567-0e02b2c3d479"),
43 );
44 show_err(
45 "non-hex digit",
46 Uuid::parse_str("g47ac10b-58cc-4372-a567-0e02b2c3d479"),
47 );
48
49 println!("\n== Byte storage round-trip ==");
50 let id = Uuid::v4();
51 let bytes: [u8; 16] = *id.as_bytes();
52 let restored = Uuid::from_bytes(&bytes);
53 println!("id = {id}");
54 println!("restored = {restored}");
55 println!("equal = {}", id == restored);
56}