4 min readFeb 24, 2024

Support me by buying an item from my wishlist, visiting my reviews site or buy me a coffee!

Using the Uuid Crate in Rust

Rust is a modern programming language that offers high performance, reliability, and productivity. One of the features that makes Rust attractive is its rich ecosystem of crates, which are reusable libraries that can be easily integrated into your projects. In this article, we will explore one of the most popular crates in Rust: the uuid crate.

The uuid crate is a Rust library designed for generating and parsing Universally Unique Identifiers (UUIDs). A UUID is a 128-bit value that serves as a unique identifier, often used in databases, distributed systems, and network protocols. The crate is highly popular, with over 846 stars on GitHub and is used by more than 174,000 projects.

Why Use UUIDs?

UUIDs are useful for several reasons:

They are globally unique, meaning that the probability of two UUIDs being the same is extremely low.
They are easy to generate, requiring no coordination or central authority.
They are versatile, supporting different versions and formats.

How to Use the uuid Crate?

To use the uuid crate, you need to add it as one of your project’s dependencies in your Cargo.toml file:

[dependencies]
uuid = { version = "0.8", features = [ "serde", "v4"] }

The features option allows you to enable different functionalities of the crate, such as serialization support ( serde) and random UUID generation ( v4). You can find the full list of features in the crate documentation.

Once you have added the dependency, you can import the crate in your Rust code:

use uuid::Uuid;

How to Generate UUIDs?

The uuid crate supports all standardized methods for generating UUIDs through individual Cargo features. By default, the crate can only parse and format UUIDs, but not generate them. Depending on the kind of UUID you want to work with, you need to enable the corresponding feature in your Cargo.toml file.

For example, if you want to generate random UUIDs (version 4), you need to enable the v4 feature:

[dependencies]
uuid = { version = "0.8", features = [ "v4"] }

Then, you can use the new_v4 method to create a random UUID:

use uuid::Uuid;

let id = Uuid::new_v4();
println!("{}", id); // e.g. 67e55044-10b1-426f-9247-bb680e5fe0c8

Similarly, if you want to generate UUIDs based on the SHA-1 hash of some data (version 5), you need to enable the v5 feature:

[dependencies]
uuid = { version = "0.8", features = [ "v5"] }

Then, you can use the new_v5 method to create a hashed UUID:

use uuid::{Uuid, Version};

// A namespace UUID for the DNS domain
const NAMESPACE_DNS: Uuid = Uuid::from_u128(0x6ba7b810_9dad_11d1_80b4_00c04fd430c8);

// The data to hash
let name = "example.com";

// Create a version 5 UUID
let id = Uuid::new_v5(&NAMESPACE_DNS, name.as_bytes());
println!("{}", id); // e.g. aad4fdee-d61d-5f4f-9dfd-814e02b0a27b

The crate also supports other versions of UUIDs, such as version 1 (based on a timestamp and a monotonic counter), version 3 (based on the MD5 hash of some data), version 6 (based on a timestamp and a monotonic counter with a different layout), version 7 (based on a Unix timestamp), and version 8 (based on user-defined data). You can find more details and examples in the crate documentation.

How to Parse UUIDs?

The uuid crate can parse UUIDs from different formats, such as strings, bytes, or slices. You can use the parse_str method to parse a UUID from a string:

use uuid::{Uuid, Version};

// A valid UUID string
let input = "67e55044-10b1-426f-9247-bb680e5fe0c8";

// Parse the string as a UUID
let id = Uuid::parse_str(input)?;
println!("{}", id); // 67e55044-10b1-426f-9247-bb680e5fe0c8

// Get the version of the UUID
assert_eq!(Some(Version::Random), id.get_version());

You can also use the from_bytes or from_slice methods to parse a UUID from a byte array or a slice:

use uuid::Uuid;

// A valid UUID byte array
let input = [
    0x67, 0xe5, 0x50, 0x44, 0x10, 0xb1, 0x42, 0x6f,
    0x92, 0x47, 0xbb, 0x68, 0x0e, 0x5f, 0xe0, 0xc8,
];

// Parse the bytes as a UUID
let id = Uuid::from_bytes(input)?;
println!("{}", id); // 67e55044-10b1-426f-9247-bb680e5fe0c8

// Parse a slice of the bytes as a UUID
let id = Uuid::from_slice(&input[0..16])?;
println!("{}", id); // 67e55044-10b1-426f-9247-bb680e5fe0c8

How to Format UUIDs?

The uuid crate can format UUIDs in different ways, such as hexadecimal strings, URNs, or simple strings. You can use the to_hyphenated method to format a UUID as a hexadecimal string with hyphens:

use uuid::Uuid;

// A random UUID
let id = Uuid::new_v4();

// Format the UUID as a hyphenated string
let output = id.to_hyphenated().to_string();
println!("{}", output); // e.g. 67e55044-10b1-426f-9247-bb680e5fe0c8

You can also use the to_urn method to format a UUID as a Uniform Resource Name (URN):

use uuid::Uuid;

// A random UUID
let id = Uuid::new_v4();

// Format the UUID as a URN
let output = id.to_urn().to_string();
println!("{}", output); // e.g. urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8

Alternatively, you can use the to_simple method to format a UUID as a simple string without hyphens:

use uuid::Uuid;

// A random UUID
let id = Uuid::new_v4();

// Format the UUID as a simple string
let output = id.to_simple().to_string();
println!("{}", output); // e.g. 67e5504410b1426f9247bb680e5fe0c8

Conclusion

The uuid crate is a powerful and convenient tool for working with UUIDs in Rust. It supports all the standard versions and formats of UUIDs, and provides easy methods for generating, parsing, and formatting them. If you need to use UUIDs in your Rust projects, you should definitely check out the uuid crate and its documentation.🦀