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.
UUIDs have a number of standardized encodings that are specified in RFC4122, with recent additions in draft.
Getting started
Add the following to your Cargo.toml:
[dependencies.uuid]
version = "1.2.2"
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.
Versions that are in draft are also supported. See the unstable features section for details.
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 ofuuid!macro.serde- adds the ability to serialize and deserialize a UUID usingserde.arbitrary- adds anArbitrarytrait implementation toUuidfor 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.
Unstable features
Some features are unstable. They may be incomplete or depend on other unstable libraries. These include:
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.zerocopy- adds support for zero-copy deserialization using thezerocopylibrary.
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.2.2"
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.2.2"
default-features = false
Some additional features are supported in no-std environments:
v1,v3,v5,v6, andv8.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 feature.
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
Re-exports
pub use timestamp::context::NoContext;pub use timestamp::ClockSequence;pub use timestamp::Timestamp;Modules
serde formats.