gwid

Implementing RFC 9562 ccompliant UUIDs (also known as GUIDs). The name gwid is derived from the phonetic pronunciation of GUID.

UUID Version 4

UUIDv4 is a 128-bit UUID generated using cryptographically secure random bits, providing a high degree of uniqueness without encoding a timestamp or providing chronological ordering.

generate() -> String

Usage

use gwid;
let uuid = gwid::v4::generate();

generate_raw() -> u128

Returns the raw u128 UUID. If you need to format it as a hexadecimal encoded String with hyphens, please use add_hyphens.

Usage

use gwid;
let uuid = gwid::v4::generate_raw();
let with_hyphens = gwid::add_hyphens(uuid);

UUID Version 7

UUIDv7 is a 128-bit, time-ordered UUID that embeds a Unix timestamp (milliseconds) and uses random bits for uniqueness. Its time-based structure makes UUIDs naturally sortable by creation time.

generate() -> String

Generates UUIDv7 values with sub-millisecond timestamp precision. Although thread-safe, UUIDs generated across multiple threads are not guaranteed to be globally monotonic.

For example, two UUIDs generated within the same sub-millisecond bucket may be out of order:

// First UUID (greater)
let first = "01a1d02e-eedb-7995-82da-278257b8340d";

// Second UUID (smaller)
let second = "01a1d02e-eedb-7995-808d-0ba60b4a6dd4";

If you require strict sub-millisecond monotonicity, use generate_strict().

RFC 9562 does not require the random bits to be cryptographically secure, so we use a pseudorandom number generator for randomness. If you want to use cryptographically secure bits for randomness, enable the v7-crypto-rand feature flag!

Usage

use gwid;
let uuidv7 = gwid::v7::generate().expect("error generating");

generate_strict() -> String

Guarantees strict thread-local monotonicity. By default, monotonicity is maintained independently per thread. To guarantee strict global monotonicity across threads, enable the v7-global-monotonicity feature flag.

RFC 9562 does not require the random bits to be cryptographically secure, so we use a pseudorandom number generator for randomness. If you want to use cryptographically secure bits for randomness, enable the v7-crypto-rand feature flag!

Usage

use gwid;
let uuidv7 = gwid::v7::generate_strict().expect("error generating strict");

generate_raw() -> u128

Behaves exactly like generate(), but returns the raw u128 UUID. If you need to format the raw UUID as a hexadecimal encoded String with hyphens, please use add_hyphens.

generate_strict_raw() -> u128

Behaves exactly like generate_strict(), but returns the raw u128 UUID. If you need to format the raw UUID as a hexadecimal encoded String with hyphens, please use add_hyphens.

Monotonic Precision

*timestamp - guarantees sub-millisecond timestamp precision, but does not guarantee monotonicity within the same sub-millisecond timestamp bucket *strict - guarantees monotonicity within same sub-millisecond timestamp bucket

Helper Functions

add_hyphens(uuid: u128) -> String

Format a raw u128 UUID to a hexadecimal encoded String with hyphens.

use gwid;
let raw_uuid: u128 = 54839052801522565720884485497537422415;
let with_hyphens = gwid::add_hyphens(raw_uuid);

uuid_to_raw(uuid: &str) -> Result<u128, ParseIntError>

Get the underlying raw u128 value from a UUID.

use gwid;
let uuid_str: &str = "a60d0392-a436-4e0f-b560-9f763b1d99a1";
let raw_uuid = gwid::uuid_to_raw(uuid_str).expect("raw uuid");

uuid_to_raw_unchecked(uuid: &str) -> u128

Panics if something goes wrong during parsing!

Get the underlying raw u128 value from a UUID.

use gwid;
let uuid_str: &str = "a60d0392-a436-4e0f-b560-9f763b1d99a1";
let raw_uuid = gwid::uuid_to_raw_unchecked(uuid_str);

Cargo Features

v7-global-monotonicity

Enable the feature in your Cargo.toml:

[dependencies]
gwid = { version = "0.1", features = ["v7-global-monotonicity"] }

When enabled (default), UUIDv7 generation uses a shared Mutex to synchronize generator state across threads, ensuring globally monotonic UUID generation within the process.

When disabled, each thread maintains its own independent generator state using thread-local storage. This eliminates mutex overhead and can improve single-threaded and concurrent generation performance, but monotonicity is only guaranteed within each individual thread, not across threads.

v7-crypto-rand

Enable the feature in your Cargo.toml:

[dependencies]
gwid = { version = "0.1", features = ["v7-crypto-rand"] }

When enabled cryptographically secure bits are used for randomness (specifically, the random_b field).

RFC 9562 does not require the random bits to be cryptographically secure, so we use a pseudorandom number generator for randomness.