Crate uuid

Expand description

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.

Getting started

Add the following to your Cargo.toml:

[dependencies.uuid]
version = "1.1.1"
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");

Dependencies

By default, this crate depends on nothing but std and can parse and format UUIDs, but cannot generate them. You need to enable the following Cargo features to enable various pieces of functionality:

v1 - adds the Uuid::new_v1 function and the ability to create a V1 UUID using an implementation of v1::ClockSequence (usually v1::Context) and a UNIX timestamp.
v3 - adds the Uuid::new_v3 function and the ability to create a V3 UUID based on the MD5 hash of some data.
v4 - adds the Uuid::new_v4 function and the ability to randomly generate a UUID.
v5 - adds the Uuid::new_v5 function and the ability to create a V5 UUID based on the SHA1 hash of some data.

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.
arbitrary - adds an Arbitrary trait implementation to Uuid for fuzzing.
fast-rng - when combined with v4 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.

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 along with v4 for a source of randomness:

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

You don’t need the js feature to use uuid in WebAssembly if you’re not also enabling v4.

Embedded

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

[dependencies.uuid]
version = "1"
default-features = false

Some additional features are supported in no-std environments:

v1, v3, and v5
serde

If you need to use v4 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 feature.

Examples

To 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());

To create a new random (V4) 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);

Error

A general error that can occur when working with UUIDs.

Uuid

A Universally Unique Identifier (UUID).

Enums

Variant

The reserved variants of UUIDs.

Version

The version of the UUID, denoting the generating algorithm.

Type Definitions

Bytes

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