Skip to content

Commit

Permalink
Merge pull request #565 from KodrAus/chore/doc-cleanups
Browse files Browse the repository at this point in the history
some small doc cleanups
  • Loading branch information
KodrAus authored Nov 16, 2021
2 parents a1df52a + 3b705af commit 27fc858
Show file tree
Hide file tree
Showing 5 changed files with 66 additions and 39 deletions.
2 changes: 1 addition & 1 deletion shared/parser.rs
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ const fn parse_hyphenated(s: &[u8]) -> Result<[u8; 16], ()> {
// We look at two hex-encoded values (4 chars) at a time because
// that's the size of the smallest group in a hyphenated UUID.
// The indexes we're interested in are:
//
//
// uuid : 936da01f-9abd-4d9d-80c7-02af85c822a8
// | | || || || || | |
// hyphens : | | 8| 13| 18| 23| | |
Expand Down
8 changes: 4 additions & 4 deletions src/builder.rs
Original file line number Diff line number Diff line change
Expand Up @@ -208,12 +208,12 @@ impl Uuid {
///
/// ```
/// # use uuid::Uuid;
/// let v = 0xd8d7d6d5d4d3d2d1c2c1b2b1a4a3a2a1u128;
/// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
///
/// let uuid = Uuid::from_u128_le(v);
///
/// assert_eq!(
/// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
/// "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
/// uuid.hyphenated().to_string(),
/// );
/// ```
Expand Down Expand Up @@ -690,12 +690,12 @@ impl Builder {
///
/// ```
/// # use uuid::Builder;
/// let v = 0xd8d7d6d5d4d3d2d1c2c1b2b1a4a3a2a1u128;
/// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
///
/// let uuid = Builder::from_u128_le(v).into_uuid();
///
/// assert_eq!(
/// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
/// "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
/// uuid.hyphenated().to_string(),
/// );
/// ```
Expand Down
24 changes: 10 additions & 14 deletions src/fmt.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! Adapters for various formats for UUIDs
//! Adapters for alternative string formats.

use crate::{
std::{borrow::Borrow, fmt, str, ptr},
std::{borrow::Borrow, fmt, ptr, str},
Uuid, Variant,
};

Expand Down Expand Up @@ -61,36 +61,32 @@ impl fmt::UpperHex for Uuid {
}
}

/// An adapter for formatting an [`Uuid`] as a hyphenated string.
///
/// Takes an owned instance of the [`Uuid`].
/// Format a [`Uuid`] as a hyphenated string, like
/// `67e55044-10b1-426f-9247-bb680e5fe0c8`.
///
/// [`Uuid`]: ../struct.Uuid.html
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[repr(transparent)]
pub struct Hyphenated(Uuid);

/// An adapter for formatting an [`Uuid`] as a simple string.
///
/// Takes an owned instance of the [`Uuid`].
/// Format a [`Uuid`] as a simple string, like
/// `67e5504410b1426f9247bb680e5fe0c8`.
///
/// [`Uuid`]: ../struct.Uuid.html
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[repr(transparent)]
pub struct Simple(Uuid);

/// An adapter for formatting an [`Uuid`] as a URN string.
///
/// Takes an owned instance of the [`Uuid`].
/// Format a [`Uuid`] as a URN string, like
/// `urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8`.
///
/// [`Uuid`]: ../struct.Uuid.html
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[repr(transparent)]
pub struct Urn(Uuid);

/// An adapter for formatting an [`Uuid`] as a braced hyphenated string.
///
/// Takes an owned instance of the [`Uuid`].
/// Format a [`Uuid`] as a braced hyphenated string, like
/// `{67e55044-10b1-426f-9247-bb680e5fe0c8}`.
///
/// [`Uuid`]: ../struct.Uuid.html
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
Expand Down
66 changes: 49 additions & 17 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,17 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! Generate and parse UUIDs.
//! Generate and parse universally unique identifiers (UUIDs).
//!
//! Provides support for Universally Unique Identifiers (UUIDs). A UUID is a
//! unique 128-bit number, stored as 16 octets. UUIDs are used to assign
//! unique identifiers to entities without requiring a central allocating
//! authority.
//! Here's an example of a UUID:
//!
//! ```text
//! 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
Expand All @@ -25,25 +30,51 @@
//! practical purposes, it can be assumed that an unintentional collision would
//! be extremely unlikely.
//!
//! # Getting started
//!
//! Add the following to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! uuid = { version = "0.8", features = ["v4"] }
//! ```
//!
//! When you want a UUID, you can generate one:
//!
//! ```
//! # fn main() {
//! # #[cfg(feature = "v4")]
//! # {
//! use uuid::Uuid;
//!
//! let id = Uuid::new_v4();
//! # }
//! # }
//! ```
//!
//! # Dependencies
//!
//! By default, this crate depends on nothing but `std` and cannot generate
//! UUIDs. You need to enable the following Cargo features to enable
//! various pieces of functionality:
//! By default, this crate depends on nothing but `std` and can parse and format
//! UUIDs, but cannot generate them. You need to enable the following Cargo
//! features to enable various pieces of functionality:
//!
//! * `v1` - adds the [`Uuid::new_v1`] function and the ability to create a V1
//! using an implementation of [`v1::ClockSequence`] (usually
//! [`v1::Context`]) and a timestamp from `time::timespec`.
//! UUID using an implementation of [`v1::ClockSequence`] (usually
//! [`v1::Context`]) and a UNIX timestamp.
//! * `v3` - adds the [`Uuid::new_v3`] function and the ability to create a V3
//! UUID based on the MD5 hash of some data.
//! * `v4` - adds the [`Uuid::new_v4`] function and the ability to randomly
//! 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.
//! * `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid`.
//!
//! Other crate features can also be useful beyond the version support:
//!
//! * `macros` - adds the `uuid!` macro that can parse UUIDs from string literals at compile time.
//! * `serde` - adds the ability to serialize and deserialize a UUID using
//! `serde`.
//! * `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid` for
//! fuzzing.
//! * `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.
Expand Down Expand Up @@ -100,7 +131,7 @@
//! ```
//!
//! You don't need the `js` feature to use `uuid` in WebAssembly if you're
//! not enabling other features too.
//! not also enabling `v4`.
//!
//! ## Embedded
//!
Expand All @@ -112,7 +143,7 @@
//! uuid = { version = "0.8", default-features = false }
//! ```
//!
//! Some additional features are supported in no-std environments:
//! Some additional features are supported in no-std environments though:
//!
//! * `v1`, `v3`, and `v5`
//! * `serde`
Expand Down Expand Up @@ -213,6 +244,7 @@ mod external;
#[cfg(feature = "macros")]
#[macro_use]
mod macros;
#[doc(hidden)]
#[cfg(feature = "macros")]
pub extern crate uuid_macro;

Expand Down Expand Up @@ -746,7 +778,7 @@ impl AsRef<[u8]> for Uuid {

#[cfg(feature = "serde")]
pub mod serde {
//! Adapters for `serde`.
//! Adapters for alternative `serde` formats.
//!
//! This module contains adapters you can use with [`#[serde(with)]`](https://serde.rs/field-attrs.html#with)
//! to change the way a [`Uuid`](../struct.Uuid.html) is serialized
Expand Down
5 changes: 2 additions & 3 deletions src/v1.rs
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ impl Uuid {
/// is seeded with a random value:
///
/// ```rust
/// use uuid::v1::{Timestamp, Context};
/// # use uuid::v1::{Timestamp, Context};
/// # use uuid::Uuid;
/// # fn random_seed() -> u16 { 42 }
/// let context = Context::new(random_seed());
Expand All @@ -183,9 +183,8 @@ impl Uuid {
/// The timestamp can also be created manually as per RFC4122:
///
/// ```
/// use uuid::v1::{Timestamp, Context};
/// # use uuid::v1::{Timestamp, Context};
/// # use uuid::Uuid;
///
/// let context = Context::new(42);
/// let ts = Timestamp::from_rfc4122(1497624119, 0);
///
Expand Down

0 comments on commit 27fc858

Please sign in to comment.