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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
//! A Rust implementation of UUID version 7
//!
//! ```rust
//! # #[cfg(feature = "global_gen")]
//! # {
//! 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 [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562).
//!
//! # 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. (See also [Why so large counter? (42bits)]).
//!
//! 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.
//!
//! [Why so large counter? (42bits)]: https://github.com/LiosK/uuidv7/issues/13#issuecomment-2306922356
//!
//! # Crate features
//!
//! Default features:
//!
//! - `std` enables, among others, the default timestamp source for [`V7Generator`]
//! using [`std::time`]. Without `std`, users must provide their own time source
//! implementing the [`TimeSource`](generator::TimeSource) trait.
//! - `global_gen` (implies `std`) provides the process-wide default UUIDv7
//! generator and enables the primary [`uuid7()`] function.
//! - `rand08`: See below.
//!
//! Optional features:
//!
//! - `serde` enables serialization/deserialization of [`Uuid`] via serde.
//! - `rand010` enables an adapter for `rand::RngCore` to use `rand` (v0.10) and any
//! other conforming random number generators with [`V7Generator`].
//! - `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.
//!
//! Deprecated optional features:
//!
//! - `rand09` enables an adapter for `rand::RngCore` to use `rand` (v0.9) and any
//! other conforming random number generators with [`V7Generator`].
//! - `rand08` enables an adapter for `rand::RngCore` to use `rand` (v0.8) and any
//! other conforming random number generators with [`V7Generator`]. This feature is
//! deprecated and for backward compatibility only, but it is always enabled and
//! cannot be turned off for historical reasons.
//!
//! # Other functionality
//!
//! This library also supports the generation of UUID version 4:
//!
//! ```rust
//! # #[cfg(feature = "global_gen")]
//! # {
//! 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
//! # #[cfg(feature = "rand010")]
//! # {
//! use uuid7::V7Generator;
//!
//! let mut g = V7Generator::with_rand010(rand::rng());
//! let custom_unix_ts_ms = 0x0123_4567_8901u64;
//! let x = g.generate_or_reset_with_ts(custom_unix_ts_ms);
//! println!("{}", x);
//!
//! g.set_rollback_allowance(5_000);
//! let y = g
//! .generate_or_abort_with_ts(custom_unix_ts_ms)
//! .expect("clock went backwards by more than 5_000 milliseconds");
//! println!("{}", y);
//! # }
//! ```
pub use Uuid;
pub use ;
pub use V7Generator;
pub use ;
/// Generates a UUIDv7 and returns it as an instance of [`uuid::Uuid`].