itsscb/uuid
1
0
Fork 0
mirror of https://github.com/uuid-rs/uuid.git synced 2025-09-29 22:10:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #527 from KodrAus/chore/endianness

Browse Source 
Add more docs on endianness
This commit is contained in:
Ashley Mannix 2021-08-13 18:16:09 +10:00 committed by GitHub
commit d25b2878df
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 48 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
src/builder/mod.rs
View File

@ -44,7 +44,7 @@ impl Uuid {
Uuid::from_bytes([0; 16])
}
/// Creates a UUID from four field values in big-endian order.
/// Creates a UUID from four field values.
///
/// # Errors
///
@ -103,8 +103,10 @@ impl Uuid {
/// Creates a UUID from four field values in little-endian order.
///
/// The bytes in the `d1`, `d2` and `d3` fields will
/// be converted into big-endian order.
/// The bytes in the `d1`, `d2` and `d3` fields will be flipped to convert
/// into big-endian order. This is based on the endianness of the UUID,
/// rather than the target environment so bytes will be flipped on both
/// big and little endian machines.
///
/// # Examples
///
@ -158,7 +160,7 @@ impl Uuid {
]))
}
/// Creates a UUID from a 128bit value in big-endian order.
/// Creates a UUID from a 128bit value.
pub const fn from_u128(v: u128) -> Self {
Uuid::from_bytes([
(v >> 120) as u8,
@ -181,6 +183,11 @@ impl Uuid {
}
/// Creates a UUID from a 128bit value in little-endian order.
///
/// The entire value will be flipped to convert into big-endian order.
/// This is based on the endianness of the UUID, rather than the target
/// environment so bytes will be flipped on both big and little endian
/// machines.
pub const fn from_u128_le(v: u128) -> Self {
Uuid::from_bytes([
v as u8,
@ -202,7 +209,7 @@ impl Uuid {
])
}
/// Creates a UUID from two 64bit values in big-endian order.
/// Creates a UUID from two 64bit values.
pub const fn from_u64_pair(high_bits: u64, low_bits: u64) -> Self {
Uuid::from_bytes([
(high_bits >> 56) as u8,
@ -224,7 +231,7 @@ impl Uuid {
])
}
/// Creates a UUID using the supplied big-endian bytes.
/// Creates a UUID using the supplied bytes.
///
/// # Errors
///
@ -273,7 +280,7 @@ impl Uuid {
Ok(Uuid::from_bytes(bytes))
}
/// Creates a UUID using the supplied big-endian bytes.
/// Creates a UUID using the supplied bytes.
pub const fn from_bytes(bytes: Bytes) -> Uuid {
Uuid(bytes)
}
@ -298,13 +305,9 @@ impl Uuid {
/// .set_version(Version::Random)
/// .build();
/// ```
// TODO: remove in 1.0.0
#[allow(dead_code)]
#[deprecated]
pub type Builder = crate::Builder;
impl crate::Builder {
/// Creates a `Builder` using the supplied big-endian bytes.
/// Creates a `Builder` using the supplied bytes.
///
/// # Examples
///
@ -334,7 +337,7 @@ impl crate::Builder {
Builder(b)
}
/// Creates a `Builder` using the supplied big-endian bytes.
/// Creates a `Builder` using the supplied bytes.
///
/// # Errors
///
@ -380,7 +383,7 @@ impl crate::Builder {
Ok(Self::from_bytes(bytes))
}
/// Creates a `Builder` from four big-endian field values.
/// Creates a `Builder` from four field values.
///
/// # Errors
///
@ -425,7 +428,7 @@ impl crate::Builder {
})
}
/// Creates a `Builder` from a big-endian 128bit value.
/// Creates a `Builder` from a 128bit value.
pub fn from_u128(v: u128) -> Self {
crate::Builder::from_bytes(*Uuid::from_u128(v).as_bytes())
}

34
src/lib.rs
View File

@ -108,6 +108,26 @@
//! * hyphenated: `550e8400-e29b-41d4-a716-446655440000`
//! * urn: `urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4`
//!
//! # Endianness
//!
//! The specification for UUIDs encodes the integer fields that make up the
//! value in big-endian order. This crate assumes integer inputs are already in
//! the correct order by default, regardless of the endianness of the
//! environment. Most methods that accept integers have a `_le` variant (such as
//! `from_fields_le`) that assumes any integer values will need to have their
//! bytes flipped, regardless of the endianness of the environment.
//!
//! Most users won't need to worry about endianness unless they need to operate
//! on individual fields (such as when converting between Microsoft GUIDs). The
//! important things to remember are:
//!
//! - The endianness is in terms of the fields of the UUID, not the environment.
//! - The endianness is assumed to be big-endian when there's no `_le` suffix
//! somewhere.
//! - Byte-flipping in `_le` methods applies to each integer.
//! - Endianness roundtrips, so if you create a UUID with `from_fields_le`
//! you'll get the same values back out with `to_fields_le`.
//!
//! # References
//!
//! * [Wikipedia: Universally Unique Identifier](http://en.wikipedia.org/wiki/Universally_unique_identifier)
@ -304,7 +324,7 @@ impl Uuid {
}
}
/// Returns the four field values of the UUID in big-endian order.
/// Returns the four field values of the UUID.
///
/// These values can be passed to the `from_fields()` method to get the
/// original `Uuid` back.
@ -366,8 +386,10 @@ impl Uuid {
/// Returns the four field values of the UUID in little-endian order.
///
/// The bytes in the returned integer fields will
/// be converted from big-endian order.
/// The bytes in the returned integer fields will be converted from
/// big-endian order. This is based on the endianness of the UUID,
/// rather than the target environment so bytes will be flipped on both
/// big and little endian machines.
///
/// # Examples
///
@ -445,7 +467,11 @@ impl Uuid {
/// Returns a 128bit little-endian value containing the UUID data.
///
/// The bytes in the UUID will be reversed and packed into a `u128`.
/// The bytes in the `u128` will be flipped to convert into big-endian
/// order. This is based on the endianness of the UUID, rather than the
/// target environment so bytes will be flipped on both big and little
/// endian machines.
///
/// Note that this will produce a different result than
/// [`Uuid::to_fields_le`], because the entire UUID is reversed, rather
/// than reversing the individual fields in-place.