Skip to content

Commit b754d0f

Browse files
sunshowerssunshowers
authored
add more UUID methods (#104)
1 parent c20c885 commit b754d0f

File tree

2 files changed

+283
-0
lines changed

2 files changed

+283
-0
lines changed

‎.claude/settings.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"WebFetch(domain:docs.rs)",
5+
"Bash(cargo check:*)",
6+
"Bash(cargo test:*)"
7+
],
8+
"deny": [],
9+
"ask": []
10+
}
11+
}

‎crates/newtype-uuid/src/lib.rs‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -342,6 +342,278 @@ impl<T: TypedUuidKind> TypedUuid<T> {
342342
self.uuid.get_version()
343343
}
344344

345+
/// Returns true if the UUID is nil (all zeros).
346+
#[inline]
347+
pub const fn is_nil(&self) -> bool {
348+
self.uuid.is_nil()
349+
}
350+
351+
/// Returns true if the UUID is the max value (all ones).
352+
#[inline]
353+
pub const fn is_max(&self) -> bool {
354+
self.uuid.is_max()
355+
}
356+
357+
/// Returns the four field values of the UUID.
358+
///
359+
/// These values can be passed to [`Self::from_fields`] to reconstruct the
360+
/// original UUID. The first field represents the initial eight hex digits
361+
/// as a big-endian `u32`. The second and third fields represent subsequent
362+
/// hex digit groups as `u16` values. The final field contains the last two
363+
/// groups of hex digits as an 8-byte array.
364+
///
365+
/// # Examples
366+
///
367+
/// ```
368+
/// # use newtype_uuid::TypedUuid;
369+
/// # enum ExampleKind {}
370+
/// # impl newtype_uuid::TypedUuidKind for ExampleKind {
371+
/// # fn tag() -> newtype_uuid::TypedUuidTag {
372+
/// # const TAG: newtype_uuid::TypedUuidTag = newtype_uuid::TypedUuidTag::new("example");
373+
/// # TAG
374+
/// # }
375+
/// # }
376+
/// let uuid: TypedUuid<ExampleKind> =
377+
/// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();
378+
///
379+
/// assert_eq!(
380+
/// uuid.as_fields(),
381+
/// (
382+
/// 0xa1a2a3a4,
383+
/// 0xb1b2,
384+
/// 0xc1c2,
385+
/// &[0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8],
386+
/// )
387+
/// );
388+
/// ```
389+
#[inline]
390+
pub fn as_fields(&self) -> (u32, u16, u16, &[u8; 8]) {
391+
self.uuid.as_fields()
392+
}
393+
394+
/// Returns the four field values in little-endian order.
395+
///
396+
/// The bytes within integer fields are converted from big-endian order.
397+
/// This is based on the endianness of the UUID rather than the target
398+
/// environment, so bytes will be flipped on both big and little endian
399+
/// machines.
400+
///
401+
/// # Examples
402+
///
403+
/// ```
404+
/// # use newtype_uuid::TypedUuid;
405+
/// # enum ExampleKind {}
406+
/// # impl newtype_uuid::TypedUuidKind for ExampleKind {
407+
/// # fn tag() -> newtype_uuid::TypedUuidTag {
408+
/// # const TAG: newtype_uuid::TypedUuidTag = newtype_uuid::TypedUuidTag::new("example");
409+
/// # TAG
410+
/// # }
411+
/// # }
412+
/// let uuid: TypedUuid<ExampleKind> =
413+
/// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();
414+
///
415+
/// assert_eq!(
416+
/// uuid.to_fields_le(),
417+
/// (
418+
/// 0xa4a3a2a1,
419+
/// 0xb2b1,
420+
/// 0xc2c1,
421+
/// &[0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8],
422+
/// )
423+
/// );
424+
/// ```
425+
#[inline]
426+
pub fn to_fields_le(&self) -> (u32, u16, u16, &[u8; 8]) {
427+
self.uuid.to_fields_le()
428+
}
429+
430+
/// Returns a 128-bit value containing the UUID bytes.
431+
///
432+
/// # Examples
433+
///
434+
/// ```
435+
/// # use newtype_uuid::TypedUuid;
436+
/// # enum ExampleKind {}
437+
/// # impl newtype_uuid::TypedUuidKind for ExampleKind {
438+
/// # fn tag() -> newtype_uuid::TypedUuidTag {
439+
/// # const TAG: newtype_uuid::TypedUuidTag = newtype_uuid::TypedUuidTag::new("example");
440+
/// # TAG
441+
/// # }
442+
/// # }
443+
/// let uuid: TypedUuid<ExampleKind> =
444+
/// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();
445+
///
446+
/// assert_eq!(
447+
/// uuid.as_u128(),
448+
/// 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128,
449+
/// );
450+
/// ```
451+
#[inline]
452+
pub const fn as_u128(&self) -> u128 {
453+
self.uuid.as_u128()
454+
}
455+
456+
/// Returns a 128-bit little-endian value.
457+
///
458+
/// The bytes in the `u128` will be flipped to convert into big-endian order.
459+
/// This is based on the endianness of the UUID, rather than the target
460+
/// environment so bytes will be flipped on both big and little endian
461+
/// machines.
462+
///
463+
/// Note that this will produce a different result than
464+
/// [`Self::to_fields_le`], because the entire UUID is reversed, rather than
465+
/// reversing the individual fields in-place.
466+
///
467+
/// # Examples
468+
///
469+
/// ```
470+
/// # use newtype_uuid::TypedUuid;
471+
/// # enum ExampleKind {}
472+
/// # impl newtype_uuid::TypedUuidKind for ExampleKind {
473+
/// # fn tag() -> newtype_uuid::TypedUuidTag {
474+
/// # const TAG: newtype_uuid::TypedUuidTag = newtype_uuid::TypedUuidTag::new("example");
475+
/// # TAG
476+
/// # }
477+
/// # }
478+
/// let uuid: TypedUuid<ExampleKind> =
479+
/// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();
480+
///
481+
/// assert_eq!(
482+
/// uuid.to_u128_le(),
483+
/// 0xd8d7d6d5d4d3d2d1c2c1b2b1a4a3a2a1u128,
484+
/// );
485+
/// ```
486+
#[inline]
487+
pub fn to_u128_le(&self) -> u128 {
488+
self.uuid.to_u128_le()
489+
}
490+
491+
/// Returns two 64-bit values representing the UUID.
492+
///
493+
/// The first `u64` contains the most significant 64 bits; the second
494+
/// contains the least significant bits.
495+
///
496+
/// # Examples
497+
///
498+
/// ```
499+
/// # use newtype_uuid::TypedUuid;
500+
/// # enum ExampleKind {}
501+
/// # impl newtype_uuid::TypedUuidKind for ExampleKind {
502+
/// # fn tag() -> newtype_uuid::TypedUuidTag {
503+
/// # const TAG: newtype_uuid::TypedUuidTag = newtype_uuid::TypedUuidTag::new("example");
504+
/// # TAG
505+
/// # }
506+
/// # }
507+
/// let uuid: TypedUuid<ExampleKind> =
508+
/// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();
509+
///
510+
/// assert_eq!(
511+
/// uuid.as_u64_pair(),
512+
/// (0xa1a2a3a4b1b2c1c2, 0xd1d2d3d4d5d6d7d8),
513+
/// );
514+
/// ```
515+
#[inline]
516+
pub const fn as_u64_pair(&self) -> (u64, u64) {
517+
self.uuid.as_u64_pair()
518+
}
519+
520+
/// Returns a slice of 16 octets containing the value.
521+
///
522+
/// This method borrows the underlying byte value of the UUID.
523+
///
524+
/// # Examples
525+
///
526+
/// ```
527+
/// # use newtype_uuid::TypedUuid;
528+
/// # enum ExampleKind {}
529+
/// # impl newtype_uuid::TypedUuidKind for ExampleKind {
530+
/// # fn tag() -> newtype_uuid::TypedUuidTag {
531+
/// # const TAG: newtype_uuid::TypedUuidTag = newtype_uuid::TypedUuidTag::new("example");
532+
/// # TAG
533+
/// # }
534+
/// # }
535+
/// let bytes = [
536+
/// 0xa1, 0xa2, 0xa3, 0xa4,
537+
/// 0xb1, 0xb2,
538+
/// 0xc1, 0xc2,
539+
/// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
540+
/// ];
541+
///
542+
/// let uuid = TypedUuid::<ExampleKind>::from_bytes(bytes);
543+
/// let bytes2 = uuid.as_bytes();
544+
///
545+
/// assert_eq!(&bytes, bytes2);
546+
/// ```
547+
#[inline]
548+
pub const fn as_bytes(&self) -> &uuid::Bytes {
549+
self.uuid.as_bytes()
550+
}
551+
552+
/// Consumes self and returns the underlying byte value of the UUID.
553+
///
554+
/// # Examples
555+
///
556+
/// ```
557+
/// # use newtype_uuid::TypedUuid;
558+
/// # enum ExampleKind {}
559+
/// # impl newtype_uuid::TypedUuidKind for ExampleKind {
560+
/// # fn tag() -> newtype_uuid::TypedUuidTag {
561+
/// # const TAG: newtype_uuid::TypedUuidTag = newtype_uuid::TypedUuidTag::new("example");
562+
/// # TAG
563+
/// # }
564+
/// # }
565+
/// let bytes = [
566+
/// 0xa1, 0xa2, 0xa3, 0xa4,
567+
/// 0xb1, 0xb2,
568+
/// 0xc1, 0xc2,
569+
/// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
570+
/// ];
571+
///
572+
/// let uuid = TypedUuid::<ExampleKind>::from_bytes(bytes);
573+
///
574+
/// assert_eq!(bytes, uuid.into_bytes());
575+
/// ```
576+
#[inline]
577+
#[must_use]
578+
pub const fn into_bytes(self) -> uuid::Bytes {
579+
self.uuid.into_bytes()
580+
}
581+
582+
/// Returns the bytes of the UUID in little-endian order.
583+
///
584+
/// The bytes will be flipped to convert into little-endian order. This is
585+
/// based on the endianness of the UUID, rather than the target environment
586+
/// so bytes will be flipped on both big and little endian machines.
587+
///
588+
/// # Examples
589+
///
590+
/// ```
591+
/// # use newtype_uuid::TypedUuid;
592+
/// # enum ExampleKind {}
593+
/// # impl newtype_uuid::TypedUuidKind for ExampleKind {
594+
/// # fn tag() -> newtype_uuid::TypedUuidTag {
595+
/// # const TAG: newtype_uuid::TypedUuidTag = newtype_uuid::TypedUuidTag::new("example");
596+
/// # TAG
597+
/// # }
598+
/// # }
599+
/// let uuid: TypedUuid<ExampleKind> =
600+
/// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();
601+
///
602+
/// assert_eq!(
603+
/// uuid.to_bytes_le(),
604+
/// [
605+
/// 0xa4, 0xa3, 0xa2, 0xa1,
606+
/// 0xb2, 0xb1,
607+
/// 0xc2, 0xc1,
608+
/// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
609+
/// ]
610+
/// );
611+
/// ```
612+
#[inline]
613+
pub fn to_bytes_le(&self) -> uuid::Bytes {
614+
self.uuid.to_bytes_le()
615+
}
616+
345617
/// Converts the UUID to one with looser semantics.
346618
///
347619
/// By default, UUID kinds are considered independent, and conversions

0 commit comments

Comments
 (0)