Crate valence::uuid

Generate and parse universally unique identifiers (UUIDs).

Here’s an example of a UUID:

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.

Getting started

Add the following to your Cargo.toml:

[dependencies.uuid]
version = "1.11.0"
features = [
    "v4",                # Lets you generate random UUIDs
    "fast-rng",          # Use a faster (but still sufficiently random) RNG
    "macro-diagnostics", # Enable better diagnostics for compile-time UUIDs
]

When you want a UUID, you can generate one:

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. This feature requires more dependencies to compile, but is just as suitable for UUIDs as the default algorithm.
• 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:

RUSTFLAGS="--cfg uuid_unstable"

Building for other targets

WebAssembly

For WebAssembly, enable the js feature:

[dependencies.uuid]
version = "1.11.0"
features = [
    "v4",
    "v7",
    "js",
]

Embedded

For embedded targets without the standard library, you’ll need to disable default features when building uuid:

[dependencies.uuid]
version = "1.11.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 follow getrandom’s docs on configuring a source of randomness on currently unsupported targets. Alternatively, you can produce random bytes yourself and then pass them to Builder::from_random_bytes without enabling the v4 or v7 features.

Examples

Parse a UUID given in the simple format and print it as a URN:

let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;

println!("{}", my_uuid.urn());

Generate a random UUID and print it out in hexadecimal form:

// Note that this requires the `v4` feature to be enabled.
let my_uuid = Uuid::new_v4();

println!("{}", my_uuid);

References

• Wikipedia: Universally Unique Identifier
• RFC 9562: Universally Unique IDentifiers (UUID).

Modules

• fmt
  Adapters for alternative string formats.
• serde
  Adapters for alternative serde formats.
• timestamp
  Generating UUIDs from timestamps.

Macros

• uuid
  Parse Uuids from string literals at compile time.

Structs

• Builder
  A builder for creating a UUID.
• Error
  A general error that can occur when working with UUIDs.
• NoContext
  An empty counter that will always return the value 0.
• Timestamp
  A timestamp that can be encoded into a UUID.
• Uuid
  A Universally Unique Identifier (UUID).

Enums

• Variant
  The reserved variants of UUIDs.
• Version
  The version of the UUID, denoting the generating algorithm.

Traits

• ClockSequence
  A counter that can be used by versions 1 and 6 UUIDs to support the uniqueness of timestamps.

Type Aliases

• Bytes
  A 128-bit (16 byte) buffer containing the UUID.