Merge pull request #548 from KodrAus/chore/remove-winapi

Remove winapi support in favor of examples

.github/workflows/ci.yml

@@ -55,12 +55,15 @@ jobs:
     - name: Install cargo-hack
       run: cargo install cargo-hack
 
-    - name: Powerset
-      run: cargo hack test --feature-powerset --lib --optional-deps serde --depth 3
-
     - name: Docs
       run: cargo test --all-features --doc
 
+    - name: Examples
+      run: cargo test --all-features --examples
+
+    - name: Powerset
+      run: cargo hack test --feature-powerset --lib --optional-deps serde --depth 3
+
   msrv:
     name: "Tests / MSRV / OS: ${{ matrix.os }}"
     runs-on: ${{ matrix.os }}

Cargo.toml

@@ -33,7 +33,7 @@ repository = "https://github.com/uuid-rs/uuid"
 version = "0.8.1" # remember to update html_root_url in lib.rs
 
 [package.metadata.docs.rs]
-features = [ "guid", "serde", "slog", "v1", "v3", "v4", "v5" ]
+features = [ "serde", "slog", "v1", "v3", "v4", "v5" ]
 default-target = "x86_64-pc-windows-msvc"
 
 [package.metadata.playground]
@@ -54,15 +54,13 @@ repository = "uuid-rs/uuid"
 [features]
 default = ["std"]
 std = []
-macros = ["uuid-macros"]
+macros = ["uuid_macro"]
 
 v1 = ["atomic"]
 v3 = ["md-5"]
 v4 = ["rng"]
 v5 = ["sha-1"]
 
-guid = ["winapi"]
-
 js = ["getrandom", "getrandom/js"]
 
 rng = ["getrandom"]
@@ -100,7 +98,7 @@ optional = true
 version = "0.9"
 
 # Public: Re-expored
-[dependencies.uuid-macros]
+[dependencies.uuid_macro]
 path = "macros"
 optional = true
 
@@ -115,11 +113,6 @@ version = "1.0.56"
 optional = true
 version = "2"
 
-# Public: Used in `From` impls on `Uuid`
-[target.'cfg(windows)'.dependencies.winapi]
-optional = true
-version = "0.3"
-
 # Public (unstable): Used in `zerocopy` derive
 [dependencies.zerocopy]
 optional = true
@@ -149,7 +142,7 @@ version = "1.0.52"
 
 [target.'cfg(windows)'.dev-dependencies.winapi]
 version = "0.3"
-features = ["combaseapi"]
+features = ["combaseapi", "impl-default"]
 
 [workspace]
 members = [

README.md

@@ -51,6 +51,18 @@ let my_uuid = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8")?;
 assert_eq!(Some(Version::Random), my_uuid.get_version());
 ```
 
+If you add the `macros` feature then you can parse UUIDs at compile time
+instead of at runtime:
+
+```rust
+#[macro_use]
+extern crate uuid;
+
+let my_uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8")?;
+
+assert_eq!(Some(Version::Random), my_uuid.get_version());
+```
+
 ## Dependencies
 
 By default, this crate depends on nothing but `std` and cannot generate
@@ -66,6 +78,7 @@ various pieces of functionality:
   generate a `Uuid`.
 * `v5` - adds the `Uuid::new_v5` function and the ability to create a V5
   UUID based on the SHA1 hash of some data.
+* `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.
 * `fast-rng` - when combined with `v4` uses a faster algorithm for generating

benches/macros/renamed.rs

@@ -8,4 +8,4 @@ struct Uuid;
 
 const _: Id = id!("67e55044-10b1-426f-9247-bb680e5fe0c8");
 
-fn main() {}
+fn main() {}

benches/parse_str.rs

@@ -56,4 +56,4 @@ fn test_valid_macro() {
     t.pass("benches/macros/valid_parse.rs");
     t.pass("benches/macros/renamed.rs");
     t.compile_fail("benches/macros/invalid_parse.rs");
-}
+}

examples/random_uuid.rs

@@ -0,0 +1,15 @@
+//! Generating a random UUID.
+//!
+//! If you enable the `v4` feature you can generate random UUIDs.
+
+#[test]
+#[cfg(feature = "v4")]
+fn generate_random_uuid() {
+    use uuid::Uuid;
+
+    let uuid = Uuid::new_v4();
+
+    assert_eq!(Some(uuid::Version::Random), uuid.get_version());
+}
+
+fn main() {}

examples/uuid_macro.rs

@@ -0,0 +1,18 @@
+//! Using the `uuid!` macro.
+//!
+//! If you enable the `macros` feature you can use the `uuid!` macro.
+//! `uuid!` will parse encoded UUIDs at compile time instead of at runtime.
+//! If you've got a fixed UUID string handy then consider using `uuid!` instead
+//! of `Uuid::parse_str` or `str::parse`.
+
+#[test]
+#[cfg(feature = "macros")]
+fn parse_uuid_at_compile_time() {
+    use uuid::uuid;
+
+    let uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");
+
+    assert_eq!(Some(uuid::Version::Random), uuid.get_version());
+}
+
+fn main() {}

examples/windows_guid.rs

@@ -0,0 +1,74 @@
+//! Converting between Windows GUIDs and UUIDs.
+//!
+//! Windows GUIDs are specified as using mixed endianness.
+//! What you get will depend on the source of the GUID.
+//! Functions like `CoCreateGuid` will generate a valid UUID so
+//! the fields will be naturally ordered for `Uuid::from_fields`.
+//! Other GUIDs might need to be passed to `Uuid::from_fields_le`
+//! to have their ordering swapped.
+
+#[test]
+#[cfg(windows)]
+fn guid_to_uuid() {
+    use uuid::Uuid;
+    use winapi::shared::guiddef;
+
+    let guid_in = guiddef::GUID {
+        Data1: 0x4a35229d,
+        Data2: 0x5527,
+        Data3: 0x4f30,
+        Data4: [0x86, 0x47, 0x9d, 0xc5, 0x4e, 0x1e, 0xe1, 0xe8],
+    };
+
+    let uuid = Uuid::from_fields(
+        guid_in.Data1,
+        guid_in.Data2,
+        guid_in.Data3,
+        &guid_in.Data4,
+    );
+
+    let guid_out = {
+        let fields = uuid.as_fields();
+
+        guiddef::GUID {
+            Data1: fields.0,
+            Data2: fields.1,
+            Data3: fields.2,
+            Data4: *fields.3,
+        }
+    };
+
+    assert_eq!(
+        (guid_in.Data1, guid_in.Data2, guid_in.Data3, guid_in.Data4),
+        (
+            guid_out.Data1,
+            guid_out.Data2,
+            guid_out.Data3,
+            guid_out.Data4
+        )
+    );
+}
+
+#[test]
+#[cfg(windows)]
+fn uuid_from_cocreateguid() {
+    use uuid::{Uuid, Variant, Version};
+    use winapi::{
+        shared::guiddef,
+        um::combaseapi::CoCreateGuid,
+    };
+
+    let mut guid = guiddef::GUID::default();
+
+    unsafe {
+        CoCreateGuid(&mut guid as *mut _);
+    }
+
+    let uuid =
+        Uuid::from_fields(guid.Data1, guid.Data2, guid.Data3, &guid.Data4);
+
+    assert_eq!(Variant::RFC4122, uuid.get_variant());
+    assert_eq!(Some(Version::Random), uuid.get_version());
+}
+
+fn main() {}

macros/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "uuid-macros"
+name = "uuid_macro"
 version = "0.0.0"
 edition = "2018"
 

macros/src/lib.rs

@@ -1,3 +1,13 @@
+//! Implementation details for the `uuid!` macro.
+//!
+//! This crate is not meant to be used directly. Instead,
+//! you can use the `macros` feature of `uuid`:
+//!
+//! ```toml
+//! [dependencies.uuid]
+//! features = ["macros"]
+//! ```
+
 use proc_macro::TokenStream;
 use proc_macro2::TokenStream as TokenStream2;
 use quote::{quote, quote_spanned};
@@ -19,6 +29,7 @@ mod error;
 mod parser;
 
 #[proc_macro]
+#[doc(hidden)]
 pub fn parse_lit(input: TokenStream) -> TokenStream {
     build_uuid(input.clone()).unwrap_or_else(|e| {
         let msg = e.to_string();

src/lib.rs

@@ -40,6 +40,7 @@
 //!   generate a UUID.
 //! * `v5` - adds the [`Uuid::new_v5`] function and the ability to create a V5
 //!   UUID based on the SHA1 hash of some data.
+//! * `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.
 //! * `fast-rng` - when combined with `v4` uses a faster algorithm for
@@ -209,14 +210,12 @@ mod rng;
 mod serde_support;
 #[cfg(feature = "slog")]
 mod slog_support;
-#[cfg(all(windows, feature = "winapi"))]
-mod winapi_support;
 
 #[cfg(feature = "macros")]
 #[macro_use]
 mod macros;
 #[cfg(feature = "macros")]
-pub extern crate uuid_macros;
+pub extern crate uuid_macro;
 
 use crate::std::convert;
 
@@ -936,10 +935,8 @@ mod tests {
         check!(buf, "{:X}", u, 36, |c| c.is_uppercase()
             || c.is_digit(10)
             || c == '-');
-        check!(buf, "{:#x}", u, 32, |c| c.is_lowercase()
-            || c.is_digit(10));
-        check!(buf, "{:#X}", u, 32, |c| c.is_uppercase()
-            || c.is_digit(10));
+        check!(buf, "{:#x}", u, 32, |c| c.is_lowercase() || c.is_digit(10));
+        check!(buf, "{:#X}", u, 32, |c| c.is_uppercase() || c.is_digit(10));
 
         check!(buf, "{:X}", u.to_hyphenated(), 36, |c| c.is_uppercase()
             || c.is_digit(10)

src/macros.rs

@@ -1,42 +1,57 @@
 /// Parse [`Uuid`][uuid::Uuid]s from string literals at compile time.
+///
 /// ## Usage
+///
 /// This macro transforms the string literal representation of a
 /// [`Uuid`][uuid::Uuid] into the bytes representation, raising a compilation
 /// error if it cannot properly be parsed.
 ///
 /// ## Examples
+///
 /// Setting a global constant:
+///
 /// ```
 /// # use uuid::{uuid, Uuid};
 /// pub const SCHEMA_ATTR_CLASS: Uuid = uuid!("00000000-0000-0000-0000-ffff00000000");
 /// pub const SCHEMA_ATTR_UUID: Uuid = uuid!("00000000-0000-0000-0000-ffff00000001");
 /// pub const SCHEMA_ATTR_NAME: Uuid = uuid!("00000000-0000-0000-0000-ffff00000002");
 /// ```
+///
 /// Defining a local variable:
+///
 /// ```
 /// # use uuid::{uuid, Uuid};
 /// let uuid: Uuid = uuid!("urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4");
 /// ```
+///
 /// ## Compilation Failures
+///
 /// Invalid UUIDs are rejected:
-/// ```ignore
+///
+/// ```compile_fail
 /// # use uuid::{uuid, Uuid};
 /// let uuid: Uuid = uuid!("F9168C5E-ZEB2-4FAA-B6BF-329BF39FA1E4");
 /// ```
+///
 /// Provides the following compilation error:
+///
 /// ```txt
 /// error: invalid character: expected an optional prefix of `urn:uuid:` followed by 0123456789abcdefABCDEF-, found Z at 9
 ///     |
 ///     |     let id: Uuid = uuid!("F9168C5E-ZEB2-4FAA-B6BF-329BF39FA1E4");
 ///     |                                    ^
 /// ```
+///
 /// Tokens that aren't string literals are also rejected:
-/// ```ignore
+///
+/// ```compile_fail
 /// # use uuid::{uuid, Uuid};
 /// let uuid_str: &str = "550e8400e29b41d4a716446655440000";
 /// let uuid: Uuid = uuid!(uuid_str);
 /// ```
+///
 /// Provides the following compilation error:
+///
 /// ```txt
 /// error: expected string literal
 ///   |
@@ -48,6 +63,6 @@
 #[macro_export]
 macro_rules! uuid {
     ($uuid:tt) => {{
-        $crate::Uuid::from_bytes($crate::uuid_macros::parse_lit!($uuid))
+        $crate::Uuid::from_bytes($crate::uuid_macro::parse_lit!($uuid))
     }};
 }