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([
208 (v >> 120) as u8,
209 (v >> 112) as u8,
210 (v >> 104) as u8,
211 (v >> 96) as u8,
212 (v >> 88) as u8,
213 (v >> 80) as u8,
214 (v >> 72) as u8,
215 (v >> 64) as u8,
216 (v >> 56) as u8,
217 (v >> 48) as u8,
218 (v >> 40) as u8,
219 (v >> 32) as u8,
220 (v >> 24) as u8,
221 (v >> 16) as u8,
222 (v >> 8) as u8,
223 v as u8,
224 ])
225 }
226
227 /// Creates a UUID from a 128bit value in little-endian order.
228 ///
229 /// The entire value will be flipped to convert into big-endian order.
230 /// This is based on the endianness of the UUID, rather than the target
231 /// environment so bytes will be flipped on both big and little endian
232 /// machines.
233 ///
234 /// # Examples
235 ///
236 /// Basic usage:
237 ///
238 /// ```
239 /// # use uuid::Uuid;
240 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
241 ///
242 /// let uuid = Uuid::from_u128_le(v);
243 ///
244 /// assert_eq!(
245 /// "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
246 /// uuid.hyphenated().to_string(),
247 /// );
248 /// ```
249 pub const fn from_u128_le(v: u128) -> Self {
250 Uuid::from_bytes([
251 v as u8,
252 (v >> 8) as u8,
253 (v >> 16) as u8,
254 (v >> 24) as u8,
255 (v >> 32) as u8,
256 (v >> 40) as u8,
257 (v >> 48) as u8,
258 (v >> 56) as u8,
259 (v >> 64) as u8,
260 (v >> 72) as u8,
261 (v >> 80) as u8,
262 (v >> 88) as u8,
263 (v >> 96) as u8,
264 (v >> 104) as u8,
265 (v >> 112) as u8,
266 (v >> 120) as u8,
267 ])
268 }
269
270 /// Creates a UUID from two 64bit values.
271 ///
272 /// # Examples
273 ///
274 /// Basic usage:
275 ///
276 /// ```
277 /// # use uuid::Uuid;
278 /// let hi = 0xa1a2a3a4b1b2c1c2u64;
279 /// let lo = 0xd1d2d3d4d5d6d7d8u64;
280 ///
281 /// let uuid = Uuid::from_u64_pair(hi, lo);
282 ///
283 /// assert_eq!(
284 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
285 /// uuid.hyphenated().to_string(),
286 /// );
287 /// ```
288 pub const fn from_u64_pair(high_bits: u64, low_bits: u64) -> Self {
289 Uuid::from_bytes([
290 (high_bits >> 56) as u8,
291 (high_bits >> 48) as u8,
292 (high_bits >> 40) as u8,
293 (high_bits >> 32) as u8,
294 (high_bits >> 24) as u8,
295 (high_bits >> 16) as u8,
296 (high_bits >> 8) as u8,
297 high_bits as u8,
298 (low_bits >> 56) as u8,
299 (low_bits >> 48) as u8,
300 (low_bits >> 40) as u8,
301 (low_bits >> 32) as u8,
302 (low_bits >> 24) as u8,
303 (low_bits >> 16) as u8,
304 (low_bits >> 8) as u8,
305 low_bits as u8,
306 ])
307 }
308
309 /// Creates a UUID using the supplied bytes.
310 ///
311 /// # Errors
312 ///
313 /// This function will return an error if `b` has any length other than 16.
314 ///
315 /// # Examples
316 ///
317 /// Basic usage:
318 ///
319 /// ```
320 /// # fn main() -> Result<(), uuid::Error> {
321 /// # use uuid::Uuid;
322 /// let bytes = [
323 /// 0xa1, 0xa2, 0xa3, 0xa4,
324 /// 0xb1, 0xb2,
325 /// 0xc1, 0xc2,
326 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
327 /// ];
328 ///
329 /// let uuid = Uuid::from_slice(&bytes)?;
330 ///
331 /// assert_eq!(
332 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
333 /// uuid.hyphenated().to_string(),
334 /// );
335 /// # Ok(())
336 /// # }
337 /// ```
338 pub fn from_slice(b: &[u8]) -> Result<Uuid, Error> {
339 if b.len() != 16 {
340 return Err(Error(ErrorKind::ByteLength { len: b.len() }));
341 }
342
343 let mut bytes: Bytes = [0; 16];
344 bytes.copy_from_slice(b);
345 Ok(Uuid::from_bytes(bytes))
346 }
347
348 /// Creates a UUID using the supplied bytes in little endian order.
349 ///
350 /// The individual fields encoded in the buffer will be flipped.
351 ///
352 /// # Errors
353 ///
354 /// This function will return an error if `b` has any length other than 16.
355 ///
356 /// # Examples
357 ///
358 /// Basic usage:
359 ///
360 /// ```
361 /// # fn main() -> Result<(), uuid::Error> {
362 /// # use uuid::Uuid;
363 /// let bytes = [
364 /// 0xa1, 0xa2, 0xa3, 0xa4,
365 /// 0xb1, 0xb2,
366 /// 0xc1, 0xc2,
367 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
368 /// ];
369 ///
370 /// let uuid = Uuid::from_slice_le(&bytes)?;
371 ///
372 /// assert_eq!(
373 /// uuid.hyphenated().to_string(),
374 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8"
375 /// );
376 /// # Ok(())
377 /// # }
378 /// ```
379 pub fn from_slice_le(b: &[u8]) -> Result<Uuid, Error> {
380 if b.len() != 16 {
381 return Err(Error(ErrorKind::ByteLength { len: b.len() }));
382 }
383
384 let mut bytes: Bytes = [0; 16];
385 bytes.copy_from_slice(b);
386 Ok(Uuid::from_bytes_le(bytes))
387 }
388
389 /// Creates a UUID using the supplied bytes.
390 ///
391 /// # Examples
392 ///
393 /// Basic usage:
394 ///
395 /// ```
396 /// # fn main() -> Result<(), uuid::Error> {
397 /// # use uuid::Uuid;
398 /// let bytes = [
399 /// 0xa1, 0xa2, 0xa3, 0xa4,
400 /// 0xb1, 0xb2,
401 /// 0xc1, 0xc2,
402 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
403 /// ];
404 ///
405 /// let uuid = Uuid::from_bytes(bytes);
406 ///
407 /// assert_eq!(
408 /// uuid.hyphenated().to_string(),
409 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
410 /// );
411 /// # Ok(())
412 /// # }
413 /// ```
414 #[inline]
415 pub const fn from_bytes(bytes: Bytes) -> Uuid {
416 Uuid(bytes)
417 }
418
419 /// Creates a UUID using the supplied bytes in little endian order.
420 ///
421 /// The individual fields encoded in the buffer will be flipped.
422 ///
423 /// # Examples
424 ///
425 /// Basic usage:
426 ///
427 /// ```
428 /// # fn main() -> Result<(), uuid::Error> {
429 /// # use uuid::Uuid;
430 /// let bytes = [
431 /// 0xa1, 0xa2, 0xa3, 0xa4,
432 /// 0xb1, 0xb2,
433 /// 0xc1, 0xc2,
434 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
435 /// ];
436 ///
437 /// let uuid = Uuid::from_bytes_le(bytes);
438 ///
439 /// assert_eq!(
440 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
441 /// uuid.hyphenated().to_string(),
442 /// );
443 /// # Ok(())
444 /// # }
445 /// ```
446 pub const fn from_bytes_le(b: Bytes) -> Uuid {
447 Uuid([
448 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],
449 b[14], b[15],
450 ])
451 }
452
453 /// Creates a reference to a UUID from a reference to the supplied bytes.
454 ///
455 /// # Examples
456 ///
457 /// Basic usage:
458 ///
459 /// ```
460 /// # fn main() -> Result<(), uuid::Error> {
461 /// # use uuid::Uuid;
462 /// let bytes = [
463 /// 0xa1, 0xa2, 0xa3, 0xa4,
464 /// 0xb1, 0xb2,
465 /// 0xc1, 0xc2,
466 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
467 /// ];
468 ///
469 /// let uuid = Uuid::from_bytes_ref(&bytes);
470 ///
471 /// assert_eq!(
472 /// uuid.hyphenated().to_string(),
473 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
474 /// );
475 ///
476 /// assert!(std::ptr::eq(
477 /// uuid as *const Uuid as *const u8,
478 /// &bytes as *const [u8; 16] as *const u8,
479 /// ));
480 /// # Ok(())
481 /// # }
482 /// ```
483 #[inline]
484 pub fn from_bytes_ref(bytes: &Bytes) -> &Uuid {
485 // SAFETY: `Bytes` and `Uuid` have the same ABI
486 unsafe { &*(bytes as *const Bytes as *const Uuid) }
487 }
488
489 // NOTE: There is no `from_u128_ref` because in little-endian
490 // environments the value isn't properly encoded. Callers would
491 // need to use `.to_be()` themselves.
492}
493
494impl Builder {
495 /// Creates a `Builder` using the supplied bytes.
496 ///
497 /// # Examples
498 ///
499 /// Basic usage:
500 ///
501 /// ```
502 /// # use uuid::Builder;
503 /// let bytes = [
504 /// 0xa1, 0xa2, 0xa3, 0xa4,
505 /// 0xb1, 0xb2,
506 /// 0xc1, 0xc2,
507 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
508 /// ];
509 ///
510 /// let uuid = Builder::from_bytes(bytes).into_uuid();
511 ///
512 /// assert_eq!(
513 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
514 /// uuid.hyphenated().to_string(),
515 /// );
516 /// ```
517 pub const fn from_bytes(b: Bytes) -> Self {
518 Builder(Uuid::from_bytes(b))
519 }
520
521 /// Creates a `Builder` using the supplied bytes in little endian order.
522 ///
523 /// The individual fields encoded in the buffer will be flipped.
524 ///
525 /// # Examples
526 ///
527 /// Basic usage:
528 ///
529 /// ```
530 /// # fn main() -> Result<(), uuid::Error> {
531 /// # use uuid::{Builder, Uuid};
532 /// let bytes = [
533 /// 0xa1, 0xa2, 0xa3, 0xa4,
534 /// 0xb1, 0xb2,
535 /// 0xc1, 0xc2,
536 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
537 /// ];
538 ///
539 /// let uuid = Builder::from_bytes_le(bytes).into_uuid();
540 ///
541 /// assert_eq!(
542 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
543 /// uuid.hyphenated().to_string(),
544 /// );
545 /// # Ok(())
546 /// # }
547 /// ```
548 pub const fn from_bytes_le(b: Bytes) -> Self {
549 Builder(Uuid::from_bytes_le(b))
550 }
551
552 /// Creates a `Builder` for a version 1 UUID using the supplied timestamp, counter, and node ID.
553 pub const fn from_gregorian_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self {
554 Builder(timestamp::encode_gregorian_timestamp(
555 ticks, counter, node_id,
556 ))
557 }
558
559 /// Creates a `Builder` for a version 3 UUID using the supplied MD5 hashed bytes.
560 pub const fn from_md5_bytes(md5_bytes: Bytes) -> Self {
561 Builder(Uuid::from_bytes(md5_bytes))
562 .with_variant(Variant::RFC4122)
563 .with_version(Version::Md5)
564 }
565
566 /// Creates a `Builder` for a version 4 UUID using the supplied random bytes.
567 ///
568 /// This method assumes the bytes are already sufficiently random, it will only
569 /// set the appropriate bits for the UUID version and variant.
570 ///
571 /// # Examples
572 ///
573 /// ```
574 /// # use uuid::{Builder, Variant, Version};
575 /// # let rng = || [
576 /// # 70, 235, 208, 238, 14, 109, 67, 201, 185, 13, 204, 195, 90,
577 /// # 145, 63, 62,
578 /// # ];
579 /// let random_bytes = rng();
580 /// let uuid = Builder::from_random_bytes(random_bytes).into_uuid();
581 ///
582 /// assert_eq!(Some(Version::Random), uuid.get_version());
583 /// assert_eq!(Variant::RFC4122, uuid.get_variant());
584 /// ```
585 pub const fn from_random_bytes(random_bytes: Bytes) -> Self {
586 Builder(Uuid::from_bytes(random_bytes))
587 .with_variant(Variant::RFC4122)
588 .with_version(Version::Random)
589 }
590
591 /// Creates a `Builder` for a version 5 UUID using the supplied SHA-1 hashed bytes.
592 ///
593 /// This method assumes the bytes are already a SHA-1 hash, it will only set the appropriate
594 /// bits for the UUID version and variant.
595 pub const fn from_sha1_bytes(sha1_bytes: Bytes) -> Self {
596 Builder(Uuid::from_bytes(sha1_bytes))
597 .with_variant(Variant::RFC4122)
598 .with_version(Version::Sha1)
599 }
600
601 /// Creates a `Builder` for a version 6 UUID using the supplied timestamp, counter, and node ID.
602 ///
603 /// This method will encode the ticks, counter, and node ID in a sortable UUID.
604 pub const fn from_sorted_gregorian_timestamp(
605 ticks: u64,
606 counter: u16,
607 node_id: &[u8; 6],
608 ) -> Self {
609 Builder(timestamp::encode_sorted_gregorian_timestamp(
610 ticks, counter, node_id,
611 ))
612 }
613
614 /// Creates a `Builder` for a version 7 UUID using the supplied Unix timestamp and counter bytes.
615 ///
616 /// This method will set the variant field within the counter bytes without attempting to shift
617 /// the data around it. Callers using the counter as a monotonic value should be careful not to
618 /// store significant data in the 2 least significant bits of the 3rd byte.
619 ///
620 /// # Examples
621 ///
622 /// Creating a UUID using the current system timestamp:
623 ///
624 /// ```
625 /// # use std::convert::TryInto;
626 /// use std::time::{Duration, SystemTime};
627 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
628 /// # use uuid::{Builder, Uuid, Variant, Version, Timestamp, NoContext};
629 /// # let rng = || [
630 /// # 70, 235, 208, 238, 14, 109, 67, 201, 185, 13
631 /// # ];
632 /// let ts = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)?;
633 ///
634 /// let random_bytes = rng();
635 ///
636 /// let uuid = Builder::from_unix_timestamp_millis(ts.as_millis().try_into()?, &random_bytes).into_uuid();
637 ///
638 /// assert_eq!(Some(Version::SortRand), uuid.get_version());
639 /// assert_eq!(Variant::RFC4122, uuid.get_variant());
640 /// # Ok(())
641 /// # }
642 /// ```
643 pub const fn from_unix_timestamp_millis(millis: u64, counter_random_bytes: &[u8; 10]) -> Self {
644 Builder(timestamp::encode_unix_timestamp_millis(
645 millis,
646 counter_random_bytes,
647 ))
648 }
649
650 /// Creates a `Builder` for a version 8 UUID using the supplied user-defined bytes.
651 ///
652 /// This method won't interpret the given bytes in any way, except to set the appropriate
653 /// bits for the UUID version and variant.
654 pub const fn from_custom_bytes(custom_bytes: Bytes) -> Self {
655 Builder::from_bytes(custom_bytes)
656 .with_variant(Variant::RFC4122)
657 .with_version(Version::Custom)
658 }
659
660 /// Creates a `Builder` using the supplied bytes.
661 ///
662 /// # Errors
663 ///
664 /// This function will return an error if `b` has any length other than 16.
665 ///
666 /// # Examples
667 ///
668 /// Basic usage:
669 ///
670 /// ```
671 /// # use uuid::Builder;
672 /// # fn main() -> Result<(), uuid::Error> {
673 /// let bytes = [
674 /// 0xa1, 0xa2, 0xa3, 0xa4,
675 /// 0xb1, 0xb2,
676 /// 0xc1, 0xc2,
677 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
678 /// ];
679 ///
680 /// let uuid = Builder::from_slice(&bytes)?.into_uuid();
681 ///
682 /// assert_eq!(
683 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
684 /// uuid.hyphenated().to_string(),
685 /// );
686 /// # Ok(())
687 /// # }
688 /// ```
689 pub fn from_slice(b: &[u8]) -> Result<Self, Error> {
690 Ok(Builder(Uuid::from_slice(b)?))
691 }
692
693 /// Creates a `Builder` using the supplied bytes in little endian order.
694 ///
695 /// The individual fields encoded in the buffer will be flipped.
696 ///
697 /// # Errors
698 ///
699 /// This function will return an error if `b` has any length other than 16.
700 ///
701 /// # Examples
702 ///
703 /// Basic usage:
704 ///
705 /// ```
706 /// # use uuid::Builder;
707 /// # fn main() -> Result<(), uuid::Error> {
708 /// let bytes = [
709 /// 0xa1, 0xa2, 0xa3, 0xa4,
710 /// 0xb1, 0xb2,
711 /// 0xc1, 0xc2,
712 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
713 /// ];
714 ///
715 /// let uuid = Builder::from_slice_le(&bytes)?.into_uuid();
716 ///
717 /// assert_eq!(
718 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
719 /// uuid.hyphenated().to_string(),
720 /// );
721 /// # Ok(())
722 /// # }
723 /// ```
724 pub fn from_slice_le(b: &[u8]) -> Result<Self, Error> {
725 Ok(Builder(Uuid::from_slice_le(b)?))
726 }
727
728 /// Creates a `Builder` from four field values.
729 ///
730 /// # Examples
731 ///
732 /// Basic usage:
733 ///
734 /// ```
735 /// # use uuid::Builder;
736 /// let d1 = 0xa1a2a3a4;
737 /// let d2 = 0xb1b2;
738 /// let d3 = 0xc1c2;
739 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
740 ///
741 /// let uuid = Builder::from_fields(d1, d2, d3, &d4).into_uuid();
742 ///
743 /// assert_eq!(
744 /// uuid.hyphenated().to_string(),
745 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
746 /// );
747 /// ```
748 pub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self {
749 Builder(Uuid::from_fields(d1, d2, d3, d4))
750 }
751
752 /// Creates a `Builder` from four field values.
753 ///
754 /// # Examples
755 ///
756 /// Basic usage:
757 ///
758 /// ```
759 /// # use uuid::Builder;
760 /// let d1 = 0xa1a2a3a4;
761 /// let d2 = 0xb1b2;
762 /// let d3 = 0xc1c2;
763 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
764 ///
765 /// let uuid = Builder::from_fields_le(d1, d2, d3, &d4).into_uuid();
766 ///
767 /// assert_eq!(
768 /// uuid.hyphenated().to_string(),
769 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8"
770 /// );
771 /// ```
772 pub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self {
773 Builder(Uuid::from_fields_le(d1, d2, d3, d4))
774 }
775
776 /// Creates a `Builder` from a 128bit value.
777 ///
778 /// # Examples
779 ///
780 /// Basic usage:
781 ///
782 /// ```
783 /// # use uuid::Builder;
784 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
785 ///
786 /// let uuid = Builder::from_u128(v).into_uuid();
787 ///
788 /// assert_eq!(
789 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
790 /// uuid.hyphenated().to_string(),
791 /// );
792 /// ```
793 pub const fn from_u128(v: u128) -> Self {
794 Builder(Uuid::from_u128(v))
795 }
796
797 /// Creates a UUID from a 128bit value in little-endian order.
798 ///
799 /// # Examples
800 ///
801 /// Basic usage:
802 ///
803 /// ```
804 /// # use uuid::Builder;
805 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
806 ///
807 /// let uuid = Builder::from_u128_le(v).into_uuid();
808 ///
809 /// assert_eq!(
810 /// "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
811 /// uuid.hyphenated().to_string(),
812 /// );
813 /// ```
814 pub const fn from_u128_le(v: u128) -> Self {
815 Builder(Uuid::from_u128_le(v))
816 }
817
818 /// Creates a `Builder` with an initial [`Uuid::nil`].
819 ///
820 /// # Examples
821 ///
822 /// Basic usage:
823 ///
824 /// ```
825 /// # use uuid::Builder;
826 /// let uuid = Builder::nil().into_uuid();
827 ///
828 /// assert_eq!(
829 /// "00000000-0000-0000-0000-000000000000",
830 /// uuid.hyphenated().to_string(),
831 /// );
832 /// ```
833 pub const fn nil() -> Self {
834 Builder(Uuid::nil())
835 }
836
837 /// Specifies the variant of the UUID.
838 pub fn set_variant(&mut self, v: Variant) -> &mut Self {
839 *self = Builder(self.0).with_variant(v);
840 self
841 }
842
843 /// Specifies the variant of the UUID.
844 pub const fn with_variant(mut self, v: Variant) -> Self {
845 let byte = (self.0).0[8];
846
847 (self.0).0[8] = match v {
848 Variant::NCS => byte & 0x7f,
849 Variant::RFC4122 => (byte & 0x3f) | 0x80,
850 Variant::Microsoft => (byte & 0x1f) | 0xc0,
851 Variant::Future => byte | 0xe0,
852 };
853
854 self
855 }
856
857 /// Specifies the version number of the UUID.
858 pub fn set_version(&mut self, v: Version) -> &mut Self {
859 *self = Builder(self.0).with_version(v);
860 self
861 }
862
863 /// Specifies the version number of the UUID.
864 pub const fn with_version(mut self, v: Version) -> Self {
865 (self.0).0[6] = ((self.0).0[6] & 0x0f) | ((v as u8) << 4);
866
867 self
868 }
869
870 /// Get a reference to the underlying [`Uuid`].
871 ///
872 /// # Examples
873 ///
874 /// Basic usage:
875 ///
876 /// ```
877 /// # use uuid::Builder;
878 /// let builder = Builder::nil();
879 ///
880 /// let uuid1 = builder.as_uuid();
881 /// let uuid2 = builder.as_uuid();
882 ///
883 /// assert_eq!(uuid1, uuid2);
884 /// ```
885 pub const fn as_uuid(&self) -> &Uuid {
886 &self.0
887 }
888
889 /// Convert the builder into a [`Uuid`].
890 ///
891 /// # Examples
892 ///
893 /// Basic usage:
894 ///
895 /// ```
896 /// # use uuid::Builder;
897 /// let uuid = Builder::nil().into_uuid();
898 ///
899 /// assert_eq!(
900 /// uuid.hyphenated().to_string(),
901 /// "00000000-0000-0000-0000-000000000000"
902 /// );
903 /// ```
904 pub const fn into_uuid(self) -> Uuid {
905 self.0
906 }
907}
908
909#[doc(hidden)]
910impl Builder {
911 #[deprecated(
912 since = "1.10.0",
913 note = "use `Builder::from_gregorian_timestamp(ticks, counter, node_id)`"
914 )]
915 pub const fn from_rfc4122_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self {
916 Builder::from_gregorian_timestamp(ticks, counter, node_id)
917 }
918
919 #[deprecated(
920 since = "1.10.0",
921 note = "use `Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)`"
922 )]
923 pub const fn from_sorted_rfc4122_timestamp(
924 ticks: u64,
925 counter: u16,
926 node_id: &[u8; 6],
927 ) -> Self {
928 Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)
929 }
930}
931