blackwriter-server/doc/uuid.md

# 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;
```