Merge pull request #550 from KodrAus/feat/arbitrary

Add optional arbitrary impl

.github/ISSUE_TEMPLATE/Bug_report.md

@@ -4,28 +4,21 @@ about: Create a report to help us improve
 
 ---
 
-**Describe the bug**
+**What happened?**
 A clear and concise description of what the bug is.
 
-**To Reproduce**
 Steps to reproduce the behavior:
 1. ...
 2. ...
 3. ...
 
-**Expected behavior**
+**What were you expecting?**
 A clear and concise description of what you expected to happen.
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+**What's the context?**
+- Target (`rustc --version`)
+- Version (e.g. `1.0`)
+- Cargo features enabled
 
-**Specifications (please complete the following information):**
-- Target
-- Version [e.g. 1.0]
-- Features Enabled
-
-**Additional context**
-Add any other context about the problem here.
-
-**Other**
+**Anything else?**
 Other information like relevant issues, external links, etc

.github/ISSUE_TEMPLATE/Feature_request.md

@@ -1,23 +1,20 @@
 ---
 name: Feature request
-about: Suggest an idea for this project
+about: Suggest an idea for UUID
 
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+**Motivation**
+A clear and concise description of what the problem is.
 
-**Describe the solution you'd like**
+**Solution**
 A clear and concise description of what you want to happen.
 
-**Is it blocking?**
-Is this issue blocking any of your work? If it is blocking any open source project, you can share the link of the issue
-
-**Describe alternatives you've considered**
+**Alternatives**
 A clear and concise description of any alternative solutions or features you've considered.
 
-**Additional context**
-Add any other context or screenshots about the feature request here.
+**Is it blocking?**
+Is this issue blocking any of your work? If it is blocking any open source project, you can share the link of the issue
 
-**Other**
+**Anything else?**
 Other information like relevant issues, external links, etc

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,16 +1,5 @@
-<!--
-    If this PR is a breaking change, ensure that you are opening it against 
-    the `breaking` branch.  If the pull request is incomplete, prepend the Title with WIP: 
--->
-
 **I'm submitting a(n)** (bug fix|deprecation|feature|refactor|removal|other)
 
-
 # Description
 
-# Motivation
-
-# Tests
-<!-- How are these changes tested? -->
-
 # Related Issue(s)

.github/workflows/ci.yml

@@ -62,7 +62,7 @@ jobs:
       run: cargo test --all-features --examples
 
     - name: Powerset
-      run: cargo hack test --feature-powerset --lib --optional-deps serde --depth 3
+      run: cargo hack test --feature-powerset --lib --optional-deps "serde arbitrary" --depth 3
 
   msrv:
     name: "Tests / MSRV / OS: ${{ matrix.os }}"

CONTRIBUTING.md

@@ -12,8 +12,7 @@ Thank you for your interest in contributing to the Uuid Project!
 * [Out-of-tree Contributions](#out-of-tree-contributions)
 * [Helpful Links](#helpful-links)
 
-For any questions, please make a post on [users.rust-lang.org][u-r-l-o], post
-on [uuid-rs mailing list] or join our [gitter] channel.
+For any questions, please make a post on [Discussions] or [users.rust-lang.org][u-r-l-o].
 
 > All contributors need to follow our [Code of Conduct].
 
@@ -22,10 +21,9 @@ on [uuid-rs mailing list] or join our [gitter] channel.
 # Feature Requests
 [Feature Requests]: #feature-requests
 
-The `uuid` crate is still in flux. All features desired may not be present. As
-such you are welcome to request for new features. Keep in mind that `uuid` is
-a general purpose library. We want to provide features that most users would
-find useful. As such not every feature may be accepted.
+The `uuid` crate is stable so features that require breaking changes can't be
+accepted. There are bound to be usability gaps that can be filled with non-breaking
+features though!
 
 If you have the chance, please [search existing issues], as there is a chance
 that someone has already requested your feature.
@@ -36,8 +34,17 @@ your request.
 You can request your feature by following [this link][Feature Request Link] and
 filling it in. 
 
-> We welcome pull requests for your own feature requests, provided they have
-been discussed.
+> We welcome pull requests for your own feature requests. Discussion should stay
+on the relevant issue to make it easier to find.
+
+## Adding new unstable dependencies
+
+If a feature introduces a new unstable dependency then it needs to be private.
+That means traits and types from the unstable library can't be visible in `uuid`'s
+own public API.
+
+To implement unstable traits, see the precedent set by the `zerocopy-unstable` feature.
+It implements a public unstable trait on `Uuid`, but uses the `uuid_unstable` cfg flag.
 
 [Feature Request Link]: https://github.com/uuid-rs/uuid/issues/new?template=Feature_request.md
 
@@ -82,12 +89,6 @@ patches), we require PRs to relevant issues.
 
 Please open PRs against the `main` branch.
 
-If the pull request is still a work in progress, prepend`[WIP] ` in your 
-title. `WIP bot` will make sure that the PR doesn't accidentally get merged.
-
-> Uuid Project has a minimum rust version policy. Currently `uuid` should 
-compile with at least `1.22.0`, and is enforced on our CI builds.
-
 When you feel that the PR is ready, please ping one of the maintainers so
 they can review your changes.
 
@@ -117,18 +118,6 @@ You can follow [this link][lrus] to look for issues like this.
 
 [lrus]: https://github.com/uuid-rs/uuid/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
 
-# Out-of-tree Contributions
-[Out-of-tree Contributions]: #out-of-tree-contributions
-
-You can contribute to Uuid in other ways:
-
-* Answer questions on [users.rust-lang.org][u-r-l-o], [uuid-rs mailing list] and/or
-[gitter] channel.
-* Find the [crates depending on `uuid`][dependent] and sending PRs to them,
-helping them keep their version of `uuid` up-to-date.
-
-[dependent]: https://crates.io/crates/uuid/reverse_dependencies
-
 # Helpful Links
 [Helpful Links]: #helpful-links
 
@@ -142,6 +131,5 @@ seasoned developers, some useful places to look for information are:
 [RFC 4122]: https://www.ietf.org/rfc/rfc4122.txt
 
 [u-r-l-o]: https://users.rust-lang.org
-[uuid-rs mailing list]: https://uuid-rs.groups.io
-[gitter]: https://gitter.im/uuid-rs/Lobby
+[Discussions]: https://github.com/uuid-rs/uuid/discussions
 [search existing issues]: https://github.com/uuid-rs/uuid/search?q=&type=Issues&utf8=%E2%9C%93

Cargo.toml

@@ -97,7 +97,7 @@ default-features = false
 optional = true
 version = "0.9"
 
-# Public: Re-expored
+# Public: Re-exported
 [dependencies.uuid_macro]
 path = "macros"
 optional = true
@@ -113,6 +113,11 @@ version = "1.0.56"
 optional = true
 version = "2"
 
+# Public: Used in trait impls on `Uuid`
+[dependencies.arbitrary]
+optional = true
+version = "1"
+
 # Public (unstable): Used in `zerocopy` derive
 [dependencies.zerocopy]
 optional = true

README.md

@@ -81,6 +81,7 @@ various pieces of functionality:
 * `macros` - adds the `uuid!` macro that can parse UUIDs at compile time.
 * `serde` - adds the ability to serialize and deserialize a `Uuid` using the
   `serde` crate.
+* `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid`.
 * `fast-rng` - when combined with `v4` 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.

examples/windows_guid.rs

@@ -53,10 +53,7 @@ fn guid_to_uuid() {
 #[cfg(windows)]
 fn uuid_from_cocreateguid() {
     use uuid::{Uuid, Variant, Version};
-    use winapi::{
-        shared::guiddef,
-        um::combaseapi::CoCreateGuid,
-    };
+    use winapi::{shared::guiddef, um::combaseapi::CoCreateGuid};
 
     let mut guid = guiddef::GUID::default();
 

src/external/arbitrary_support.rs

@@ -0,0 +1,43 @@
+use crate::{std::convert::TryInto, Builder, Uuid};
+
+use arbitrary::{Arbitrary, Unstructured};
+
+impl Arbitrary<'_> for Uuid {
+    fn arbitrary(u: &mut Unstructured<'_>) -> arbitrary::Result<Self> {
+        let b = u
+            .bytes(16)?
+            .try_into()
+            .map_err(|_| arbitrary::Error::NotEnoughData)?;
+
+        Ok(Builder::from_random_bytes(b).into_uuid())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::{Variant, Version};
+
+    #[test]
+    fn test_arbitrary() {
+        let mut bytes = Unstructured::new(&[
+            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+        ]);
+
+        let uuid = Uuid::arbitrary(&mut bytes).unwrap();
+
+        assert_eq!(Some(Version::Random), uuid.get_version());
+        assert_eq!(Variant::RFC4122, uuid.get_variant());
+    }
+
+    #[test]
+    fn test_arbitrary_empty() {
+        let mut bytes = Unstructured::new(&[]);
+
+        // Ensure we don't panic when building an arbitrary `Uuid`
+        let uuid = Uuid::arbitrary(&mut bytes);
+
+        assert!(uuid.is_err());
+    }
+}

src/external/mod.rs

@@ -0,0 +1,6 @@
+#[cfg(feature = "arbitrary")]
+mod arbitrary_support;
+#[cfg(feature = "serde")]
+mod serde_support;
+#[cfg(feature = "slog")]
+mod slog_support;

src/lib.rs

@@ -43,6 +43,7 @@
 //! * `macros` - adds the `uuid!` macro that can parse UUIDs at compile time.
 //! * `serde` - adds the ability to serialize and deserialize a UUID using the
 //!   `serde` crate.
+//! * `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid`.
 //! * `fast-rng` - when combined with `v4` 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.
@@ -206,10 +207,8 @@ mod v5;
 
 #[cfg(feature = "rng")]
 mod rng;
-#[cfg(feature = "serde")]
-mod serde_support;
-#[cfg(feature = "slog")]
-mod slog_support;
+
+mod external;
 
 #[cfg(feature = "macros")]
 #[macro_use]