Prepare for 1.0.0-alpha.1 release

[KodrAus]

Part of #113

This PR gets us ready for an alpha release of uuid 1.0 that can be used to ensure everything is good in downstream consumers. Ideally we won't make any API changes before actually stabilizing 1.0 proper, but some things may come up that need additional breaking alpha releases.

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

0.8.2...main

Contributions since the last release

• Add impl AsRef<[u8]> for Uuid #510
• Allow access of inner Uuid for Hyphenated, Simple, Urn #482
• Allow access of inner Uuid for adapters #511
• Use TryInto to avoid unsafe. #507
• Added support for converting u64 pair into UUID and back #518
• Upgrade to GitHub-native Dependabot #519
• Allow v3, v4, v5 features on wasm32-unknown-unknown #512
• Update mod.rs #520
• Update Uuid::new_v4 documentation to reflect Try no longer being implemented #521
• add more ci for wasm and embedded targets #525
• Update dependencies for sha-1 and md-5 #526
• Add more docs on endianness #527
• check more features in no-std #528
• Make more things const #535
• Make ctors that accept slices infallible using arrays and other breaking changes #536
• Fix typo in v4.rs #539
• Add unstable zerocopy support #538
• Don't flip GUID fields when converting to UUID #540
• Scaffold out a uuid-macros crate that shares the parser #541
• Rename to_timestamp to get_timestamp #542
• More housekeeping before stabilization #544
• Add support for using rand for rng #545
• More serde and parsing impls #546
• Impl UUID macro #543
• Only increment v1 context when the seconds component matches #547
• Remove winapi support in favor of examples #548
• Move ui tests into dedicated directories #549
• Add optional arbitrary impl #550
• Add support for parsing UUIDs between braces #552
• Fixed uuid!("") macro diagnostics when using urn:uuid prefix. #554
• Make conversion methods consistent across the API #558
• Improved parser & diagnostics #560
• Improve try_parse and encode performance #562
• Add some inline comments to the new parser impl #563
• Revert default compact serialization #564
• some small doc cleanups #565
• Provide uuid macro without dependencies #566

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've got two options for compile-time UUIDs:

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.

[KodrAus]

Just cross-posting a comment from Reddit on the change to serde:

For some serialization formats, byte array is more efficient per element than seq. Tuple is similar to seq, except it has known length. For example, consider a format where each element has one byte overhead, where tuple would thus cost 2*16 bytes instead of 1+16 bytes for byte array.

https://www.reddit.com/r/rust/comments/qksulj/comment/hizps4r/

reddit

Getting ready for uuid 1.0

I don't understand the serde change. Which type of the serde data model does a uuid map to now, if not `byte array [u8]`? A `tuple` with 16...

[Dylan-DPC-zz]

How about bumping the edition to 2021 (in a separate PR)? I know there won't be much changes but I think its better to keep it to the latest edition.

…

On Tue, 2 Nov 2021 11:27 Ashley Mannix, ***@***.***> wrote: Just cross-posting a comment from Reddit on the change to serde: For some serialization formats, byte array is more efficient per element than seq. Tuple is similar to seq, except it has known length. For example, consider a format where each element has one byte overhead, where tuple would thus cost 2*16 bytes instead of 1+16 bytes for byte array. https://www.reddit.com/r/rust/comments/qksulj/comment/hizps4r/ <https://camo.githubusercontent.com/a4fa7f4594e0a03053290995bcd6501f6f57fdd60ac98a56f2476a296f42ca36/68747470733a2f2f7777772e7265646469747374617469632e636f6d2f6e65772d69636f6e2e706e67> reddit *Getting ready for uuid 1.0 <https://www.reddit.com/r/rust/comments/qksulj/comment/hizps4r/>* I don't understand the serde change. Which type of the serde data model does a uuid map to now, if not `byte array [u8]`? A `tuple` with 16... — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#553 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AC6MJNPH3BDKWABTDZIABALUJ64KHANCNFSM5HFIDH3Q> .

[mitsuhiko]

I think the serde change is not positive. It's untypical, generally serde hasn't been used like this and it's going to break a lot of formats. I'm also not convinced that u128 is a better solution here. Does the length information cause a problem in practice that it's worth considering going out of the way to do something untypical here?

[KodrAus]

@mitsuhiko I've opened #557 that we can use to try come to some resolution. We won't be shipping any builds with a changed serde implementation until we do.

[KodrAus]

The change to the default serialization format has been reverted, so Uuid will continue to serialize using byte slices as it currently does.

[KodrAus]

I think we've been through and over the feedback that came in from the community, so the last thing to do is a final pass over the API to make sure nothing's been missed. I've done this myself, but would appreciate any more eyes on it! You can use:

RUSTDOCFLAGS="--cfg uuid_unstable" cargo doc --all-features --open

to explore the complete public API.

Resolved

[KodrAus]

cc @kinggoesgaming how is everything looking to you now?

[kinggoesgaming]

@KodrAus Following the current activity on repo, this should be good.

Will have a look in the morning through the entire codebase just to see if there is anything that was missed out.

[kinggoesgaming]

@KodrAus I think all is good for the first alpha release.

[KodrAus]

Thanks for reviewing this @kinggoesgaming!