uuid/builder.rs
1// Copyright 2013-2014 The Rust Project Developers.
2// Copyright 2018 The Uuid Project Developers.
3//
4// See the COPYRIGHT file at the top-level directory of this distribution.
5//
6// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
7// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
8// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
9// option. This file may not be copied, modified, or distributed
10// except according to those terms.
11
12//! A Builder type for [`Uuid`]s.
13//!
14//! [`Uuid`]: ../struct.Uuid.html
15
16use crate::{error::*, timestamp, Bytes, Uuid, Variant, Version};
17
18/// A builder for creating a UUID.
19///
20/// This type is useful if you need to mutate individual fields of a [`Uuid`]
21/// while constructing it. Since the [`Uuid`] type is `Copy`, it doesn't offer
22/// any methods to mutate in place. They live on the `Builder` instead.
23///
24/// The `Builder` type also always exposes APIs to construct [`Uuid`]s for any
25/// version without needing crate features or additional dependencies. It's a
26/// lower-level API than the methods on [`Uuid`].
27///
28/// # Examples
29///
30/// Creating a version 4 UUID from externally generated random bytes:
31///
32/// ```
33/// # use uuid::{Builder, Version, Variant};
34/// # let rng = || [
35/// # 70, 235, 208, 238, 14, 109, 67, 201, 185, 13, 204, 195, 90,
36/// # 145, 63, 62,
37/// # ];
38/// let random_bytes = rng();
39///
40/// let uuid = Builder::from_random_bytes(random_bytes).into_uuid();
41///
42/// assert_eq!(Some(Version::Random), uuid.get_version());
43/// assert_eq!(Variant::RFC4122, uuid.get_variant());
44/// ```
45#[allow(missing_copy_implementations)]
46#[derive(Debug)]
47pub struct Builder(Uuid);
48
49impl Uuid {
50 /// The 'nil UUID' (all zeros).
51 ///
52 /// The nil UUID is a special form of UUID that is specified to have all
53 /// 128 bits set to zero.
54 ///
55 /// # References
56 ///
57 /// * [Nil UUID in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.9)
58 ///
59 /// # Examples
60 ///
61 /// Basic usage:
62 ///
63 /// ```
64 /// # use uuid::Uuid;
65 /// let uuid = Uuid::nil();
66 ///
67 /// assert_eq!(
68 /// "00000000-0000-0000-0000-000000000000",
69 /// uuid.hyphenated().to_string(),
70 /// );
71 /// ```
72 pub const fn nil() -> Self {
73 Uuid::from_bytes([0; 16])
74 }
75
76 /// The 'max UUID' (all ones).
77 ///
78 /// The max UUID is a special form of UUID that is specified to have all
79 /// 128 bits set to one.
80 ///
81 /// # References
82 ///
83 /// * [Max UUID in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.10)
84 ///
85 /// # Examples
86 ///
87 /// Basic usage:
88 ///
89 /// ```
90 /// # use uuid::Uuid;
91 /// let uuid = Uuid::max();
92 ///
93 /// assert_eq!(
94 /// "ffffffff-ffff-ffff-ffff-ffffffffffff",
95 /// uuid.hyphenated().to_string(),
96 /// );
97 /// ```
98 pub const fn max() -> Self {
99 Uuid::from_bytes([0xFF; 16])
100 }
101
102 /// Creates a UUID from four field values.
103 ///
104 /// # Examples
105 ///
106 /// Basic usage:
107 ///
108 /// ```
109 /// # use uuid::Uuid;
110 /// let d1 = 0xa1a2a3a4;
111 /// let d2 = 0xb1b2;
112 /// let d3 = 0xc1c2;
113 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
114 ///
115 /// let uuid = Uuid::from_fields(d1, d2, d3, &d4);
116 ///
117 /// assert_eq!(
118 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
119 /// uuid.hyphenated().to_string(),
120 /// );
121 /// ```
122 pub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Uuid {
123 Uuid::from_bytes([
124 (d1 >> 24) as u8,
125 (d1 >> 16) as u8,
126 (d1 >> 8) as u8,
127 d1 as u8,
128 (d2 >> 8) as u8,
129 d2 as u8,
130 (d3 >> 8) as u8,
131 d3 as u8,
132 d4[0],
133 d4[1],
134 d4[2],
135 d4[3],
136 d4[4],
137 d4[5],
138 d4[6],
139 d4[7],
140 ])
141 }
142
143 /// Creates a UUID from four field values in little-endian order.
144 ///
145 /// The bytes in the `d1`, `d2` and `d3` fields will be flipped to convert
146 /// into big-endian order. This is based on the endianness of the UUID,
147 /// rather than the target environment so bytes will be flipped on both
148 /// big and little endian machines.
149 ///
150 /// # Examples
151 ///
152 /// Basic usage:
153 ///
154 /// ```
155 /// # use uuid::Uuid;
156 /// let d1 = 0xa1a2a3a4;
157 /// let d2 = 0xb1b2;
158 /// let d3 = 0xc1c2;
159 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
160 ///
161 /// let uuid = Uuid::from_fields_le(d1, d2, d3, &d4);
162 ///
163 /// assert_eq!(
164 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
165 /// uuid.hyphenated().to_string(),
166 /// );
167 /// ```
168 pub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Uuid {
169 Uuid::from_bytes([
170 d1 as u8,
171 (d1 >> 8) as u8,
172 (d1 >> 16) as u8,
173 (d1 >> 24) as u8,
174 (d2) as u8,
175 (d2 >> 8) as u8,
176 d3 as u8,
177 (d3 >> 8) as u8,
178 d4[0],
179 d4[1],
180 d4[2],
181 d4[3],
182 d4[4],
183 d4[5],
184 d4[6],
185 d4[7],
186 ])
187 }
188
189 /// Creates a UUID from a 128bit value.
190 ///
191 /// # Examples
192 ///
193 /// Basic usage:
194 ///
195 /// ```
196 /// # use uuid::Uuid;
197 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
198 ///
199 /// let uuid = Uuid::from_u128(v);
200 ///
201 /// assert_eq!(
202 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
203 /// uuid.hyphenated().to_string(),
204 /// );
205 /// ```
206 pub const fn from_u128(v: u128) -> Self {
207 Uuid::from_bytes(v.to_be_bytes())
208 }
209
210 /// Creates a UUID from a 128bit value in little-endian order.
211 ///
212 /// The entire value will be flipped to convert into big-endian order.
213 /// This is based on the endianness of the UUID, rather than the target
214 /// environment so bytes will be flipped on both big and little endian
215 /// machines.
216 ///
217 /// # Examples
218 ///
219 /// Basic usage:
220 ///
221 /// ```
222 /// # use uuid::Uuid;
223 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
224 ///
225 /// let uuid = Uuid::from_u128_le(v);
226 ///
227 /// assert_eq!(
228 /// "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
229 /// uuid.hyphenated().to_string(),
230 /// );
231 /// ```
232 pub const fn from_u128_le(v: u128) -> Self {
233 Uuid::from_bytes(v.to_le_bytes())
234 }
235
236 /// Creates a UUID from two 64bit values.
237 ///
238 /// # Examples
239 ///
240 /// Basic usage:
241 ///
242 /// ```
243 /// # use uuid::Uuid;
244 /// let hi = 0xa1a2a3a4b1b2c1c2u64;
245 /// let lo = 0xd1d2d3d4d5d6d7d8u64;
246 ///
247 /// let uuid = Uuid::from_u64_pair(hi, lo);
248 ///
249 /// assert_eq!(
250 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
251 /// uuid.hyphenated().to_string(),
252 /// );
253 /// ```
254 pub const fn from_u64_pair(high_bits: u64, low_bits: u64) -> Self {
255 Uuid::from_u128(((high_bits as u128) << 64) | low_bits as u128)
256 }
257
258 /// Creates a UUID using the supplied bytes.
259 ///
260 /// # Errors
261 ///
262 /// This function will return an error if `b` has any length other than 16.
263 ///
264 /// # Examples
265 ///
266 /// Basic usage:
267 ///
268 /// ```
269 /// # fn main() -> Result<(), uuid::Error> {
270 /// # use uuid::Uuid;
271 /// let bytes = [
272 /// 0xa1, 0xa2, 0xa3, 0xa4,
273 /// 0xb1, 0xb2,
274 /// 0xc1, 0xc2,
275 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
276 /// ];
277 ///
278 /// let uuid = Uuid::from_slice(&bytes)?;
279 ///
280 /// assert_eq!(
281 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
282 /// uuid.hyphenated().to_string(),
283 /// );
284 /// # Ok(())
285 /// # }
286 /// ```
287 pub fn from_slice(b: &[u8]) -> Result<Uuid, Error> {
288 if b.len() != 16 {
289 return Err(Error(ErrorKind::ParseByteLength { len: b.len() }));
290 }
291
292 let mut bytes: Bytes = [0; 16];
293 bytes.copy_from_slice(b);
294 Ok(Uuid::from_bytes(bytes))
295 }
296
297 /// Creates a UUID using the supplied bytes in little endian order.
298 ///
299 /// The individual fields encoded in the buffer will be flipped.
300 ///
301 /// # Errors
302 ///
303 /// This function will return an error if `b` has any length other than 16.
304 ///
305 /// # Examples
306 ///
307 /// Basic usage:
308 ///
309 /// ```
310 /// # fn main() -> Result<(), uuid::Error> {
311 /// # use uuid::Uuid;
312 /// let bytes = [
313 /// 0xa1, 0xa2, 0xa3, 0xa4,
314 /// 0xb1, 0xb2,
315 /// 0xc1, 0xc2,
316 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
317 /// ];
318 ///
319 /// let uuid = Uuid::from_slice_le(&bytes)?;
320 ///
321 /// assert_eq!(
322 /// uuid.hyphenated().to_string(),
323 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8"
324 /// );
325 /// # Ok(())
326 /// # }
327 /// ```
328 pub fn from_slice_le(b: &[u8]) -> Result<Uuid, Error> {
329 if b.len() != 16 {
330 return Err(Error(ErrorKind::ParseByteLength { len: b.len() }));
331 }
332
333 let mut bytes: Bytes = [0; 16];
334 bytes.copy_from_slice(b);
335 Ok(Uuid::from_bytes_le(bytes))
336 }
337
338 /// Creates a UUID using the supplied bytes.
339 ///
340 /// # Examples
341 ///
342 /// Basic usage:
343 ///
344 /// ```
345 /// # fn main() -> Result<(), uuid::Error> {
346 /// # use uuid::Uuid;
347 /// let bytes = [
348 /// 0xa1, 0xa2, 0xa3, 0xa4,
349 /// 0xb1, 0xb2,
350 /// 0xc1, 0xc2,
351 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
352 /// ];
353 ///
354 /// let uuid = Uuid::from_bytes(bytes);
355 ///
356 /// assert_eq!(
357 /// uuid.hyphenated().to_string(),
358 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
359 /// );
360 /// # Ok(())
361 /// # }
362 /// ```
363 #[inline]
364 pub const fn from_bytes(bytes: Bytes) -> Uuid {
365 Uuid(bytes)
366 }
367
368 /// Creates a UUID using the supplied bytes in little endian order.
369 ///
370 /// Note that ordering is applied to each _field_, rather than to the bytes as a whole.
371 /// This ordering is compatible with Microsoft's mixed endian GUID format.
372 ///
373 /// # Examples
374 ///
375 /// Basic usage:
376 ///
377 /// ```
378 /// # fn main() -> Result<(), uuid::Error> {
379 /// # use uuid::Uuid;
380 /// let bytes = [
381 /// 0xa1, 0xa2, 0xa3, 0xa4,
382 /// 0xb1, 0xb2,
383 /// 0xc1, 0xc2,
384 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
385 /// ];
386 ///
387 /// let uuid = Uuid::from_bytes_le(bytes);
388 ///
389 /// assert_eq!(
390 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
391 /// uuid.hyphenated().to_string(),
392 /// );
393 /// # Ok(())
394 /// # }
395 /// ```
396 pub const fn from_bytes_le(b: Bytes) -> Uuid {
397 Uuid([
398 b[3], b[2], b[1], b[0], b[5], b[4], b[7], b[6], b[8], b[9], b[10], b[11], b[12], b[13],
399 b[14], b[15],
400 ])
401 }
402
403 /// Creates a reference to a UUID from a reference to the supplied bytes.
404 ///
405 /// # Examples
406 ///
407 /// Basic usage:
408 ///
409 /// ```
410 /// # fn main() -> Result<(), uuid::Error> {
411 /// # use uuid::Uuid;
412 /// let bytes = [
413 /// 0xa1, 0xa2, 0xa3, 0xa4,
414 /// 0xb1, 0xb2,
415 /// 0xc1, 0xc2,
416 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
417 /// ];
418 ///
419 /// let uuid = Uuid::from_bytes_ref(&bytes);
420 ///
421 /// assert_eq!(
422 /// uuid.hyphenated().to_string(),
423 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
424 /// );
425 ///
426 /// assert!(std::ptr::eq(
427 /// uuid as *const Uuid as *const u8,
428 /// &bytes as *const [u8; 16] as *const u8,
429 /// ));
430 /// # Ok(())
431 /// # }
432 /// ```
433 #[inline]
434 pub fn from_bytes_ref(bytes: &Bytes) -> &Uuid {
435 unsafe_transmute_ref!(bytes)
436 }
437
438 // NOTE: There is no `from_u128_ref` because in little-endian
439 // environments the value isn't properly encoded. Callers would
440 // need to use `.to_be()` themselves.
441}
442
443impl Builder {
444 /// Creates a `Builder` using the supplied bytes.
445 ///
446 /// # Examples
447 ///
448 /// Basic usage:
449 ///
450 /// ```
451 /// # use uuid::Builder;
452 /// let bytes = [
453 /// 0xa1, 0xa2, 0xa3, 0xa4,
454 /// 0xb1, 0xb2,
455 /// 0xc1, 0xc2,
456 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
457 /// ];
458 ///
459 /// let uuid = Builder::from_bytes(bytes).into_uuid();
460 ///
461 /// assert_eq!(
462 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
463 /// uuid.hyphenated().to_string(),
464 /// );
465 /// ```
466 pub const fn from_bytes(b: Bytes) -> Self {
467 Builder(Uuid::from_bytes(b))
468 }
469
470 /// Creates a `Builder` using the supplied bytes in little endian order.
471 ///
472 /// The individual fields encoded in the buffer will be flipped.
473 ///
474 /// # Examples
475 ///
476 /// Basic usage:
477 ///
478 /// ```
479 /// # fn main() -> Result<(), uuid::Error> {
480 /// # use uuid::{Builder, Uuid};
481 /// let bytes = [
482 /// 0xa1, 0xa2, 0xa3, 0xa4,
483 /// 0xb1, 0xb2,
484 /// 0xc1, 0xc2,
485 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
486 /// ];
487 ///
488 /// let uuid = Builder::from_bytes_le(bytes).into_uuid();
489 ///
490 /// assert_eq!(
491 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
492 /// uuid.hyphenated().to_string(),
493 /// );
494 /// # Ok(())
495 /// # }
496 /// ```
497 pub const fn from_bytes_le(b: Bytes) -> Self {
498 Builder(Uuid::from_bytes_le(b))
499 }
500
501 /// Creates a `Builder` for a version 1 UUID using the supplied timestamp, counter, and node ID.
502 pub const fn from_gregorian_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self {
503 Builder(timestamp::encode_gregorian_timestamp(
504 ticks, counter, node_id,
505 ))
506 }
507
508 /// Creates a `Builder` for a version 3 UUID using the supplied MD5 hashed bytes.
509 pub const fn from_md5_bytes(md5_bytes: Bytes) -> Self {
510 Builder(Uuid::from_bytes(md5_bytes))
511 .with_variant(Variant::RFC4122)
512 .with_version(Version::Md5)
513 }
514
515 /// Creates a `Builder` for a version 4 UUID using the supplied random bytes.
516 ///
517 /// This method assumes the bytes are already sufficiently random, it will only
518 /// set the appropriate bits for the UUID version and variant.
519 ///
520 /// # Examples
521 ///
522 /// ```
523 /// # use uuid::{Builder, Variant, Version};
524 /// # let rng = || [
525 /// # 70, 235, 208, 238, 14, 109, 67, 201, 185, 13, 204, 195, 90,
526 /// # 145, 63, 62,
527 /// # ];
528 /// let random_bytes = rng();
529 /// let uuid = Builder::from_random_bytes(random_bytes).into_uuid();
530 ///
531 /// assert_eq!(Some(Version::Random), uuid.get_version());
532 /// assert_eq!(Variant::RFC4122, uuid.get_variant());
533 /// ```
534 pub const fn from_random_bytes(random_bytes: Bytes) -> Self {
535 Builder(Uuid::from_bytes(random_bytes))
536 .with_variant(Variant::RFC4122)
537 .with_version(Version::Random)
538 }
539
540 /// Creates a `Builder` for a version 5 UUID using the supplied SHA-1 hashed bytes.
541 ///
542 /// This method assumes the bytes are already a SHA-1 hash, it will only set the appropriate
543 /// bits for the UUID version and variant.
544 pub const fn from_sha1_bytes(sha1_bytes: Bytes) -> Self {
545 Builder(Uuid::from_bytes(sha1_bytes))
546 .with_variant(Variant::RFC4122)
547 .with_version(Version::Sha1)
548 }
549
550 /// Creates a `Builder` for a version 6 UUID using the supplied timestamp, counter, and node ID.
551 ///
552 /// This method will encode the ticks, counter, and node ID in a sortable UUID.
553 pub const fn from_sorted_gregorian_timestamp(
554 ticks: u64,
555 counter: u16,
556 node_id: &[u8; 6],
557 ) -> Self {
558 Builder(timestamp::encode_sorted_gregorian_timestamp(
559 ticks, counter, node_id,
560 ))
561 }
562
563 /// Creates a `Builder` for a version 7 UUID using the supplied Unix timestamp and counter bytes.
564 ///
565 /// This method will set the variant field within the counter bytes without attempting to shift
566 /// the data around it. Callers using the counter as a monotonic value should be careful not to
567 /// store significant data in the 2 least significant bits of the 3rd byte.
568 ///
569 /// # Examples
570 ///
571 /// Creating a UUID using the current system timestamp:
572 ///
573 /// ```
574 /// use std::time::{Duration, SystemTime};
575 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
576 /// # use uuid::{Builder, Uuid, Variant, Version, Timestamp, NoContext};
577 /// # let rng = || [
578 /// # 70, 235, 208, 238, 14, 109, 67, 201, 185, 13
579 /// # ];
580 /// let ts = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)?;
581 ///
582 /// let random_bytes = rng();
583 ///
584 /// let uuid = Builder::from_unix_timestamp_millis(ts.as_millis().try_into()?, &random_bytes).into_uuid();
585 ///
586 /// assert_eq!(Some(Version::SortRand), uuid.get_version());
587 /// assert_eq!(Variant::RFC4122, uuid.get_variant());
588 /// # Ok(())
589 /// # }
590 /// ```
591 pub const fn from_unix_timestamp_millis(millis: u64, counter_random_bytes: &[u8; 10]) -> Self {
592 Builder(timestamp::encode_unix_timestamp_millis(
593 millis,
594 counter_random_bytes,
595 ))
596 }
597
598 /// Creates a `Builder` for a version 8 UUID using the supplied user-defined bytes.
599 ///
600 /// This method won't interpret the given bytes in any way, except to set the appropriate
601 /// bits for the UUID version and variant.
602 pub const fn from_custom_bytes(custom_bytes: Bytes) -> Self {
603 Builder::from_bytes(custom_bytes)
604 .with_variant(Variant::RFC4122)
605 .with_version(Version::Custom)
606 }
607
608 /// Creates a `Builder` using the supplied bytes.
609 ///
610 /// # Errors
611 ///
612 /// This function will return an error if `b` has any length other than 16.
613 ///
614 /// # Examples
615 ///
616 /// Basic usage:
617 ///
618 /// ```
619 /// # use uuid::Builder;
620 /// # fn main() -> Result<(), uuid::Error> {
621 /// let bytes = [
622 /// 0xa1, 0xa2, 0xa3, 0xa4,
623 /// 0xb1, 0xb2,
624 /// 0xc1, 0xc2,
625 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
626 /// ];
627 ///
628 /// let uuid = Builder::from_slice(&bytes)?.into_uuid();
629 ///
630 /// assert_eq!(
631 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
632 /// uuid.hyphenated().to_string(),
633 /// );
634 /// # Ok(())
635 /// # }
636 /// ```
637 pub fn from_slice(b: &[u8]) -> Result<Self, Error> {
638 Ok(Builder(Uuid::from_slice(b)?))
639 }
640
641 /// Creates a `Builder` using the supplied bytes in little endian order.
642 ///
643 /// The individual fields encoded in the buffer will be flipped.
644 ///
645 /// # Errors
646 ///
647 /// This function will return an error if `b` has any length other than 16.
648 ///
649 /// # Examples
650 ///
651 /// Basic usage:
652 ///
653 /// ```
654 /// # use uuid::Builder;
655 /// # fn main() -> Result<(), uuid::Error> {
656 /// let bytes = [
657 /// 0xa1, 0xa2, 0xa3, 0xa4,
658 /// 0xb1, 0xb2,
659 /// 0xc1, 0xc2,
660 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
661 /// ];
662 ///
663 /// let uuid = Builder::from_slice_le(&bytes)?.into_uuid();
664 ///
665 /// assert_eq!(
666 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
667 /// uuid.hyphenated().to_string(),
668 /// );
669 /// # Ok(())
670 /// # }
671 /// ```
672 pub fn from_slice_le(b: &[u8]) -> Result<Self, Error> {
673 Ok(Builder(Uuid::from_slice_le(b)?))
674 }
675
676 /// Creates a `Builder` from four field values.
677 ///
678 /// # Examples
679 ///
680 /// Basic usage:
681 ///
682 /// ```
683 /// # use uuid::Builder;
684 /// let d1 = 0xa1a2a3a4;
685 /// let d2 = 0xb1b2;
686 /// let d3 = 0xc1c2;
687 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
688 ///
689 /// let uuid = Builder::from_fields(d1, d2, d3, &d4).into_uuid();
690 ///
691 /// assert_eq!(
692 /// uuid.hyphenated().to_string(),
693 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
694 /// );
695 /// ```
696 pub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self {
697 Builder(Uuid::from_fields(d1, d2, d3, d4))
698 }
699
700 /// Creates a `Builder` from four field values.
701 ///
702 /// # Examples
703 ///
704 /// Basic usage:
705 ///
706 /// ```
707 /// # use uuid::Builder;
708 /// let d1 = 0xa1a2a3a4;
709 /// let d2 = 0xb1b2;
710 /// let d3 = 0xc1c2;
711 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
712 ///
713 /// let uuid = Builder::from_fields_le(d1, d2, d3, &d4).into_uuid();
714 ///
715 /// assert_eq!(
716 /// uuid.hyphenated().to_string(),
717 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8"
718 /// );
719 /// ```
720 pub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self {
721 Builder(Uuid::from_fields_le(d1, d2, d3, d4))
722 }
723
724 /// Creates a `Builder` from a 128bit value.
725 ///
726 /// # Examples
727 ///
728 /// Basic usage:
729 ///
730 /// ```
731 /// # use uuid::Builder;
732 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
733 ///
734 /// let uuid = Builder::from_u128(v).into_uuid();
735 ///
736 /// assert_eq!(
737 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
738 /// uuid.hyphenated().to_string(),
739 /// );
740 /// ```
741 pub const fn from_u128(v: u128) -> Self {
742 Builder(Uuid::from_u128(v))
743 }
744
745 /// Creates a UUID from a 128bit value in little-endian order.
746 ///
747 /// # Examples
748 ///
749 /// Basic usage:
750 ///
751 /// ```
752 /// # use uuid::Builder;
753 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
754 ///
755 /// let uuid = Builder::from_u128_le(v).into_uuid();
756 ///
757 /// assert_eq!(
758 /// "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
759 /// uuid.hyphenated().to_string(),
760 /// );
761 /// ```
762 pub const fn from_u128_le(v: u128) -> Self {
763 Builder(Uuid::from_u128_le(v))
764 }
765
766 /// Creates a `Builder` with an initial [`Uuid::nil`].
767 ///
768 /// # Examples
769 ///
770 /// Basic usage:
771 ///
772 /// ```
773 /// # use uuid::Builder;
774 /// let uuid = Builder::nil().into_uuid();
775 ///
776 /// assert_eq!(
777 /// "00000000-0000-0000-0000-000000000000",
778 /// uuid.hyphenated().to_string(),
779 /// );
780 /// ```
781 pub const fn nil() -> Self {
782 Builder(Uuid::nil())
783 }
784
785 /// Specifies the variant of the UUID.
786 pub fn set_variant(&mut self, v: Variant) -> &mut Self {
787 *self = Builder(self.0).with_variant(v);
788 self
789 }
790
791 /// Specifies the variant of the UUID.
792 pub const fn with_variant(mut self, v: Variant) -> Self {
793 let byte = (self.0).0[8];
794
795 (self.0).0[8] = match v {
796 Variant::NCS => byte & 0x7f,
797 Variant::RFC4122 => (byte & 0x3f) | 0x80,
798 Variant::Microsoft => (byte & 0x1f) | 0xc0,
799 Variant::Future => byte | 0xe0,
800 };
801
802 self
803 }
804
805 /// Specifies the version number of the UUID.
806 pub fn set_version(&mut self, v: Version) -> &mut Self {
807 *self = Builder(self.0).with_version(v);
808 self
809 }
810
811 /// Specifies the version number of the UUID.
812 pub const fn with_version(mut self, v: Version) -> Self {
813 (self.0).0[6] = ((self.0).0[6] & 0x0f) | ((v as u8) << 4);
814
815 self
816 }
817
818 /// Get a reference to the underlying [`Uuid`].
819 ///
820 /// # Examples
821 ///
822 /// Basic usage:
823 ///
824 /// ```
825 /// # use uuid::Builder;
826 /// let builder = Builder::nil();
827 ///
828 /// let uuid1 = builder.as_uuid();
829 /// let uuid2 = builder.as_uuid();
830 ///
831 /// assert_eq!(uuid1, uuid2);
832 /// ```
833 pub const fn as_uuid(&self) -> &Uuid {
834 &self.0
835 }
836
837 /// Convert the builder into a [`Uuid`].
838 ///
839 /// # Examples
840 ///
841 /// Basic usage:
842 ///
843 /// ```
844 /// # use uuid::Builder;
845 /// let uuid = Builder::nil().into_uuid();
846 ///
847 /// assert_eq!(
848 /// uuid.hyphenated().to_string(),
849 /// "00000000-0000-0000-0000-000000000000"
850 /// );
851 /// ```
852 pub const fn into_uuid(self) -> Uuid {
853 self.0
854 }
855}
856
857#[doc(hidden)]
858impl Builder {
859 #[deprecated(
860 since = "1.10.0",
861 note = "use `Builder::from_gregorian_timestamp(ticks, counter, node_id)`"
862 )]
863 pub const fn from_rfc4122_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self {
864 Builder::from_gregorian_timestamp(ticks, counter, node_id)
865 }
866
867 #[deprecated(
868 since = "1.10.0",
869 note = "use `Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)`"
870 )]
871 pub const fn from_sorted_rfc4122_timestamp(
872 ticks: u64,
873 counter: u16,
874 node_id: &[u8; 6],
875 ) -> Self {
876 Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)
877 }
878}