BlackEducation/blackwriter-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
blackwriter-server/doc/uuid.md
PIVODEVAT 059fbda921 init
2025-12-13 22:28:05 +03:00

2559 lines
56 KiB
Markdown
Raw Permalink Blame History

# Crate Documentation
**Version:** 1.19.0
**Format Version:** 57
# Module `uuid`
Generate and parse universally unique identifiers (UUIDs).
Here's an example of a UUID:
```text
67e55044-10b1-426f-9247-bb680e5fe0c8
```
A UUID is a unique 128-bit value, stored as 16 octets, and regularly
formatted as a hex string in five groups. UUIDs are used to assign unique
identifiers to entities without requiring a central allocating authority.
They are particularly useful in distributed systems, though can be used in
disparate areas, such as databases and network protocols. Typically a UUID
is displayed in a readable string form as a sequence of hexadecimal digits,
separated into groups by hyphens.
The uniqueness property is not strictly guaranteed, however for all
practical purposes, it can be assumed that an unintentional collision would
be extremely unlikely.
UUIDs have a number of standardized encodings that are specified in [RFC 9562](https://www.ietf.org/rfc/rfc9562.html).
# Getting started
Add the following to your `Cargo.toml`:
```toml
[dependencies.uuid]
version = "1.19.0"
# Lets you generate random UUIDs
features = [
"v4",
]
```
When you want a UUID, you can generate one:
```
# fn main() {
# #[cfg(feature = "v4")]
# {
use uuid::Uuid;
let id = Uuid::new_v4();
# }
# }
```
If you have a UUID value, you can use its string literal form inline:
```
use uuid::{uuid, Uuid};
const ID: Uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");
```
# Working with different UUID versions
This library supports all standardized methods for generating UUIDs through individual Cargo features.
By default, this crate depends on nothing but the Rust standard library and can parse and format
UUIDs, but cannot generate them. Depending on the kind of UUID you'd like to work with, there
are Cargo features that enable generating them:
* `v1` - Version 1 UUIDs using a timestamp and monotonic counter.
* `v3` - Version 3 UUIDs based on the MD5 hash of some data.
* `v4` - Version 4 UUIDs with random data.
* `v5` - Version 5 UUIDs based on the SHA1 hash of some data.
* `v6` - Version 6 UUIDs using a timestamp and monotonic counter.
* `v7` - Version 7 UUIDs using a Unix timestamp.
* `v8` - Version 8 UUIDs using user-defined data.
This library also includes a [`Builder`] type that can be used to help construct UUIDs of any
version without any additional dependencies or features. It's a lower-level API than [`Uuid`]
that can be used when you need control over implicit requirements on things like a source
of randomness.
## Which UUID version should I use?
If you just want to generate unique identifiers then consider version 4 (`v4`) UUIDs. If you want
to use UUIDs as database keys or need to sort them then consider version 7 (`v7`) UUIDs.
Other versions should generally be avoided unless there's an existing need for them.
Some UUID versions supersede others. Prefer version 6 over version 1 and version 5 over version 3.
# Other features
Other crate features can also be useful beyond the version support:
* `macro-diagnostics` - enhances the diagnostics of `uuid!` macro.
* `serde` - adds the ability to serialize and deserialize a UUID using
`serde`.
* `borsh` - adds the ability to serialize and deserialize a UUID using
`borsh`.
* `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid` for
fuzzing.
* `fast-rng` - uses a faster algorithm for generating random UUIDs when available.
This feature requires more dependencies to compile, but is just as suitable for
UUIDs as the default algorithm.
* `rng-rand` - forces `rand` as the backend for randomness.
* `rng-getrandom` - forces `getrandom` as the backend for randomness.
* `bytemuck` - adds a `Pod` trait implementation to `Uuid` for byte manipulation
# Unstable features
Some features are unstable. They may be incomplete or depend on other
unstable libraries. These include:
* `zerocopy` - adds support for zero-copy deserialization using the
`zerocopy` library.
Unstable features may break between minor releases.
To allow unstable features, you'll need to enable the Cargo feature as
normal, but also pass an additional flag through your environment to opt-in
to unstable `uuid` features:
```text
RUSTFLAGS="--cfg uuid_unstable"
```
# Building for other targets
## WebAssembly
For WebAssembly, enable the `js` feature:
```toml
[dependencies.uuid]
version = "1.19.0"
features = [
"v4",
"v7",
"js",
]
```
## Embedded
For embedded targets without the standard library, you'll need to
disable default features when building `uuid`:
```toml
[dependencies.uuid]
version = "1.19.0"
default-features = false
```
Some additional features are supported in no-std environments:
* `v1`, `v3`, `v5`, `v6`, and `v8`.
* `serde`.
If you need to use `v4` or `v7` in a no-std environment, you'll need to
produce random bytes yourself and then pass them to [`Builder::from_random_bytes`]
without enabling the `v4` or `v7` features.
If you're using `getrandom`, you can specify the `rng-getrandom` or `rng-rand`
features of `uuid` and configure `getrandom`'s provider per its docs. `uuid`
may upgrade its version of `getrandom` in minor releases.
# Examples
Parse a UUID given in the simple format and print it as a URN:
```
# use uuid::Uuid;
# fn main() -> Result<(), uuid::Error> {
let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
println!("{}", my_uuid.urn());
# Ok(())
# }
```
Generate a random UUID and print it out in hexadecimal form:
```
// Note that this requires the `v4` feature to be enabled.
# use uuid::Uuid;
# fn main() {
# #[cfg(feature = "v4")] {
let my_uuid = Uuid::new_v4();
println!("{}", my_uuid);
# }
# }
```
# References
* [Wikipedia: Universally Unique Identifier](http://en.wikipedia.org/wiki/Universally_unique_identifier)
* [RFC 9562: Universally Unique IDentifiers (UUID)](https://www.ietf.org/rfc/rfc9562.html).
[`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen
## Modules
## Module `fmt`
Adapters for alternative string formats.
```rust
pub mod fmt { /* ... */ }
```
### Types
#### Struct `Hyphenated`
**Attributes:**
- `Other("#[<cfg_attr_trace>(all(uuid_unstable, feature = \"zerocopy\"),\nderive(zerocopy::IntoBytes, zerocopy::FromBytes, zerocopy::KnownLayout,\nzerocopy::Immutable, zerocopy::Unaligned))]")`
- `Repr(AttributeRepr { kind: Transparent, align: None, packed: None, int: None })`
Format a [`Uuid`] as a hyphenated string, like
`67e55044-10b1-426f-9247-bb680e5fe0c8`.
```rust
pub struct Hyphenated(/* private field */);
```
##### Fields
| Index | Type | Documentation |
|-------|------|---------------|
| 0 | `private` | *Private field* |
##### Implementations
###### Methods
- ```rust
pub const fn from_uuid(uuid: Uuid) -> Self { /* ... */ }
```
Creates a [`Hyphenated`] from a [`Uuid`].
- ```rust
pub fn encode_lower<''buf>(self: &Self, buffer: &''buf mut [u8]) -> &''buf mut str { /* ... */ }
```
Writes the [`Uuid`] as a lower-case hyphenated string to
- ```rust
pub fn encode_upper<''buf>(self: &Self, buffer: &''buf mut [u8]) -> &''buf mut str { /* ... */ }
```
Writes the [`Uuid`] as an upper-case hyphenated string to
- ```rust
pub const fn as_uuid(self: &Self) -> &Uuid { /* ... */ }
```
Get a reference to the underlying [`Uuid`].
- ```rust
pub const fn into_uuid(self: Self) -> Uuid { /* ... */ }
```
Consumes the [`Hyphenated`], returning the underlying [`Uuid`].
###### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **AsRef**
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- ```rust
fn borrow(self: &Self) -> &Uuid { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> Hyphenated { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
```
- **Default**
- ```rust
fn default() -> Hyphenated { /* ... */ }
```
- **Display**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Eq**
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- ```rust
fn from(f: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Hyphenated) -> Self { /* ... */ }
```
- **FromStr**
- ```rust
fn from_str(s: &str) -> Result<Self, <Self as >::Err> { /* ... */ }
```
- **Hash**
- ```rust
fn hash<__H: $crate::hash::Hasher>(self: &Self, state: &mut __H) { /* ... */ }
```
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **LowerHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Ord**
- ```rust
fn cmp(self: &Self, other: &Hyphenated) -> $crate::cmp::Ordering { /* ... */ }
```
- **PartialEq**
- ```rust
fn eq(self: &Self, other: &Hyphenated) -> bool { /* ... */ }
```
- **PartialOrd**
- ```rust
fn partial_cmp(self: &Self, other: &Hyphenated) -> $crate::option::Option<$crate::cmp::Ordering> { /* ... */ }
```
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **Serialize**
- ```rust
fn erased_serialize(self: &Self, serializer: &mut dyn Serializer) -> Result<Ok, Error> { /* ... */ }
```
- ```rust
fn serialize<S: Serializer>(self: &Self, serializer: S) -> Result<<S as >::Ok, <S as >::Error> { /* ... */ }
```
- **StructuralPartialEq**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **ToString**
- ```rust
fn to_string(self: &Self) -> String { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
- **UpperHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
#### Struct `Simple`
**Attributes:**
- `Other("#[<cfg_attr_trace>(all(uuid_unstable, feature = \"zerocopy\"),\nderive(zerocopy::IntoBytes, zerocopy::FromBytes, zerocopy::KnownLayout,\nzerocopy::Immutable, zerocopy::Unaligned))]")`
- `Repr(AttributeRepr { kind: Transparent, align: None, packed: None, int: None })`
Format a [`Uuid`] as a simple string, like
`67e5504410b1426f9247bb680e5fe0c8`.
```rust
pub struct Simple(/* private field */);
```
##### Fields
| Index | Type | Documentation |
|-------|------|---------------|
| 0 | `private` | *Private field* |
##### Implementations
###### Methods
- ```rust
pub const fn from_uuid(uuid: Uuid) -> Self { /* ... */ }
```
Creates a [`Simple`] from a [`Uuid`].
- ```rust
pub fn encode_lower<''buf>(self: &Self, buffer: &''buf mut [u8]) -> &''buf mut str { /* ... */ }
```
Writes the [`Uuid`] as a lower-case simple string to `buffer`,
- ```rust
pub fn encode_upper<''buf>(self: &Self, buffer: &''buf mut [u8]) -> &''buf mut str { /* ... */ }
```
Writes the [`Uuid`] as an upper-case simple string to `buffer`,
- ```rust
pub const fn as_uuid(self: &Self) -> &Uuid { /* ... */ }
```
Get a reference to the underlying [`Uuid`].
- ```rust
pub const fn into_uuid(self: Self) -> Uuid { /* ... */ }
```
Consumes the [`Simple`], returning the underlying [`Uuid`].
###### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **AsRef**
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- ```rust
fn borrow(self: &Self) -> &Uuid { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> Simple { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
```
- **Default**
- ```rust
fn default() -> Simple { /* ... */ }
```
- **Display**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Eq**
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- ```rust
fn from(f: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Simple) -> Self { /* ... */ }
```
- **FromStr**
- ```rust
fn from_str(s: &str) -> Result<Self, <Self as >::Err> { /* ... */ }
```
- **Hash**
- ```rust
fn hash<__H: $crate::hash::Hasher>(self: &Self, state: &mut __H) { /* ... */ }
```
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **LowerHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Ord**
- ```rust
fn cmp(self: &Self, other: &Simple) -> $crate::cmp::Ordering { /* ... */ }
```
- **PartialEq**
- ```rust
fn eq(self: &Self, other: &Simple) -> bool { /* ... */ }
```
- **PartialOrd**
- ```rust
fn partial_cmp(self: &Self, other: &Simple) -> $crate::option::Option<$crate::cmp::Ordering> { /* ... */ }
```
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **Serialize**
- ```rust
fn erased_serialize(self: &Self, serializer: &mut dyn Serializer) -> Result<Ok, Error> { /* ... */ }
```
- ```rust
fn serialize<S: Serializer>(self: &Self, serializer: S) -> Result<<S as >::Ok, <S as >::Error> { /* ... */ }
```
- **StructuralPartialEq**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **ToString**
- ```rust
fn to_string(self: &Self) -> String { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
- **UpperHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
#### Struct `Urn`
**Attributes:**
- `Other("#[<cfg_attr_trace>(all(uuid_unstable, feature = \"zerocopy\"),\nderive(zerocopy::IntoBytes, zerocopy::FromBytes, zerocopy::KnownLayout,\nzerocopy::Immutable, zerocopy::Unaligned))]")`
- `Repr(AttributeRepr { kind: Transparent, align: None, packed: None, int: None })`
Format a [`Uuid`] as a URN string, like
`urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8`.
```rust
pub struct Urn(/* private field */);
```
##### Fields
| Index | Type | Documentation |
|-------|------|---------------|
| 0 | `private` | *Private field* |
##### Implementations
###### Methods
- ```rust
pub const fn from_uuid(uuid: Uuid) -> Self { /* ... */ }
```
Creates a [`Urn`] from a [`Uuid`].
- ```rust
pub fn encode_lower<''buf>(self: &Self, buffer: &''buf mut [u8]) -> &''buf mut str { /* ... */ }
```
Writes the [`Uuid`] as a lower-case URN string to
- ```rust
pub fn encode_upper<''buf>(self: &Self, buffer: &''buf mut [u8]) -> &''buf mut str { /* ... */ }
```
Writes the [`Uuid`] as an upper-case URN string to
- ```rust
pub const fn as_uuid(self: &Self) -> &Uuid { /* ... */ }
```
Get a reference to the underlying [`Uuid`].
- ```rust
pub const fn into_uuid(self: Self) -> Uuid { /* ... */ }
```
Consumes the [`Urn`], returning the underlying [`Uuid`].
###### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **AsRef**
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- ```rust
fn borrow(self: &Self) -> &Uuid { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> Urn { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
```
- **Default**
- ```rust
fn default() -> Urn { /* ... */ }
```
- **Display**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Eq**
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- ```rust
fn from(f: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Urn) -> Self { /* ... */ }
```
- **FromStr**
- ```rust
fn from_str(s: &str) -> Result<Self, <Self as >::Err> { /* ... */ }
```
- **Hash**
- ```rust
fn hash<__H: $crate::hash::Hasher>(self: &Self, state: &mut __H) { /* ... */ }
```
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **LowerHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Ord**
- ```rust
fn cmp(self: &Self, other: &Urn) -> $crate::cmp::Ordering { /* ... */ }
```
- **PartialEq**
- ```rust
fn eq(self: &Self, other: &Urn) -> bool { /* ... */ }
```
- **PartialOrd**
- ```rust
fn partial_cmp(self: &Self, other: &Urn) -> $crate::option::Option<$crate::cmp::Ordering> { /* ... */ }
```
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **Serialize**
- ```rust
fn erased_serialize(self: &Self, serializer: &mut dyn Serializer) -> Result<Ok, Error> { /* ... */ }
```
- ```rust
fn serialize<S: Serializer>(self: &Self, serializer: S) -> Result<<S as >::Ok, <S as >::Error> { /* ... */ }
```
- **StructuralPartialEq**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **ToString**
- ```rust
fn to_string(self: &Self) -> String { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
- **UpperHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
#### Struct `Braced`
**Attributes:**
- `Other("#[<cfg_attr_trace>(all(uuid_unstable, feature = \"zerocopy\"),\nderive(zerocopy::IntoBytes, zerocopy::FromBytes, zerocopy::KnownLayout,\nzerocopy::Immutable, zerocopy::Unaligned))]")`
- `Repr(AttributeRepr { kind: Transparent, align: None, packed: None, int: None })`
Format a [`Uuid`] as a braced hyphenated string, like
`{67e55044-10b1-426f-9247-bb680e5fe0c8}`.
```rust
pub struct Braced(/* private field */);
```
##### Fields
| Index | Type | Documentation |
|-------|------|---------------|
| 0 | `private` | *Private field* |
##### Implementations
###### Methods
- ```rust
pub const fn from_uuid(uuid: Uuid) -> Self { /* ... */ }
```
Creates a [`Braced`] from a [`Uuid`].
- ```rust
pub fn encode_lower<''buf>(self: &Self, buffer: &''buf mut [u8]) -> &''buf mut str { /* ... */ }
```
Writes the [`Uuid`] as a lower-case hyphenated string surrounded by
- ```rust
pub fn encode_upper<''buf>(self: &Self, buffer: &''buf mut [u8]) -> &''buf mut str { /* ... */ }
```
Writes the [`Uuid`] as an upper-case hyphenated string surrounded by
- ```rust
pub const fn as_uuid(self: &Self) -> &Uuid { /* ... */ }
```
Get a reference to the underlying [`Uuid`].
- ```rust
pub const fn into_uuid(self: Self) -> Uuid { /* ... */ }
```
Consumes the [`Braced`], returning the underlying [`Uuid`].
###### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **AsRef**
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- ```rust
fn borrow(self: &Self) -> &Uuid { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> Braced { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
```
- **Default**
- ```rust
fn default() -> Braced { /* ... */ }
```
- **Display**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Eq**
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- ```rust
fn from(f: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Braced) -> Self { /* ... */ }
```
- **FromStr**
- ```rust
fn from_str(s: &str) -> Result<Self, <Self as >::Err> { /* ... */ }
```
- **Hash**
- ```rust
fn hash<__H: $crate::hash::Hasher>(self: &Self, state: &mut __H) { /* ... */ }
```
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **LowerHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Ord**
- ```rust
fn cmp(self: &Self, other: &Braced) -> $crate::cmp::Ordering { /* ... */ }
```
- **PartialEq**
- ```rust
fn eq(self: &Self, other: &Braced) -> bool { /* ... */ }
```
- **PartialOrd**
- ```rust
fn partial_cmp(self: &Self, other: &Braced) -> $crate::option::Option<$crate::cmp::Ordering> { /* ... */ }
```
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **Serialize**
- ```rust
fn erased_serialize(self: &Self, serializer: &mut dyn Serializer) -> Result<Ok, Error> { /* ... */ }
```
- ```rust
fn serialize<S: Serializer>(self: &Self, serializer: S) -> Result<<S as >::Ok, <S as >::Error> { /* ... */ }
```
- **StructuralPartialEq**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **ToString**
- ```rust
fn to_string(self: &Self) -> String { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
- **UpperHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
## Module `timestamp`
Generating UUIDs from timestamps.
Timestamps are used in a few UUID versions as a source of decentralized
uniqueness (as in versions 1 and 6), and as a way to enable sorting (as
in versions 6 and 7). Timestamps aren't encoded the same way by all UUID
versions so this module provides a single [`Timestamp`] type that can
convert between them.
# Timestamp representations in UUIDs
Versions 1 and 6 UUIDs use a bespoke timestamp that consists of the
number of 100ns ticks since `1582-10-15 00:00:00`, along with
a counter value to avoid duplicates.
Version 7 UUIDs use a more standard timestamp that consists of the
number of millisecond ticks since the Unix epoch (`1970-01-01 00:00:00`).
# References
* [UUID Version 1 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.1)
* [UUID Version 7 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.7)
* [Timestamp Considerations in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.1)
```rust
pub mod timestamp { /* ... */ }
```
### Modules
## Module `context`
Default implementations for the [`ClockSequence`] trait.
```rust
pub mod context { /* ... */ }
```
### Types
#### Struct `NoContext`
An empty counter that will always return the value `0`.
This type can be used when constructing version 7 UUIDs. When used to
construct a version 7 UUID, the entire counter segment of the UUID will be
filled with a random value. This type does not maintain ordering of UUIDs
within a millisecond but is efficient.
This type should not be used when constructing version 1 or version 6 UUIDs.
When used to construct a version 1 or version 6 UUID, the counter
segment will remain zero.
```rust
pub struct NoContext;
```
##### Implementations
###### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **ClockSequence**
- ```rust
fn generate_sequence(self: &Self, _seconds: u64, _nanos: u32) -> <Self as >::Output { /* ... */ }
```
- ```rust
fn usable_bits(self: &Self) -> usize { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> NoContext { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
```
- **Default**
- ```rust
fn default() -> NoContext { /* ... */ }
```
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
### Re-exports
#### Re-export `v1_support::*`
**Attributes:**
- `Other("#[<cfg_trace>(any(feature = \"v1\", feature = \"v6\"))]")`
```rust
pub use v1_support::*;
```
#### Re-export `std_support::*`
**Attributes:**
- `Other("#[<cfg_trace>(feature = \"std\")]")`
```rust
pub use std_support::*;
```
#### Re-export `v7_support::*`
**Attributes:**
- `Other("#[<cfg_trace>(feature = \"v7\")]")`
```rust
pub use v7_support::*;
```
### Types
#### Struct `Timestamp`
A timestamp that can be encoded into a UUID.
This type abstracts the specific encoding, so versions 1, 6, and 7
UUIDs can both be supported through the same type, even
though they have a different representation of a timestamp.
# References
* [Timestamp Considerations in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.1)
* [UUID Generator States in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.3)
```rust
pub struct Timestamp {
// Some fields omitted
}
```
##### Fields
| Name | Type | Documentation |
|------|------|---------------|
| *private fields* | ... | *Some fields have been omitted* |
##### Implementations
###### Methods
- ```rust
pub fn now</* synthetic */ impl Into<u128>: Into<u128>, /* synthetic */ impl ClockSequence<Output = impl Into<u128>>: ClockSequence<Output = impl Into<u128>>>(context: impl ClockSequence<Output = impl Into<u128>>) -> Self { /* ... */ }
```
Get a timestamp representing the current system time and up to a 128-bit counter.
- ```rust
pub const fn from_gregorian(ticks: u64, counter: u16) -> Self { /* ... */ }
```
Construct a `Timestamp` from the number of 100 nanosecond ticks since 00:00:00.00,
- ```rust
pub const fn from_unix_time(seconds: u64, subsec_nanos: u32, counter: u128, usable_counter_bits: u8) -> Self { /* ... */ }
```
Construct a `Timestamp` from a Unix timestamp and up to a 128-bit counter, as used in version 7 UUIDs.
- ```rust
pub fn from_unix</* synthetic */ impl Into<u128>: Into<u128>, /* synthetic */ impl ClockSequence<Output = impl Into<u128>>: ClockSequence<Output = impl Into<u128>>>(context: impl ClockSequence<Output = impl Into<u128>>, seconds: u64, subsec_nanos: u32) -> Self { /* ... */ }
```
Construct a `Timestamp` from a Unix timestamp and up to a 128-bit counter, as used in version 7 UUIDs.
- ```rust
pub const fn to_gregorian(self: &Self) -> (u64, u16) { /* ... */ }
```
Get the value of the timestamp as the number of 100 nanosecond ticks since 00:00:00.00,
- ```rust
pub const fn to_unix(self: &Self) -> (u64, u32) { /* ... */ }
```
Get the value of the timestamp as a Unix timestamp, as used in version 7 UUIDs.
###### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> Timestamp { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
```
- **Eq**
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- ```rust
fn from(ts: Timestamp) -> Self { /* ... */ }
```
- **Hash**
- ```rust
fn hash<__H: $crate::hash::Hasher>(self: &Self, state: &mut __H) { /* ... */ }
```
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **PartialEq**
- ```rust
fn eq(self: &Self, other: &Timestamp) -> bool { /* ... */ }
```
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **StructuralPartialEq**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- ```rust
fn try_from(st: std::time::SystemTime) -> Result<Self, <Self as >::Error> { /* ... */ }
```
Perform the conversion.
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
### Traits
#### Trait `ClockSequence`
A counter that can be used by versions 1 and 6 UUIDs to support
the uniqueness of timestamps.
# References
* [UUID Version 1 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.1)
* [UUID Version 6 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.6)
* [UUID Generator States in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.3)
```rust
pub trait ClockSequence {
/* Associated items */
}
```
##### Required Items
###### Associated Types
- `Output`: The type of sequence returned by this counter.
###### Required Methods
- `generate_sequence`: Get the next value in the sequence to feed into a timestamp.
##### Provided Methods
- ```rust
fn generate_timestamp_sequence(self: &Self, seconds: u64, subsec_nanos: u32) -> (<Self as >::Output, u64, u32) { /* ... */ }
```
Get the next value in the sequence, potentially also adjusting the timestamp.
- ```rust
fn usable_bits(self: &Self) -> usize
where
<Self as >::Output: Sized { /* ... */ }
```
The number of usable bits from the least significant bit in the result of [`ClockSequence::generate_sequence`]
##### Implementations
This trait is implemented for the following types:
- `&T` with <T: ClockSequence + ?Sized>
- `Context`
- `ThreadLocalContext<C>` with <C: ClockSequence + ''static>
- `core::panic::AssertUnwindSafe<C>` with <C: ClockSequence>
- `std::sync::Mutex<C>` with <C: ClockSequence + RefUnwindSafe>
- `ContextV7`
- `NoContext`
### Constants and Statics
#### Constant `UUID_TICKS_BETWEEN_EPOCHS`
The number of 100 nanosecond ticks between the RFC 9562 epoch
(`1582-10-15 00:00:00`) and the Unix epoch (`1970-01-01 00:00:00`).
```rust
pub const UUID_TICKS_BETWEEN_EPOCHS: u64 = 0x01B2_1DD2_1381_4000;
```
## Module `serde`
**Attributes:**
- `Other("#[<cfg_trace>(feature = \"serde\")]")`
Adapters for alternative `serde` formats.
This module contains adapters you can use with [`#[serde(with)]`](https://serde.rs/field-attrs.html#with)
to change the way a [`Uuid`](../struct.Uuid.html) is serialized
and deserialized.
```rust
pub mod serde { /* ... */ }
```
### Re-exports
#### Re-export `braced`
```rust
pub use crate::external::serde_support::braced;
```
#### Re-export `compact`
```rust
pub use crate::external::serde_support::compact;
```
#### Re-export `simple`
```rust
pub use crate::external::serde_support::simple;
```
#### Re-export `urn`
```rust
pub use crate::external::serde_support::urn;
```
## Types
### Type Alias `Bytes`
A 128-bit (16 byte) buffer containing the UUID.
# ABI
The `Bytes` type is always guaranteed to be have the same ABI as [`Uuid`].
```rust
pub type Bytes = [u8; 16];
```
### Enum `Version`
**Attributes:**
- `Repr(AttributeRepr { kind: Rust, align: None, packed: None, int: Some("u8") })`
- `NonExhaustive`
The version of the UUID, denoting the generating algorithm.
# References
* [Version Field in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-4.2)
```rust
pub enum Version {
Nil = 0u8,
Mac = 1,
Dce = 2,
Md5 = 3,
Random = 4,
Sha1 = 5,
SortMac = 6,
SortRand = 7,
Custom = 8,
Max = 0xff,
}
```
#### Variants
##### `Nil`
The "nil" (all zeros) UUID.
Discriminant: `0u8`
Discriminant value: `0`
##### `Mac`
Version 1: Timestamp and node ID.
Discriminant: `1`
Discriminant value: `1`
##### `Dce`
Version 2: DCE Security.
Discriminant: `2`
Discriminant value: `2`
##### `Md5`
Version 3: MD5 hash.
Discriminant: `3`
Discriminant value: `3`
##### `Random`
Version 4: Random.
Discriminant: `4`
Discriminant value: `4`
##### `Sha1`
Version 5: SHA-1 hash.
Discriminant: `5`
Discriminant value: `5`
##### `SortMac`
Version 6: Sortable Timestamp and node ID.
Discriminant: `6`
Discriminant value: `6`
##### `SortRand`
Version 7: Timestamp and random.
Discriminant: `7`
Discriminant value: `7`
##### `Custom`
Version 8: Custom.
Discriminant: `8`
Discriminant value: `8`
##### `Max`
The "max" (all ones) UUID.
Discriminant: `0xff`
Discriminant value: `255`
#### Implementations
##### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> Version { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
```
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **PartialEq**
- ```rust
fn eq(self: &Self, other: &Version) -> bool { /* ... */ }
```
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **StructuralPartialEq**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
### Enum `Variant`
**Attributes:**
- `Repr(AttributeRepr { kind: Rust, align: None, packed: None, int: Some("u8") })`
- `NonExhaustive`
The reserved variants of UUIDs.
# References
* [Variant Field in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-4.1)
```rust
pub enum Variant {
NCS = 0u8,
RFC4122,
Microsoft,
Future,
}
```
#### Variants
##### `NCS`
Reserved by the NCS for backward compatibility.
Discriminant: `0u8`
Discriminant value: `0`
##### `RFC4122`
As described in the RFC 9562 Specification (default).
(for backward compatibility it is not yet renamed)
##### `Microsoft`
Reserved by Microsoft for backward compatibility.
##### `Future`
Reserved for future expansion.
#### Implementations
##### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> Variant { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
```
- **Display**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **PartialEq**
- ```rust
fn eq(self: &Self, other: &Variant) -> bool { /* ... */ }
```
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **StructuralPartialEq**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **ToString**
- ```rust
fn to_string(self: &Self) -> String { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
### Struct `Uuid`
**Attributes:**
- `Other("#[<cfg_attr_trace>(feature = \"borsh\",\nderive(borsh_derive::BorshDeserialize, borsh_derive::BorshSerialize))]")`
- `Other("#[<cfg_attr_trace>(feature = \"bytemuck\",\nderive(bytemuck::Zeroable, bytemuck::Pod, bytemuck::TransparentWrapper))]")`
- `Other("#[<cfg_attr_trace>(all(uuid_unstable, feature = \"zerocopy\"),\nderive(zerocopy::IntoBytes, zerocopy::FromBytes, zerocopy::KnownLayout,\nzerocopy::Immutable, zerocopy::Unaligned))]")`
- `Repr(AttributeRepr { kind: Transparent, align: None, packed: None, int: None })`
A Universally Unique Identifier (UUID).
# Examples
Parse a UUID given in the simple format and print it as a urn:
```
# use uuid::Uuid;
# fn main() -> Result<(), uuid::Error> {
let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
println!("{}", my_uuid.urn());
# Ok(())
# }
```
Create a new random (V4) UUID and print it out in hexadecimal form:
```
// Note that this requires the `v4` feature enabled in the uuid crate.
# use uuid::Uuid;
# fn main() {
# #[cfg(feature = "v4")] {
let my_uuid = Uuid::new_v4();
println!("{}", my_uuid);
# }
# }
```
# Formatting
A UUID can be formatted in one of a few ways:
* [`simple`](#method.simple): `a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8`.
* [`hyphenated`](#method.hyphenated):
`a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8`.
* [`urn`](#method.urn): `urn:uuid:A1A2A3A4-B1B2-C1C2-D1D2-D3D4D5D6D7D8`.
* [`braced`](#method.braced): `{a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8}`.
The default representation when formatting a UUID with `Display` is
hyphenated:
```
# use uuid::Uuid;
# fn main() -> Result<(), uuid::Error> {
let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
assert_eq!(
"a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
my_uuid.to_string(),
);
# Ok(())
# }
```
Other formats can be specified using adapter methods on the UUID:
```
# use uuid::Uuid;
# fn main() -> Result<(), uuid::Error> {
let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
assert_eq!(
"urn:uuid:a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
my_uuid.urn().to_string(),
);
# Ok(())
# }
```
# Endianness
The specification for UUIDs encodes the integer fields that make up the
value in big-endian order. This crate assumes integer inputs are already in
the correct order by default, regardless of the endianness of the
environment. Most methods that accept integers have a `_le` variant (such as
`from_fields_le`) that assumes any integer values will need to have their
bytes flipped, regardless of the endianness of the environment.
Most users won't need to worry about endianness unless they need to operate
on individual fields (such as when converting between Microsoft GUIDs). The
important things to remember are:
- The endianness is in terms of the fields of the UUID, not the environment.
- The endianness is assumed to be big-endian when there's no `_le` suffix
somewhere.
- Byte-flipping in `_le` methods applies to each integer.
- Endianness roundtrips, so if you create a UUID with `from_fields_le`
you'll get the same values back out with `to_fields_le`.
# ABI
The `Uuid` type is always guaranteed to be have the same ABI as [`Bytes`].
```rust
pub struct Uuid(/* private field */);
```
#### Fields
| Index | Type | Documentation |
|-------|------|---------------|
| 0 | `private` | *Private field* |
#### Implementations
##### Methods
- ```rust
pub const fn nil() -> Self { /* ... */ }
```
The 'nil UUID' (all zeros).
- ```rust
pub const fn max() -> Self { /* ... */ }
```
The 'max UUID' (all ones).
- ```rust
pub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Uuid { /* ... */ }
```
Creates a UUID from four field values.
- ```rust
pub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Uuid { /* ... */ }
```
Creates a UUID from four field values in little-endian order.
- ```rust
pub const fn from_u128(v: u128) -> Self { /* ... */ }
```
Creates a UUID from a 128bit value.
- ```rust
pub const fn from_u128_le(v: u128) -> Self { /* ... */ }
```
Creates a UUID from a 128bit value in little-endian order.
- ```rust
pub const fn from_u64_pair(high_bits: u64, low_bits: u64) -> Self { /* ... */ }
```
Creates a UUID from two 64bit values.
- ```rust
pub fn from_slice(b: &[u8]) -> Result<Uuid, Error> { /* ... */ }
```
Creates a UUID using the supplied bytes.
- ```rust
pub fn from_slice_le(b: &[u8]) -> Result<Uuid, Error> { /* ... */ }
```
Creates a UUID using the supplied bytes in little endian order.
- ```rust
pub const fn from_bytes(bytes: Bytes) -> Uuid { /* ... */ }
```
Creates a UUID using the supplied bytes.
- ```rust
pub const fn from_bytes_le(b: Bytes) -> Uuid { /* ... */ }
```
Creates a UUID using the supplied bytes in little endian order.
- ```rust
pub fn from_bytes_ref(bytes: &Bytes) -> &Uuid { /* ... */ }
```
Creates a reference to a UUID from a reference to the supplied bytes.
- ```rust
pub fn parse_str(input: &str) -> Result<Uuid, Error> { /* ... */ }
```
Parses a `Uuid` from a string of hexadecimal digits with optional
- ```rust
pub const fn try_parse(input: &str) -> Result<Uuid, Error> { /* ... */ }
```
Parses a `Uuid` from a string of hexadecimal digits with optional
- ```rust
pub const fn try_parse_ascii(input: &[u8]) -> Result<Uuid, Error> { /* ... */ }
```
Parses a `Uuid` from a string of hexadecimal digits with optional
- ```rust
pub const fn hyphenated(self: Self) -> Hyphenated { /* ... */ }
```
Get a [`Hyphenated`] formatter.
- ```rust
pub fn as_hyphenated(self: &Self) -> &Hyphenated { /* ... */ }
```
Get a borrowed [`Hyphenated`] formatter.
- ```rust
pub const fn simple(self: Self) -> Simple { /* ... */ }
```
Get a [`Simple`] formatter.
- ```rust
pub fn as_simple(self: &Self) -> &Simple { /* ... */ }
```
Get a borrowed [`Simple`] formatter.
- ```rust
pub const fn urn(self: Self) -> Urn { /* ... */ }
```
Get a [`Urn`] formatter.
- ```rust
pub fn as_urn(self: &Self) -> &Urn { /* ... */ }
```
Get a borrowed [`Urn`] formatter.
- ```rust
pub const fn braced(self: Self) -> Braced { /* ... */ }
```
Get a [`Braced`] formatter.
- ```rust
pub fn as_braced(self: &Self) -> &Braced { /* ... */ }
```
Get a borrowed [`Braced`] formatter.
- ```rust
pub fn now_v1(node_id: &[u8; 6]) -> Self { /* ... */ }
```
Create a new version 1 UUID using the current system time and node ID.
- ```rust
pub fn new_v1(ts: Timestamp, node_id: &[u8; 6]) -> Self { /* ... */ }
```
Create a new version 1 UUID using the given timestamp and node ID.
- ```rust
pub fn new_v3(namespace: &Uuid, name: &[u8]) -> Uuid { /* ... */ }
```
Creates a UUID using a name from a namespace, based on the MD5
- ```rust
pub fn new_v4() -> Uuid { /* ... */ }
```
Creates a random UUID.
- ```rust
pub fn new_v5(namespace: &Uuid, name: &[u8]) -> Uuid { /* ... */ }
```
Creates a UUID using a name from a namespace, based on the SHA-1 hash.
- ```rust
pub fn now_v6(node_id: &[u8; 6]) -> Self { /* ... */ }
```
Create a new version 6 UUID using the current system time and node ID.
- ```rust
pub fn new_v6(ts: Timestamp, node_id: &[u8; 6]) -> Self { /* ... */ }
```
Create a new version 6 UUID using the given timestamp and a node ID.
- ```rust
pub fn now_v7() -> Self { /* ... */ }
```
Create a new version 7 UUID using the current time value.
- ```rust
pub fn new_v7(ts: Timestamp) -> Self { /* ... */ }
```
Create a new version 7 UUID using a time value and random bytes.
- ```rust
pub const fn new_v8(buf: [u8; 16]) -> Uuid { /* ... */ }
```
Creates a custom UUID comprised almost entirely of user-supplied bytes.
- ```rust
pub const fn get_variant(self: &Self) -> Variant { /* ... */ }
```
Returns the variant of the UUID structure.
- ```rust
pub const fn get_version_num(self: &Self) -> usize { /* ... */ }
```
Returns the version number of the UUID.
- ```rust
pub const fn get_version(self: &Self) -> Option<Version> { /* ... */ }
```
Returns the version of the UUID.
- ```rust
pub fn as_fields(self: &Self) -> (u32, u16, u16, &[u8; 8]) { /* ... */ }
```
Returns the four field values of the UUID.
- ```rust
pub fn to_fields_le(self: &Self) -> (u32, u16, u16, &[u8; 8]) { /* ... */ }
```
Returns the four field values of the UUID in little-endian order.
- ```rust
pub const fn as_u128(self: &Self) -> u128 { /* ... */ }
```
Returns a 128bit value containing the value.
- ```rust
pub const fn to_u128_le(self: &Self) -> u128 { /* ... */ }
```
Returns a 128bit little-endian value containing the value.
- ```rust
pub const fn as_u64_pair(self: &Self) -> (u64, u64) { /* ... */ }
```
Returns two 64bit values containing the value.
- ```rust
pub const fn as_bytes(self: &Self) -> &Bytes { /* ... */ }
```
Returns a slice of 16 octets containing the value.
- ```rust
pub const fn into_bytes(self: Self) -> Bytes { /* ... */ }
```
Consumes self and returns the underlying byte value of the UUID.
- ```rust
pub const fn to_bytes_le(self: &Self) -> Bytes { /* ... */ }
```
Returns the bytes of the UUID in little-endian order.
- ```rust
pub const fn is_nil(self: &Self) -> bool { /* ... */ }
```
Tests if the UUID is nil (all zeros).
- ```rust
pub const fn is_max(self: &Self) -> bool { /* ... */ }
```
Tests if the UUID is max (all ones).
- ```rust
pub const fn encode_buffer() -> [u8; 45] { /* ... */ }
```
A buffer that can be used for `encode_...` calls, that is
- ```rust
pub const fn get_timestamp(self: &Self) -> Option<Timestamp> { /* ... */ }
```
If the UUID is the correct version (v1, v6, or v7) this will return
- ```rust
pub const fn get_node_id(self: &Self) -> Option<[u8; 6]> { /* ... */ }
```
If the UUID is the correct version (v1, or v6) this will return the
##### Trait Implementations
- **Any**
- ```rust
fn type_id(self: &Self) -> TypeId { /* ... */ }
```
- **Arbitrary**
- ```rust
fn arbitrary(u: &mut Unstructured<''_>) -> arbitrary::Result<Self> { /* ... */ }
```
- ```rust
fn size_hint(_: usize) -> (usize, Option<usize>) { /* ... */ }
```
- **AsRef**
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- ```rust
fn as_ref(self: &Self) -> &Uuid { /* ... */ }
```
- ```rust
fn as_ref(self: &Self) -> &[u8] { /* ... */ }
```
- **Borrow**
- ```rust
fn borrow(self: &Self) -> &T { /* ... */ }
```
- ```rust
fn borrow(self: &Self) -> &Uuid { /* ... */ }
```
- ```rust
fn borrow(self: &Self) -> &Uuid { /* ... */ }
```
- ```rust
fn borrow(self: &Self) -> &Uuid { /* ... */ }
```
- ```rust
fn borrow(self: &Self) -> &Uuid { /* ... */ }
```
- **BorrowMut**
- ```rust
fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
```
- **BorshDeserialize**
- ```rust
fn deserialize_reader<__R: borsh::io::Read>(reader: &mut __R) -> ::core::result::Result<Self, borsh::io::Error> { /* ... */ }
```
- **BorshSerialize**
- ```rust
fn serialize<__W: borsh::io::Write>(self: &Self, writer: &mut __W) -> ::core::result::Result<(), borsh::io::Error> { /* ... */ }
```
- **Clone**
- ```rust
fn clone(self: &Self) -> Uuid { /* ... */ }
```
- **CloneToUninit**
- ```rust
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
```
- **Copy**
- **Debug**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Default**
- ```rust
fn default() -> Self { /* ... */ }
```
- **Deserialize**
- ```rust
fn deserialize<D: Deserializer<''de>>(deserializer: D) -> Result<Self, <D as >::Error> { /* ... */ }
```
- **DeserializeOwned**
- **Display**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Eq**
- **Freeze**
- **From**
- ```rust
fn from(t: T) -> T { /* ... */ }
```
Returns the argument unchanged.
- ```rust
fn from(non_nil: NonNilUuid) -> Self { /* ... */ }
```
Converts a [`NonNilUuid`] back into a [`Uuid`].
- ```rust
fn from(uuid: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Hyphenated) -> Self { /* ... */ }
```
- ```rust
fn from(f: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Simple) -> Self { /* ... */ }
```
- ```rust
fn from(f: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Urn) -> Self { /* ... */ }
```
- ```rust
fn from(f: Uuid) -> Self { /* ... */ }
```
- ```rust
fn from(f: Braced) -> Self { /* ... */ }
```
- ```rust
fn from(value: Uuid) -> Self { /* ... */ }
```
- **FromStr**
- ```rust
fn from_str(uuid_str: &str) -> Result<Self, <Self as >::Err> { /* ... */ }
```
- **Hash**
- ```rust
fn hash<H: Hasher>(self: &Self, state: &mut H) { /* ... */ }
```
- **Into**
- ```rust
fn into(self: Self) -> U { /* ... */ }
```
Calls `U::from(self)`.
- **LowerHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Ord**
- ```rust
fn cmp(self: &Self, other: &Uuid) -> $crate::cmp::Ordering { /* ... */ }
```
- **PartialEq**
- ```rust
fn eq(self: &Self, other: &Uuid) -> bool { /* ... */ }
```
- ```rust
fn eq(self: &Self, other: &NonNilUuid) -> bool { /* ... */ }
```
- ```rust
fn eq(self: &Self, other: &Uuid) -> bool { /* ... */ }
```
- **PartialOrd**
- ```rust
fn partial_cmp(self: &Self, other: &Uuid) -> $crate::option::Option<$crate::cmp::Ordering> { /* ... */ }
```
- **RefUnwindSafe**
- **Same**
- **Send**
- **SendSyncUnwindSafe**
- **Serialize**
- ```rust
fn erased_serialize(self: &Self, serializer: &mut dyn Serializer) -> Result<Ok, Error> { /* ... */ }
```
- ```rust
fn serialize<S: Serializer>(self: &Self, serializer: S) -> Result<<S as >::Ok, <S as >::Error> { /* ... */ }
```
- **StructuralPartialEq**
- **Sync**
- **ToOwned**
- ```rust
fn to_owned(self: &Self) -> T { /* ... */ }
```
- ```rust
fn clone_into(self: &Self, target: &mut T) { /* ... */ }
```
- **ToString**
- ```rust
fn to_string(self: &Self) -> String { /* ... */ }
```
- **TryFrom**
- ```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
```
- ```rust
fn try_from(uuid: Uuid) -> Result<Self, <Self as >::Error> { /* ... */ }
```
Attempts to convert a [`Uuid`] into a [`NonNilUuid`].
- ```rust
fn try_from(uuid_str: &str) -> Result<Self, <Self as >::Error> { /* ... */ }
```
- ```rust
fn try_from(uuid_str: String) -> Result<Self, <Self as >::Error> { /* ... */ }
```
- ```rust
fn try_from(value: std::vec::Vec<u8>) -> Result<Self, <Self as >::Error> { /* ... */ }
```
- **TryInto**
- ```rust
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
```
- **Unpin**
- **UnwindSafe**
- **UpperHex**
- ```rust
fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
```
- **Value**
- ```rust
fn serialize(self: &Self, _: &slog::Record<''_>, key: slog::Key, serializer: &mut dyn slog::Serializer) -> Result<(), slog::Error> { /* ... */ }
```
## Macros
### Macro `uuid`
**Attributes:**
- `Other("#[<cfg_trace>(not(feature = \"macro-diagnostics\"))]")`
- `MacroExport`
Parse [`Uuid`][uuid::Uuid]s from string literals at compile time.
## Usage
This macro transforms the string literal representation of a
[`Uuid`][uuid::Uuid] into the bytes representation, raising a compilation
error if it cannot properly be parsed.
## Examples
Setting a global constant:
```
# use uuid::{uuid, Uuid};
pub const SCHEMA_ATTR_CLASS: Uuid = uuid!("00000000-0000-0000-0000-ffff00000000");
pub const SCHEMA_ATTR_UUID: Uuid = uuid!("00000000-0000-0000-0000-ffff00000001");
pub const SCHEMA_ATTR_NAME: Uuid = uuid!("00000000-0000-0000-0000-ffff00000002");
```
Defining a local variable:
```
# use uuid::uuid;
let uuid = uuid!("urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4");
```
Using a const variable:
```
# use uuid::uuid;
const UUID_STR: &str = "12345678-1234-5678-1234-567812345678";
let UUID = uuid!(UUID_STR);
```
## Compilation Failures
Invalid UUIDs are rejected:
```compile_fail
# use uuid::uuid;
let uuid = uuid!("F9168C5E-ZEB2-4FAA-B6BF-329BF39FA1E4");
```
Enable the feature `macro-diagnostics` to see the error messages below.
Provides the following compilation error:
```txt
error: invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found Z at 9
|
| let id = uuid!("F9168C5E-ZEB2-4FAA-B6BF-329BF39FA1E4");
| ^
```
[uuid::Uuid]: https://docs.rs/uuid/*/uuid/struct.Uuid.html
```rust
pub macro_rules! uuid {
/* macro_rules! uuid {
($uuid:expr) => { ... };
} */
}
```
## Re-exports
### Re-export `NoContext`
```rust
pub use timestamp::context::NoContext;
```
### Re-export `ClockSequence`
```rust
pub use timestamp::ClockSequence;
```
### Re-export `Timestamp`
```rust
pub use timestamp::Timestamp;
```
### Re-export `Context`
**Attributes:**
- `Other("#[<cfg_trace>(any(feature = \"v1\", feature = \"v6\"))]")`
```rust
pub use timestamp::context::Context;
```
### Re-export `ContextV7`
**Attributes:**
- `Other("#[<cfg_trace>(feature = \"v7\")]")`
```rust
pub use timestamp::context::ContextV7;
```
### Re-export `Builder`
```rust
pub use crate::builder::Builder;
```
### Re-export `Error`
```rust
pub use crate::error::Error;
```
### Re-export `NonNilUuid`
```rust
pub use crate::non_nil::NonNilUuid;
```
Reference in New Issue View Git Blame Copy Permalink