Generate and parse UUIDs.

Last update: Jan 6, 2023

Related tags

Overview

`uuid`

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.0.0-alpha.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");

You can also parse UUIDs without needing any crate features:

use uuid::{Uuid, Version};

let my_uuid = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8")?;

assert_eq!(Some(Version::Random), my_uuid.get_version());

If you'd like to parse UUIDs really fast, check out the uuid-simd library.

For more details on using uuid, see the library documentation.

Minimum Supported Rust Version (MSRV)

The minimum supported Rust version for uuid is documented in CI. It may be bumped in minor releases as necessary.

References

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Comments

Support serialization as `[u8; 16]` rather than as `&[u8]`

Is your feature request related to a problem? Please describe. Currently, serialization and deserialization are performed as a slice rather than a fixed-sized array. When using the bincode codec, this means that the raw data is prefixed with a redundant length tag (16usize), which is unsuitable for loading binary datastructures containing UUIDs. It is also unexpected that a UUID is serialized in a different way than [u8; 16], since it essentially is an [u8; 16].

Describe the solution you'd like I would like to be able to serialize a UUID as if it was a [u8; 16] in non-human-readable codecs. This could be protected by a new feature flag to avoid breaking compatibility with old serialized data.

Is it blocking? Not really, since we stopped using this crate because of this issue. While it would be possible to implement a different serialization for the UUID type, it was easier for us to use a plain [u8;16] instead.

Describe alternatives you've considered I looked into writing my own serialization and deserialization functions. It would be nice if this was supported out of the box, though.

Additional context N/A

Other N/A

opened by smarnach 31
Rethink the `serde` `[u8; 16]` binary representation
Blocking #553 Following #329

The currently proposed stable uuid API changes the serde implementation from &[u8] to [u8; 16]. This is a breaking change to existing serialized data.

It's been pointed out on Reddit that [u8; 16] isn't really a universal improvement over &[u8] for binary formats, because some can treat byte slices specially.

Before stabilizing, we should try come to some consensus on this one way or another. If we can't, then I think we should fall back to the status-quo of &[u8]. So I think the options are:

&[u8]: the current approach. Can be optimized by some binary formats compared to tuples/sequences. Produces a redundant length field. May be possible to do bytemucking to re-interpret serialized bits directly as a UUID.

[u8; 16]: what's on main. Is better for some binary formats that don't have an overhead per field on sequences, but is less optimal for some binary formats than &[u8]. Will cause breakage for existing data.

~~u128: what I'm currently proposing. Can be formatted optimally by any binary format. Isn't necessarily guaranteed to be supported by all serializers/deserializers. The encoded UUID won't look like a UUID. Will cause breakage for existing data.~~

Some kind of Serializer::serialize_byte_array<const N: usize>(bytes: &[u8; N]) in serde that forwards to &[u8]?

Anything else?

cc @smarnach @Marwes @mitsuhiko (as having originally provided input on the serde format)

Also just to re-iterate, this only affects non-human-readable formats like bincode. Other formats like serde-json are still going to use hyphenated strings by default.
opened by KodrAus 26
Macro construction without `syn`

Motivation Macros are notoriously slow at compile time to include, it'd be nice to remove the tradeoff for users

Solution The uuid macro can be implemented with const fn (Playground). This makes the decision easier for users - just move the call to a const context.

If we wish, we can also have the uuid macro to force the parsing to be const.

opened by Plecra 22
Differences in parsing UUIDs from uint128 in Python and Rust
Describe the bug I'm creating a binding of this library to Python for learning purposes and possible production usage. I've encountered a difference in the values Python provides and the values Rust provides when parsing a UUID from an unsigned 128-bit integer.

To Reproduce

When parsing a UUID from an unsigned integer in Python I get the following UUID:

>>> import uuid >>> uuid.UUID(int=286695482685957555672632549999181678124) UUID('d7af8a9f-e924-4f96-b36f-9ecea445c62c')

However, when I use the following rust code:

extern crate uuid; use uuid::Uuid; let u: uint128 = 286695482685957555672632549999181678124; let uuid: Uuid = u.into(); println!(uuid.to_hyphenated() .encode_lower(&mut Uuid::encode_buffer()) .to_string());

The output is the following UUID: 2cc645a4-ce9e-6fb3-964f-24e99f8aafd7

Expected behavior I think that the value should be the same in both implementations. If not, we need to figure out the difference and decide which implementation is correct.

Screenshots If applicable, add screenshots to help explain your problem.

Specifications (please complete the following information):

Target: Debug

Version [e.g. 1.0]: 0.7.4

Features Enabled: v1, v3, v4, v5, u128

Additional context See the Python implementation here.

Other N/A
opened by thedrow 20
Feature/wasm
Description

This PR adds two new features:

stdweb

wasm-bindgen

These features are kind of passthrough features, because they do nothing in the uuid crate itself. They're just passed to the rand crate to make the uuid crate working for the wasm32-unknown-unknown target.

Motivation

I'm unable to generate random UUID (v4) when this crate is compiled for the wasm32-unknown-unknown target.

Tests

I just added these features ...

- cargo test --features "v3" - cargo test --features "v3 stdweb" - cargo test --features "v3 wasm-bindgen"

... for all v3 & v4 & v5 (rand crate is used in all these features) to the script section in the .travis.yml.

Not sure if it makes sense, but it can demonstrate that it's buildable at least.

I don't think that more tests are required unless you'd like to bring the whole wasm-bindgen, wasm-pack, ... machinery here. And it has no sense to do it, because goal of this PR is not to publish uuid-rs NPM package, just add the ability to compile & use it from the wasm32-unknown-unknown target.

Related Issue(s)

#350

now() doesn't work

Manual tests

My Cargo.toml:

[dependencies] uuid = { features = ["v4"], git = "https://github.com/zrzka/uuid.git", branch = "feature/wasm" } [target.wasm32-unknown-unknown.dependencies] uuid = { features = ["wasm-bindgen"], git = "https://github.com/zrzka/uuid.git", branch = "feature/wasm" }

My index.js:

const bt = require('balena-temen'); console.log( bt.evaluate({ "id": { "$$eval": "uuidv4()" } }) );

uuidv4() implementation.

Output:

{ id: 'cefa2919-ff48-48ef-a231-e13697e23ed2' }
opened by zrzka 20
Uuid::new_v4() compiles and then panics for wasm32-unknown-unknown target
Is your feature request related to a problem? Please describe.

I do use uuid crate in my crate, which can be used as a pure Rust library or as an isomorphic NPM package (node & browser). The only feature I do use is random UUID (v4) generation.

It panics:

panicked at 'could not initialize thread_rng: No entropy sources available (permanently unavailable)', /Users/robertvojta/.cargo/registry/src/github.com-1ecc6299db9ec823/rand-0.5.5/src/rngs/thread.rs:84:17

Example of what we do is in this issue. Our uuidv4() function source code.

Describe the solution you'd like

Generate UUID v4 even when compiled for the wasm32-unknown-unknown target.

Is it blocking?

Kind of. Not a high priority.

Describe alternatives you've considered

Thinking about using Math.random in my function if the target is wasm32-....

Other

Not sure if this is the uuid crate problem or it lies somehwere deeper inside this whole bleeding edge stuff.
opened by zrzka 19
[WIP] Add support for zerocopy traits via a feature.

I'm submitting a feature proposal.

Description

Allows uuid::Uuid to be read from or serialized to a byte slice without copying by using the zerocopy crate.

Motivation

I like the abstraction that zerocopy provides and UUIDs are often embedded in other structs I'd like to use zerocopy's traits on. Hiding this behind a feature that needs to be explicitly enabled should keep the general cost of this very low for the vast majority of users of uuid that do not use zerocopy.

Tests

Tests missing, therefore marked WIP.

Related Issue(s)

Not aware of any, possibly somewhat related to #472, though. Clearly adding another variant of as_bytes() via the zerocopy::AsBytes trait.

opened by mwanner 18
Tracker: Release 1.0
This is a list of things we need to do before we can release a stable version of uuid.

[x] https://github.com/rust-lang-nursery/uuid/issues/106

[x] ~~https://github.com/rust-lang-nursery/uuid/issues/90~~

[x] ~~Shift into rust-lang org~~

[x] ~~RFC (as per https://github.com/rust-lang/rfcs/blob/master/text/1242-rust-lang-crates.md)~~

[x] set up for bors?

[x] Find a new home for uuid

[x] #191

[x] Public dependencies:

~~[ ] Rename serde to serde1~~

~~[ ] Rename slog to slog2~~

[x] Shift winapi into an external library (uuid-winapi)

[x] Remove stdweb and rename wasm-bindgen to js

[ ] 1.0.0!
opened by KodrAus 17
uuid!("") literal macro

I am looking for a way to specify uuid literals in my code without having to do Uuid::parse_str("").unwrap(); at runtime. A good example for a different use case is the hex-literal crate (https://crates.io/crates/hex-literal) that makes is easy to specify hex literals with the hex!() macro. In this case, I would like to declare a UUID as a string like "cc58f58b-ca41-4678-b9f9-94ba4eeb9e1e" and have it checked for validity at compile-time to avoid the unwrap().

Maybe the best way would be to have the macro define a byte array to use Uuid::from_bytes() under the hood. Any thoughts?

opened by awakecoding 16
Little-Endian byte order support

Microsoft uses little-endian byte order representation for its GUID structure in memory, like this:

typedef struct _GUID { UINT32 Data1; UINT16 Data2; UINT16 Data3; BYTE Data4[8]; } GUID, UUID, *PGUID, *LPGUID, *LPCGUID;

Would it be possible to add the option of reading from byte arrays in little endian order, and writing to byte arrays in little endian order? The current code apparently assumes big-endian ordering 100% of the time, making it harder to interoperate in specific cases.

For instance, from_bytes_le and as_bytes_le could be special functions to read/write to/from bytes in little-endian order.

opened by awakecoding 15
Substitute unwrap for ? operator

I'm submitting a refactor (and fixes for test cases).

Description

This PR addresses C-QUESTION-MARK in the roadmap for #191. The examples have been updated to accommodate for the ? operator instead of .unwrap or try!.

Motivation

UUID can move forward with other portions of documentation given this has been completed.

Tests

All existing tests remain successful after changes.

Related Issue(s)

#191

opened by amadeusine 14

regression(?): Pretty debug printing now strips hyphens

What happened? When upgrading from uuid 0.8 to 1.2 pretty-debug-printing changed to not contain hyphens

Steps to reproduce the behavior:

fn main() {
    println!("{}", uuid::uuid!("161d93bd-bd16-4c9c-b236-2e044546f36c"));
    println!("{:?}", uuid::uuid!("161d93bd-bd16-4c9c-b236-2e044546f36c"));
    println!("{:#?}", uuid::uuid!("161d93bd-bd16-4c9c-b236-2e044546f36c"));
}

161d93bd-bd16-4c9c-b236-2e044546f36c
161d93bd-bd16-4c9c-b236-2e044546f36c
161d93bdbd164c9cb2362e044546f36c

What were you expecting?

161d93bd-bd16-4c9c-b236-2e044546f36c
161d93bd-bd16-4c9c-b236-2e044546f36c
161d93bd-bd16-4c9c-b236-2e044546f36c

What's the context?

rustc 1.66.0 (69f9c33d7 2022-12-12)
uuid: 1.2.2
features: None

opened by bergmark 0

Add reordering to convert between v1 and v6 UUIDs
Motivation

According to the uuid v6+ draft, v6 UUIDs are just a rearrangement of v1 UUIDs. Being able to easily convert between them would be useful for updating anything that works with both rearranged and non-rearranged versions, plus providing an easy way to sort v1 UUIDs.

v1: time_low|time_mid|time_high_and_version|clk_seq_and_variant|node

v6: time_high|time_mid|time_low_and_version|clk_seq_hi_res|clk_seq_low|node

Relates to #523

Solution

An API along the lines of the following would be nice:

// rearrange a v1 UUID to v6 .v1_as_v6(&self) -> Self // rearrange a v6 UUID to v1 .v6_as_v1(&self) -> Self

Alternatives

This is currently possible by manually rearranging the bytes
opened by tgross35 1
error[E0432]: unresolved import `uuid` --> testuuid.rs:1:5 | 1 | use uuid::Uuid; | ^^^^ maybe a missing crate `uuid`? | = help: consider adding `extern crate uuid` to use the `uuid` crate

error[E0463]: can't find crate for uuid --> testuuid.rs:1:1 | 1 | extern crate uuid; | ^^^^^^^^^^^^^^^^^^ can't find crate

error: aborting due to previous error

For more information about this error, try rustc --explain E0463.

opened by harryheng 0
Backport Arbitrary support to 0.7.x and 0.6.x versions
Motivation We're using Diesel 1.x ,which depends on uuid 0.7.x. This forces our project to use uuid 0.7.x too. We'd really love to use Arbitrary to simplify testing in the project, but uuid started supporting Arbitrary only in 1.0 (which we cannot use at the moment due to the Diesel).

Solution Backport support of Arbitrary to 0.7.x and 0.8.x version of UUID.

Alternatives

Update to Diesel 2.x (which is not possible for us)

Wait until Arbitrary implements support for custom fields (https://github.com/rust-fuzz/arbitrary/issues/33) - the issue stays there for a while already.

Wrap UUIDs into newtype and implement Arbitrary for the newtype - we probably gonna this way if the idea will be rejected.

Is it blocking? I would not say that is blocking. Rather nice to have.

Anything else?

We're fine to contribute and open pull requests if the maintainer gives us a positive signal.

Thank you!
opened by greyblake 0
Tracking issue for defmt

This issue is a place to keep anybody using the unstable defmt feature up-to-date on any changes being made to it.

In order to use defmt, you need to opt-in not just to the feature, but to the uuid_unstable RUSTFLAGS configuration too. We can make breaking changes to defmt at any point, but still want to be considerate of anybody making use of it, so will try keep open about any version bumps or other breakage that's coming.
unstable

opened by KodrAus 0
Add a Natvis definition for `Uuid` along with tests and documentation
I'm submitting a feature

Description

This change adds Natvis visualizations for types in the uuid crate to help improve the debugging experience on Windows.

Natvis is a framework that can be used to specify how types should be viewed under a supported debugger, such as the Windows debugger (WinDbg) and the Visual Studio debugger.

The Rust compiler does have Natvis support for some types, but this is limited to some of the core libraries and not supported for external crates.

https://github.com/rust-lang/rfcs/pull/3191 proposes adding support for embedding debugging visualizations such as Natvis in a Rust crate. This RFC has been approved, merged and implemented.

This PR adds:

Natvis visualizations for the Uuid type.

Tests for testing visualizers embedded in the uuid crate.

A new debugger_visualizer feature for the uuid crate to enable the unstable debugger_visualizer Rust feature.

Changes to the CI pipeline to ensure debugger visualizer tests are run and do not break silently.

Updates to the CI pipeline to separate testing stable features vs. unstable features.
opened by ridwanabdillahi 1

Releases(1.2.2)

1.2.2(Nov 14, 2022)
What's Changed

CI Cleanups by @KodrAus in https://github.com/uuid-rs/uuid/pull/640

Remove extern crate alloc by @KodrAus in https://github.com/uuid-rs/uuid/pull/645

Prepare for 1.2.2 release by @KodrAus in https://github.com/uuid-rs/uuid/pull/646

Full Changelog: https://github.com/uuid-rs/uuid/compare/1.2.1...1.2.2
Source code(tar.gz)
Source code(zip)
1.2.1(Oct 8, 2022)
What's Changed

Fix up lost re-export of v1 Timestamp by @KodrAus in https://github.com/uuid-rs/uuid/pull/636

Prepare for 1.2.1 release by @KodrAus in https://github.com/uuid-rs/uuid/pull/637

Full Changelog: https://github.com/uuid-rs/uuid/compare/1.2.0...1.2.1
Source code(tar.gz)
Source code(zip)
1.2.0(Oct 8, 2022)
What's Changed

formatting changes by @pintariching in https://github.com/uuid-rs/uuid/pull/610

Remove outdated Travis CI reference by @atouchet in https://github.com/uuid-rs/uuid/pull/616

refactors Timestamp, Context and ClockSequence, and adds UUIDS v6, v7, v8 by @rrichardson in https://github.com/uuid-rs/uuid/pull/611

migrate from winapi to windows_sys in examples by @sn99 in https://github.com/uuid-rs/uuid/pull/626

Update windows-sys requirement from 0.36.1 to 0.42.0 by @dependabot in https://github.com/uuid-rs/uuid/pull/628

Some work on the new version features by @KodrAus in https://github.com/uuid-rs/uuid/pull/625

Implement now in wasm by @KodrAus in https://github.com/uuid-rs/uuid/pull/630

More work on docs by @KodrAus in https://github.com/uuid-rs/uuid/pull/631

hide draft versions behind the unstable cfg by @KodrAus in https://github.com/uuid-rs/uuid/pull/633

Prepare for 1.2.0 release by @KodrAus in https://github.com/uuid-rs/uuid/pull/634

New Contributors

@pintariching made their first contribution in https://github.com/uuid-rs/uuid/pull/610

@atouchet made their first contribution in https://github.com/uuid-rs/uuid/pull/616

@sn99 made their first contribution in https://github.com/uuid-rs/uuid/pull/626

Full Changelog: https://github.com/uuid-rs/uuid/compare/1.1.2...1.2.0
Source code(tar.gz)
Source code(zip)
1.1.2(Jun 10, 2022)
What's Changed

Fix some doc links by @mbrobbel in https://github.com/uuid-rs/uuid/pull/606

Prepare for 1.1.2 release by @KodrAus in https://github.com/uuid-rs/uuid/pull/607

New Contributors

@mbrobbel made their first contribution in https://github.com/uuid-rs/uuid/pull/606

Full Changelog: https://github.com/uuid-rs/uuid/compare/1.1.1...1.1.2
Source code(tar.gz)
Source code(zip)
1.1.1(May 31, 2022)
What's Changed

Fix documentation typo by @nstinus in https://github.com/uuid-rs/uuid/pull/603

Prepare for 1.1.1 release by @KodrAus in https://github.com/uuid-rs/uuid/pull/604

New Contributors

@nstinus made their first contribution in https://github.com/uuid-rs/uuid/pull/603

Full Changelog: https://github.com/uuid-rs/uuid/compare/1.1.0...1.1.1
Source code(tar.gz)
Source code(zip)
1.1.0(May 25, 2022)
What's Changed

note that the Error display impl is public API by @KodrAus in https://github.com/uuid-rs/uuid/pull/597

Fixed documentation link by @Razican in https://github.com/uuid-rs/uuid/pull/600

Add to_bytes_le method by @dfaust in https://github.com/uuid-rs/uuid/pull/599

Prepare for 1.1.0 release by @KodrAus in https://github.com/uuid-rs/uuid/pull/602

New Contributors

@Razican made their first contribution in https://github.com/uuid-rs/uuid/pull/600

@dfaust made their first contribution in https://github.com/uuid-rs/uuid/pull/599

Full Changelog: https://github.com/uuid-rs/uuid/compare/1.0.0...1.1.0
Source code(tar.gz)
Source code(zip)
1.0.0(Apr 20, 2022)
This release includes a huge amount of work from a lot of contributors. These notes are duplicated from 1.0.0-alpha.1 since they're relevant for anybody moving from 0.8.2 to 1.0.0.

Changes since the last release

https://github.com/uuid-rs/uuid/compare/0.8.2...main

Contributions since the last release

#510

#482

#511

#507

#518

#519

#512

#520

#521

#525

#526

#527

#528

#535

#536

#539

#538

#540

#541

#542

#544

#545

#546

#543

#547

#548

#549

#550

#552

#554

#558

#560

#562

#563

#564

#565

#566

#579

#584

#587

#595

@Gaelan @hecsalazarf @Expyron @saiintbrisson @tshepang @Tehnix @Takashiidobe @A248 @clehner

With a special thanks to:

@kinggoesgaming @QnnOkabayashi @Nugine

Highlights

Parsing and formatting methods are now much faster, and work in const too! On my i9 9900K Windows desktop, the difference looks something like this:

Case | 1.0.0-alpha.1 | 0.8.3 ----------------------- | ------------------ | ------------------ parse_invalid_character | 40 ns/iter (+/- 0) | 39 ns/iter (+/- 1) parse_invalid_group_len | 47 ns/iter (+/- 1) | 52 ns/iter (+/- 5) parse_invalid_groups | 58 ns/iter (+/- 1) | 58 ns/iter (+/- 0) parse_invalid_len | 57 ns/iter (+/- 2) | 6 ns/iter (+/- 0) parse_nil | 16 ns/iter (+/- 0) | 50 ns/iter (+/- 4) parse_nil_hyphenated | 17 ns/iter (+/- 0) | 59 ns/iter (+/- 2) parse_random | 16 ns/iter (+/- 0) | 42 ns/iter (+/- 1) parse_random_hyphenated | 18 ns/iter (+/- 0) | 51 ns/iter (+/- 2) parse_urn | 18 ns/iter (+/- 0) | 51 ns/iter (+/- 1)

You can go one step further and look at the uuid-simd library for vectorized UUID parsing. It's fast!

You can create UUIDs at compile time using the uuid! macro:

#[macro_use] extern crate uuid; use uuid::Uuid; const ID: Uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");

Enable the macro-diagnostics crate feature to get better diagnostics from uuid! using a procedural macro.

Breaking changes

Relocation of adapter::compact

This module can now be found in serde::compact. It can be combined with #[serde(with)] to serialize a Uuid using a more compact representation. We originally moved to this representation directly, but discovered it comes with its own drawbacks that aren't suitable for all formats.

Infallible constructors

The following methods have been changed to accept a &[u8; N] instead of a &[u8], making them infallible instead of returning a Result:

Uuid::from_fields

Uuid::from_fields_le

Uuid::new_v1

Builder::from_fields

Builder::from_fields_le

Infallible get_variant

The Uuid::get_variant method now returns a Variant instead of an Option<Varaint>, because it's not actually possible for it to ever be None.

Uuid::to_timestamp is now Uuid::get_timestamp

The Uuid::to_timestamp method has been renamed to Uuid::get_timestamp to make it more consistent with Uuid::get_version and Uuid::get_variant.

Changes to formatting methods

The following methods that produce formatting adapters have been renamed:

Uuid::to_hyphenated -> Uuid::hyphenated

Uuid::to_simple -> Uuid::simple

Uuid::to_urn -> Uuid::urn

The following types have been removed:

HyphenatedRef

SimpleRef

UrnRef

The following methods have been changed to return a &<AdapterType> instead of an <AtapterType>Ref:

Uuid::to_hyphenated_ref -> Uuid::as_hyphenated

Uuid::to_simple_ref -> Uuid::as_simple

Uuid::to_urn_ref -> Uuid::as_urn

Builder method consistency

The Builder::build method has been renamed to Builder::into_uuid, to complement the <AdapterType>::into_uuid methods. It also gets an equivalent Builder::as_uuid method.

Version and Variant are non-exhaustive

The #[non_exhaustive] attribute has been added to Version and Variant. There are already active proposals for new UUID versions, so these are likely to continue evolving in the future.

Removed winapi support

The Uuid::to_guid and Uuid::from_guid methods have been removed. This was done for two reasons:

We need to avoid unstable winapi types in the stable uuid public API.

Whether or not GUID fields need to be flipped to convert into a UUID depends on the source of the GUID, so we can't really offer a single pair of methods to convert a GUID into a UUID.

There are some examples in the repository root that demonstrate how to convert GUIDs into UUIDs as a replacement.

Building with --all-features

Now that uuid includes unstable features, if you're building with --all-features (such as in package manager scenarios), you'll also need to pass RUSTFLAGS="--cfg uuid_unstable", or you'll end up with compilation errors. If this strategy becomes problematic for users we can change unstable features to silently no-op instead of cause compilation failures if the corresponding cfg is not also supplied. Please reach out if that affects you!

Stability commitment

With uuid 1.0 we'll try to stay on that version "forever". There won't be a 2.0 unless there's a very compelling need for it. That means you should feel safe depending on Uuid in the public API of your libraries if you want to.
Source code(tar.gz)
Source code(zip)
1.0.0-alpha.1(Nov 18, 2021)
This release includes a huge amount of work from a lot of contributors. I'll try call out breakage here as well as in release notes once we're ready to merge so everyone knows what to expect.

Changes since the last release

https://github.com/uuid-rs/uuid/compare/0.8.2...main

Contributions since the last release

#510

#482

#511

#507

#518

#519

#512

#520

#521

#525

#526

#527

#528

#535

#536

#539

#538

#540

#541

#542

#544

#545

#546

#543

#547

#548

#549

#550

#552

#554

#558

#560

#562

#563

#564

#565

#566

@Gaelan @hecsalazarf @Expyron @saiintbrisson @tshepang @Tehnix @Takashiidobe

With a special thanks to:

@kinggoesgaming @QnnOkabayashi @Nugine

Highlights

Parsing and formatting methods are now much faster, and work in const too! On my i9 9900K Windows desktop, the difference looks something like this:

Case | 1.0.0-alpha.1 | 0.8.3 ----------------------- | ------------------ | ------------------ parse_invalid_character | 40 ns/iter (+/- 0) | 39 ns/iter (+/- 1) parse_invalid_group_len | 47 ns/iter (+/- 1) | 52 ns/iter (+/- 5) parse_invalid_groups | 58 ns/iter (+/- 1) | 58 ns/iter (+/- 0) parse_invalid_len | 57 ns/iter (+/- 2) | 6 ns/iter (+/- 0) parse_nil | 16 ns/iter (+/- 0) | 50 ns/iter (+/- 4) parse_nil_hyphenated | 17 ns/iter (+/- 0) | 59 ns/iter (+/- 2) parse_random | 16 ns/iter (+/- 0) | 42 ns/iter (+/- 1) parse_random_hyphenated | 18 ns/iter (+/- 0) | 51 ns/iter (+/- 2) parse_urn | 18 ns/iter (+/- 0) | 51 ns/iter (+/- 1)

You can go one step further and look at the uuid-simd library for vectorized UUID parsing. It's fast!

You can create UUIDs at compile time using the uuid! macro:

#[macro_use] extern crate uuid; use uuid::Uuid; const ID: Uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");

Enable the macro-diagnostics crate feature to get better diagnostics from uuid! using a procedural macro.

Breaking changes

Relocation of adapter::compact

This module can now be found in serde::compact. It can be combined with #[serde(with)] to serialize a Uuid using a more compact representation. We originally moved to this representation directly, but discovered it comes with its own drawbacks that aren't suitable for all formats.

Infallible constructors

The following methods have been changed to accept a &[u8; N] instead of a &[u8], making them infallible instead of returning a Result:

Uuid::from_fields

Uuid::from_fields_le

Uuid::new_v1

Builder::from_fields

Builder::from_fields_le

Infallible get_variant

The Uuid::get_variant method now returns a Variant instead of an Option<Varaint>, because it's not actually possible for it to ever be None.

Uuid::to_timestamp is now Uuid::get_timestamp

The Uuid::to_timestamp method has been renamed to Uuid::get_timestamp to make it more consistent with Uuid::get_version and Uuid::get_variant.

Changes to formatting methods

The following methods that produce formatting adapters have been renamed:

Uuid::to_hyphenated -> Uuid::hyphenated

Uuid::to_simple -> Uuid::simple

Uuid::to_urn -> Uuid::urn

The following types have been removed:

HyphenatedRef

SimpleRef

UrnRef

The following methods have been changed to return a &<AdapterType> instead of an <AtapterType>Ref:

Uuid::to_hyphenated_ref -> Uuid::as_hyphenated

Uuid::to_simple_ref -> Uuid::as_simple

Uuid::to_urn_ref -> Uuid::as_urn

Builder method consistency

The Builder::build method has been renamed to Builder::into_uuid, to complement the <AdapterType>::into_uuid methods. It also gets an equivalent Builder::as_uuid method.

Version and Variant are non-exhaustive

The #[non_exhaustive] attribute has been added to Version and Variant. There are already active proposals for new UUID versions, so these are likely to continue evolving in the future.

Removed winapi support

The Uuid::to_guid and Uuid::from_guid methods have been removed. This was done for two reasons:

We need to avoid unstable winapi types in the stable uuid public API.

Whether or not GUID fields need to be flipped to convert into a UUID depends on the source of the GUID, so we can't really offer a single pair of methods to convert a GUID into a UUID.

There are some examples in the repository root that demonstrate how to convert GUIDs into UUIDs as a replacement.

Building with --all-features

Now that uuid includes unstable features, if you're building with --all-features (such as in package manager scenarios), you'll also need to pass RUSTFLAGS="--cfg uuid_unstable", or you'll end up with compilation errors. If this strategy becomes problematic for users we can change unstable features to silently no-op instead of cause compilation failures if the corresponding cfg is not also supplied. Please reach out if that affects you!

Stability commitment

Once uuid releases 1.0 we'll try to stay on that version "forever". There won't be a 2.0 unless there's a very compelling need for it. That means you should feel safe depending on Uuid in the public API of your libraries if you want to.
Source code(tar.gz)
Source code(zip)
0.8.2(Jan 11, 2021)
This release includes a large number of internal refactorings and changes to dependencies.

The 0.8.x releases are now tracked on the 0.8.x branch of uuid. The main branch now contains breaking changes.

Contributions

Update md5 to 0.7 (#442)

Use getrandom instead of rand (#447)

Remove dependency on serde_derive (#478)

Add WASI support (#477)

Fix some links in the docs (#471)

Make Uuid #[repr(transparent)] (#468)

Fix the example in the readme (#467)

Clarify documentation around rand crate (#489)

Fix an incorrect date mentioned in the docs (#496)

Update getrandom to 0.2.0 (#501)

Improve deserialization error message (#505)

Update docs on wasm features (#506)

Source code(tar.gz)
Source code(zip)
0.8.1(Oct 18, 2019)
This release doesn't contain any source changes, it fixes up errors in the docs, adds clarification and more examples.

Contributions

Tidy up some docs. (#434)

Source code(tar.gz)
Source code(zip)
0.8.0(Oct 18, 2019)
This release is pretty substantial; it's the accumulation of some 8 months of work. It includes changes to error types, 128bit integer support, explicit endianness and V1 timestamps.

Contributions

#427

#419

#424

#418

#413

#407

#404

#400

#399

#398

#397

#396

#394

#393

#390

#389

#388

Source code(tar.gz)
Source code(zip)
0.7.4(Mar 28, 2019)
Fixes

docs.rs builds now will work properly again. (#385)

Anyone interested can see the entire diff between 0.7.3 and 0.7.4 here.
Source code(tar.gz)
Source code(zip)
0.7.3(Mar 25, 2019)
Added

The uuid::Error error type. This is a sumtype of uuid::BytesError and uuid::ParseError.(#373)

Useful when the underlying uuid version and its error types don't matter until an error occurs.

Add encode_{lower, upper} for the uuid::adapter::{ Hyphenated, Simple, Urn }(#378)

Relatedly, added uuid::Uuid::encode_buffer for the buffer used in the encode_{lower,upper} functions.(#378)

Changes

Remove the rand dependency for v3 and v5 Uuids. (#371)

Anyone interested can see the entire diff between 0.7.2 and 0.7.3 here.
Source code(tar.gz)
Source code(zip)
0.7.2(Jan 29, 2019)
Added

Support for winapi GUIDs, with guid feature (#336, #338)

Introduce Uuid builder interface (#332)

Support for compact serialization of uuid::Uuid and related types with uuid::adapter::compact::{serialize,deserialize) (#331)

use serde_derive's #[serde(with = "uuid::adapter::compact::dense_serde")] you can for your specific case with attributes.

Add support for functions that provide uuids in little endian format (#311)

By default, the internal representation of uuid::Uuids is unspecified.

However all functions returning the bytes are guaranteed to be big endian

Changes

Use hyphenated string instead of a raw bytes for uuid::Uuid Debug output (#360)

Adjust the error message for uuid::parser::Error::InvalidCharacter for clarity. (#355)

Fixes

uuid::Uuid::new_v4 compiles on wasm32 but panics at execution (#351, #358)

Dependencies

md5 from 0.3 to 0.6 (#321, #262)

Anyone interested can see the entire diff between 0.7.1 and 0.7.2 here.
Source code(tar.gz)
Source code(zip)
0.7.1(Sep 14, 2018)
Fixes:

fix up the doc names to follow the name changes (#315)

prelude names are not inlined (#316)

Source code(tar.gz)
Source code(zip)
0.7.0(Sep 7, 2018)
We have a transition guide for moving from uuid 0.6.x to uuid 0.7.x.

Minimum rustc version bumped to 1.22 (#254)

Added

Nil variant to uuid::Version (#181)

Add uuid::Version to prelude (#188)

Allow v3 & v5 Uuids to be constructed from bytes (#270)

BytesError for general Uuid use when byte slices are involved (#284)

Changes

Move namespace Uuid constants under uuid::Uuid (#187)

Use uuid::UuidBytes` instead of [u8;16] (#263)

uuid::Uuid::from_bytes() renamed to uuid::Uuid::from_slice(), uuid::Uuid::from_uuid_bytes() renamed to uuid::Uuid::from_bytes() (#299)

Uuid prefix removed from structs, enums and functions (#294)

Removed

uuid::Uuid::new() method (#214)

Remove deprecated use-std feature (#280)

Dependencies

Rand to 0.5 (#262)

2018 edition is available. To enable it, use the 2018 branch.

Since 0.7.0-beta

fix const_fn marked functions not being const for adapters (#310)

Optimize formatting by 80-90% by avoiding write!. (#303)

Source code(tar.gz)
Source code(zip)
0.7.0-beta(Aug 25, 2018)
Minimum rustc version bumped to 1.22 (#254)

Added:

Nil variant to UuidVersion (#181)

Add UuidVersion to prelude (#188)

support for u128 (#201)

Allow v3 & v5 to be constructed from bytes (#270)

BytesError for general Uuid use (#284)

Changes:

Move namespaces into Uuid::(#187)

Use UuidBytes instead of [u8;16] (#263)

from_bytes renamed to from_slice, from_uuid_bytes renamed to from_bytes (#299)

Uuid Prefix removed from functions (#294)

Removed:

Uuid::new() method (#214)

Remove deprecated use-std feature (#280)

Dependencies:

Rand to 0.5 (#262)

2018 edition is available. To enable it, use the 2018 branch
Source code(tar.gz)
Source code(zip)
0.6.5(May 24, 2018)
Fixes:

Fixes name of the feature in lib.rs (#246)

Source code(tar.gz)
Source code(zip)
0.6.4(May 23, 2018)
Additions:

Const Uuid::from_bytes added (#218)

Backport u128 support (#238)

Dependency Updates:

serde & serde-test to 1.0.56 (#240)

cfg_if fixed to min 0.1.2

Feature Gates:

const_fn feature gate added (#232)

Collaborators:

@jethrogb

@mokeyish

Source code(tar.gz)
Source code(zip)
0.6.3(Apr 15, 2018)
Additions:

UUID Prelude added (#177) (refactored in #193)

Allow compatibility with rust playgrounds - play.integer32.com and play.rust-lang.org (#189)

Refactors:

slog implementation (#185) and test (#182) uuid creation functions moved to seperate modules

Source code(tar.gz)
Source code(zip)
0.6.2(Mar 20, 2018)
Changelog:

from_random_bytes added as a workaround for making rand public (#172)

Other miscellaneous changes (non-public):

copy_memory_function removed and replaced with copy_from_slice (#175)

cfg-if to create logical feature gate implementations (#167)

templates for issues & PRs. So please use them while creating issues/PRs (#162)

Source code(tar.gz)
Source code(zip)
0.6.1(Mar 3, 2018)
adds optional slog::Value impl #158

[BUG-FIX] use_std brought back for backward compatibility #157

Use uuid in your project with uuid="0.6.1" in your Cargo.toml file
Source code(tar.gz)
Source code(zip)
0.6.0(Feb 16, 2018)
Cargo.toml updated to reflect repository changes (#148)

Minimum supported rustc version added (#143)

Update Sha1 dependency to ~~0.5~~ 0.6 (#142 and #146)

UuidV1ClockSequence trait added (#137)

from beta release:

make std default feature (#130 #131)

macro use cleanup (#125)

remove rustc_serialize support (#112)

make rand a private dependency

fix some doc rendering issues

bump sha-1 to 0.4 (#110)

rename use_std to std (#107)

Add tests for compact/readable representations (#105)

Remove use of serde_test (#104)

Add impl fmt::{UpperHex,LowerHex} for {Uuid,Hyphenated,Simple} (#103)

Source code(tar.gz)
Source code(zip)
0.6.0-beta(Feb 7, 2018)
make std default feature (#130 #131)

macro use cleanup (#125)

remove rustc_serialize support (#112)

make rand a private dependency

fix some doc rendering issues

bump sha-1 to 0.4 (#110)

rename use_std to std (#107)

Add tests for compact/readable representations (#105)

Remove use of serde_test (#104)

Add impl fmt::{UpperHex,LowerHex} for {Uuid,Hyphenated,Simple} (#103)

Source code(tar.gz)
Source code(zip)

Generate and parse UUIDs.

Related tags

Overview

uuid

Getting started

Minimum Supported Rust Version (MSRV)

References

License

Contribution

Comments

Description

Motivation

Tests

Related Issue(s)

Manual tests

Description

Motivation

Tests

Related Issue(s)

Description

Motivation

Tests

Related Issue(s)

Description

Releases(1.2.2)

1.2.2(Nov 14, 2022)

What's Changed

1.2.1(Oct 8, 2022)

What's Changed

1.2.0(Oct 8, 2022)

What's Changed

New Contributors

1.1.2(Jun 10, 2022)

What's Changed

New Contributors

1.1.1(May 31, 2022)

What's Changed

New Contributors

1.1.0(May 25, 2022)

What's Changed

New Contributors

1.0.0(Apr 20, 2022)

Changes since the last release

Contributions since the last release

Highlights

Breaking changes

Relocation of adapter::compact

Infallible constructors

Infallible get_variant

Uuid::to_timestamp is now Uuid::get_timestamp

Changes to formatting methods

Builder method consistency

Version and Variant are non-exhaustive

Removed winapi support

Building with --all-features

Stability commitment

1.0.0-alpha.1(Nov 18, 2021)

Changes since the last release

Contributions since the last release

Highlights

Breaking changes

Relocation of adapter::compact

Infallible constructors

Infallible get_variant

Uuid::to_timestamp is now Uuid::get_timestamp

Changes to formatting methods

Builder method consistency

Version and Variant are non-exhaustive

Removed winapi support

Building with --all-features

Stability commitment

0.8.2(Jan 11, 2021)

Contributions

0.8.1(Oct 18, 2019)

Contributions

0.8.0(Oct 18, 2019)

Contributions

0.7.4(Mar 28, 2019)

Fixes

0.7.3(Mar 25, 2019)

`uuid`

Relocation of `adapter::compact`

Infallible `get_variant`

`Uuid::to_timestamp` is now `Uuid::get_timestamp`

`Builder` method consistency

`Version` and `Variant` are non-exhaustive

Removed `winapi` support

Building with `--all-features`

Relocation of `adapter::compact`

Infallible `get_variant`

`Uuid::to_timestamp` is now `Uuid::get_timestamp`

`Builder` method consistency

`Version` and `Variant` are non-exhaustive

Removed `winapi` support

Building with `--all-features`

Since `0.7.0-beta`