1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

//! A Rust implementation of the proposed UUID Version 7
//!
//! ```rust
//! let uuid = uuid7::uuid7();
//! println!("{}", uuid); // e.g., "01809424-3e59-7c05-9219-566f82fff672"
//! println!("{:?}", uuid.as_bytes()); // as 16-byte big-endian array
//!
//! let uuid_string: String = uuid7::uuid7().to_string();
//! ```
//!
//! See [draft-ietf-uuidrev-rfc4122bis-11](https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-11.html).
//!
//! # Field and bit layout
//!
//! This implementation produces identifiers with the following bit layout:
//!
//! ```text
//!  0                   1                   2                   3
//!  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
//! +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
//! |                          unix_ts_ms                           |
//! +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
//! |          unix_ts_ms           |  ver  |        counter        |
//! +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
//! |var|                        counter                            |
//! +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
//! |                             rand                              |
//! +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
//! ```
//!
//! Where:
//!
//! - The 48-bit `unix_ts_ms` field is dedicated to the Unix timestamp in
//!   milliseconds.
//! - The 4-bit `ver` field is set at `0111`.
//! - The 42-bit `counter` field accommodates a counter that ensures the increasing
//!   order of IDs generated within a millisecond. The counter is incremented by one
//!   for each new ID and is reset to a random number when the `unix_ts_ms` changes.
//! - The 2-bit `var` field is set at `10`.
//! - The remaining 32 `rand` bits are filled with a cryptographically strong random
//!   number.
//!
//! The 42-bit `counter` is sufficiently large, so you do not usually need to worry
//! about overflow, but in an extremely rare circumstance where it overflows, this
//! library increments the `unix_ts_ms` field to continue instant monotonic
//! generation. As a result, the `unix_ts_ms` may have a greater value than that of
//! the system's real-time clock.
//!
//! UUIDv7, by design, relies on the system clock to guarantee the monotonically
//! increasing order of generated IDs. A generator may not be able to produce a
//! monotonic sequence if the system clock goes backwards. This library ignores a
//! clock rollback and reuses the previous `unix_ts_ms` unless the clock rollback is
//! considered significant (by default, more than ten seconds). If such a
//! significant rollback takes place, this library resets the generator by default
//! and thus breaks the increasing order of generated IDs.
//!
//! # Crate features
//!
//! Default features:
//!
//! - `std` integrates the library with, among others, the system clock to draw
//!   current timestamps. Without `std`, this crate provides limited functionality
//!   available under `no_std` environments.
//! - `global_gen` (implies `std`) enables the primary [`uuid7()`] function and the
//!   process-wide global generator under the hood.
//!
//! Optional features:
//!
//! - `serde` enables the serialization and deserialization of [`Uuid`] objects.
//! - `uuid` (together with `global_gen`) enables the [`new_v7()`] function that
//!   returns the popular [uuid](https://crates.io/crates/uuid) crate's [`Uuid`](uuid::Uuid)
//!   objects.
//!
//! # Other functionality
//!
//! This library also supports the generation of UUID version 4:
//!
//! ```rust
//! let uuid = uuid7::uuid4();
//! println!("{}", uuid); // e.g., "2ca4b2ce-6c13-40d4-bccf-37d222820f6f"
//! ```
//!
//! [`V7Generator`] provides an interface that allows finer control over the various
//! aspects of the UUIDv7 generation:
//!
//! ```rust
//! use uuid7::V7Generator;
//!
//! let mut g = V7Generator::new(rand::rngs::OsRng);
//! let custom_unix_ts_ms = 0x0123_4567_8901u64;
//! let x = g.generate_or_reset_core(custom_unix_ts_ms, 10_000);
//! println!("{}", x);
//!
//! let y = g
//!     .generate_or_abort_core(custom_unix_ts_ms, 10_000)
//!     .expect("clock went backwards by more than 10_000 milliseconds");
//! println!("{}", y);
//! ```

#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(docsrs, feature(doc_cfg))]

mod id;
pub use id::{ParseError, Uuid, Variant};

mod gen7;
pub use gen7::V7Generator;

mod global_gen;
#[cfg(feature = "global_gen")]
pub use global_gen::{uuid4, uuid7};

/// Generates a UUIDv7 and returns it as an instance of [`uuid::Uuid`].
#[cfg(all(feature = "global_gen", feature = "uuid"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "global_gen", feature = "uuid"))))]
pub fn new_v7() -> uuid::Uuid {
    uuid7().into()
}