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 /// The individual fields encoded in the buffer will be flipped.
371 ///
372 /// # Examples
373 ///
374 /// Basic usage:
375 ///
376 /// ```
377 /// # fn main() -> Result<(), uuid::Error> {
378 /// # use uuid::Uuid;
379 /// let bytes = [
380 /// 0xa1, 0xa2, 0xa3, 0xa4,
381 /// 0xb1, 0xb2,
382 /// 0xc1, 0xc2,
383 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
384 /// ];
385 ///
386 /// let uuid = Uuid::from_bytes_le(bytes);
387 ///
388 /// assert_eq!(
389 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
390 /// uuid.hyphenated().to_string(),
391 /// );
392 /// # Ok(())
393 /// # }
394 /// ```
395 pub const fn from_bytes_le(b: Bytes) -> Uuid {
396 Uuid([
397 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],
398 b[14], b[15],
399 ])
400 }
401
402 /// Creates a reference to a UUID from a reference to the supplied bytes.
403 ///
404 /// # Examples
405 ///
406 /// Basic usage:
407 ///
408 /// ```
409 /// # fn main() -> Result<(), uuid::Error> {
410 /// # use uuid::Uuid;
411 /// let bytes = [
412 /// 0xa1, 0xa2, 0xa3, 0xa4,
413 /// 0xb1, 0xb2,
414 /// 0xc1, 0xc2,
415 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
416 /// ];
417 ///
418 /// let uuid = Uuid::from_bytes_ref(&bytes);
419 ///
420 /// assert_eq!(
421 /// uuid.hyphenated().to_string(),
422 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
423 /// );
424 ///
425 /// assert!(std::ptr::eq(
426 /// uuid as *const Uuid as *const u8,
427 /// &bytes as *const [u8; 16] as *const u8,
428 /// ));
429 /// # Ok(())
430 /// # }
431 /// ```
432 #[inline]
433 pub fn from_bytes_ref(bytes: &Bytes) -> &Uuid {
434 unsafe_transmute_ref!(bytes)
435 }
436
437 // NOTE: There is no `from_u128_ref` because in little-endian
438 // environments the value isn't properly encoded. Callers would
439 // need to use `.to_be()` themselves.
440}
441
442impl Builder {
443 /// Creates a `Builder` using the supplied bytes.
444 ///
445 /// # Examples
446 ///
447 /// Basic usage:
448 ///
449 /// ```
450 /// # use uuid::Builder;
451 /// let bytes = [
452 /// 0xa1, 0xa2, 0xa3, 0xa4,
453 /// 0xb1, 0xb2,
454 /// 0xc1, 0xc2,
455 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
456 /// ];
457 ///
458 /// let uuid = Builder::from_bytes(bytes).into_uuid();
459 ///
460 /// assert_eq!(
461 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
462 /// uuid.hyphenated().to_string(),
463 /// );
464 /// ```
465 pub const fn from_bytes(b: Bytes) -> Self {
466 Builder(Uuid::from_bytes(b))
467 }
468
469 /// Creates a `Builder` using the supplied bytes in little endian order.
470 ///
471 /// The individual fields encoded in the buffer will be flipped.
472 ///
473 /// # Examples
474 ///
475 /// Basic usage:
476 ///
477 /// ```
478 /// # fn main() -> Result<(), uuid::Error> {
479 /// # use uuid::{Builder, Uuid};
480 /// let bytes = [
481 /// 0xa1, 0xa2, 0xa3, 0xa4,
482 /// 0xb1, 0xb2,
483 /// 0xc1, 0xc2,
484 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
485 /// ];
486 ///
487 /// let uuid = Builder::from_bytes_le(bytes).into_uuid();
488 ///
489 /// assert_eq!(
490 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
491 /// uuid.hyphenated().to_string(),
492 /// );
493 /// # Ok(())
494 /// # }
495 /// ```
496 pub const fn from_bytes_le(b: Bytes) -> Self {
497 Builder(Uuid::from_bytes_le(b))
498 }
499
500 /// Creates a `Builder` for a version 1 UUID using the supplied timestamp, counter, and node ID.
501 pub const fn from_gregorian_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self {
502 Builder(timestamp::encode_gregorian_timestamp(
503 ticks, counter, node_id,
504 ))
505 }
506
507 /// Creates a `Builder` for a version 3 UUID using the supplied MD5 hashed bytes.
508 pub const fn from_md5_bytes(md5_bytes: Bytes) -> Self {
509 Builder(Uuid::from_bytes(md5_bytes))
510 .with_variant(Variant::RFC4122)
511 .with_version(Version::Md5)
512 }
513
514 /// Creates a `Builder` for a version 4 UUID using the supplied random bytes.
515 ///
516 /// This method assumes the bytes are already sufficiently random, it will only
517 /// set the appropriate bits for the UUID version and variant.
518 ///
519 /// # Examples
520 ///
521 /// ```
522 /// # use uuid::{Builder, Variant, Version};
523 /// # let rng = || [
524 /// # 70, 235, 208, 238, 14, 109, 67, 201, 185, 13, 204, 195, 90,
525 /// # 145, 63, 62,
526 /// # ];
527 /// let random_bytes = rng();
528 /// let uuid = Builder::from_random_bytes(random_bytes).into_uuid();
529 ///
530 /// assert_eq!(Some(Version::Random), uuid.get_version());
531 /// assert_eq!(Variant::RFC4122, uuid.get_variant());
532 /// ```
533 pub const fn from_random_bytes(random_bytes: Bytes) -> Self {
534 Builder(Uuid::from_bytes(random_bytes))
535 .with_variant(Variant::RFC4122)
536 .with_version(Version::Random)
537 }
538
539 /// Creates a `Builder` for a version 5 UUID using the supplied SHA-1 hashed bytes.
540 ///
541 /// This method assumes the bytes are already a SHA-1 hash, it will only set the appropriate
542 /// bits for the UUID version and variant.
543 pub const fn from_sha1_bytes(sha1_bytes: Bytes) -> Self {
544 Builder(Uuid::from_bytes(sha1_bytes))
545 .with_variant(Variant::RFC4122)
546 .with_version(Version::Sha1)
547 }
548
549 /// Creates a `Builder` for a version 6 UUID using the supplied timestamp, counter, and node ID.
550 ///
551 /// This method will encode the ticks, counter, and node ID in a sortable UUID.
552 pub const fn from_sorted_gregorian_timestamp(
553 ticks: u64,
554 counter: u16,
555 node_id: &[u8; 6],
556 ) -> Self {
557 Builder(timestamp::encode_sorted_gregorian_timestamp(
558 ticks, counter, node_id,
559 ))
560 }
561
562 /// Creates a `Builder` for a version 7 UUID using the supplied Unix timestamp and counter bytes.
563 ///
564 /// This method will set the variant field within the counter bytes without attempting to shift
565 /// the data around it. Callers using the counter as a monotonic value should be careful not to
566 /// store significant data in the 2 least significant bits of the 3rd byte.
567 ///
568 /// # Examples
569 ///
570 /// Creating a UUID using the current system timestamp:
571 ///
572 /// ```
573 /// use std::time::{Duration, SystemTime};
574 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
575 /// # use uuid::{Builder, Uuid, Variant, Version, Timestamp, NoContext};
576 /// # let rng = || [
577 /// # 70, 235, 208, 238, 14, 109, 67, 201, 185, 13
578 /// # ];
579 /// let ts = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)?;
580 ///
581 /// let random_bytes = rng();
582 ///
583 /// let uuid = Builder::from_unix_timestamp_millis(ts.as_millis().try_into()?, &random_bytes).into_uuid();
584 ///
585 /// assert_eq!(Some(Version::SortRand), uuid.get_version());
586 /// assert_eq!(Variant::RFC4122, uuid.get_variant());
587 /// # Ok(())
588 /// # }
589 /// ```
590 pub const fn from_unix_timestamp_millis(millis: u64, counter_random_bytes: &[u8; 10]) -> Self {
591 Builder(timestamp::encode_unix_timestamp_millis(
592 millis,
593 counter_random_bytes,
594 ))
595 }
596
597 /// Creates a `Builder` for a version 8 UUID using the supplied user-defined bytes.
598 ///
599 /// This method won't interpret the given bytes in any way, except to set the appropriate
600 /// bits for the UUID version and variant.
601 pub const fn from_custom_bytes(custom_bytes: Bytes) -> Self {
602 Builder::from_bytes(custom_bytes)
603 .with_variant(Variant::RFC4122)
604 .with_version(Version::Custom)
605 }
606
607 /// Creates a `Builder` using the supplied bytes.
608 ///
609 /// # Errors
610 ///
611 /// This function will return an error if `b` has any length other than 16.
612 ///
613 /// # Examples
614 ///
615 /// Basic usage:
616 ///
617 /// ```
618 /// # use uuid::Builder;
619 /// # fn main() -> Result<(), uuid::Error> {
620 /// let bytes = [
621 /// 0xa1, 0xa2, 0xa3, 0xa4,
622 /// 0xb1, 0xb2,
623 /// 0xc1, 0xc2,
624 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
625 /// ];
626 ///
627 /// let uuid = Builder::from_slice(&bytes)?.into_uuid();
628 ///
629 /// assert_eq!(
630 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
631 /// uuid.hyphenated().to_string(),
632 /// );
633 /// # Ok(())
634 /// # }
635 /// ```
636 pub fn from_slice(b: &[u8]) -> Result<Self, Error> {
637 Ok(Builder(Uuid::from_slice(b)?))
638 }
639
640 /// Creates a `Builder` using the supplied bytes in little endian order.
641 ///
642 /// The individual fields encoded in the buffer will be flipped.
643 ///
644 /// # Errors
645 ///
646 /// This function will return an error if `b` has any length other than 16.
647 ///
648 /// # Examples
649 ///
650 /// Basic usage:
651 ///
652 /// ```
653 /// # use uuid::Builder;
654 /// # fn main() -> Result<(), uuid::Error> {
655 /// let bytes = [
656 /// 0xa1, 0xa2, 0xa3, 0xa4,
657 /// 0xb1, 0xb2,
658 /// 0xc1, 0xc2,
659 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
660 /// ];
661 ///
662 /// let uuid = Builder::from_slice_le(&bytes)?.into_uuid();
663 ///
664 /// assert_eq!(
665 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
666 /// uuid.hyphenated().to_string(),
667 /// );
668 /// # Ok(())
669 /// # }
670 /// ```
671 pub fn from_slice_le(b: &[u8]) -> Result<Self, Error> {
672 Ok(Builder(Uuid::from_slice_le(b)?))
673 }
674
675 /// Creates a `Builder` from four field values.
676 ///
677 /// # Examples
678 ///
679 /// Basic usage:
680 ///
681 /// ```
682 /// # use uuid::Builder;
683 /// let d1 = 0xa1a2a3a4;
684 /// let d2 = 0xb1b2;
685 /// let d3 = 0xc1c2;
686 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
687 ///
688 /// let uuid = Builder::from_fields(d1, d2, d3, &d4).into_uuid();
689 ///
690 /// assert_eq!(
691 /// uuid.hyphenated().to_string(),
692 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
693 /// );
694 /// ```
695 pub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self {
696 Builder(Uuid::from_fields(d1, d2, d3, d4))
697 }
698
699 /// Creates a `Builder` from four field values.
700 ///
701 /// # Examples
702 ///
703 /// Basic usage:
704 ///
705 /// ```
706 /// # use uuid::Builder;
707 /// let d1 = 0xa1a2a3a4;
708 /// let d2 = 0xb1b2;
709 /// let d3 = 0xc1c2;
710 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
711 ///
712 /// let uuid = Builder::from_fields_le(d1, d2, d3, &d4).into_uuid();
713 ///
714 /// assert_eq!(
715 /// uuid.hyphenated().to_string(),
716 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8"
717 /// );
718 /// ```
719 pub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self {
720 Builder(Uuid::from_fields_le(d1, d2, d3, d4))
721 }
722
723 /// Creates a `Builder` from a 128bit value.
724 ///
725 /// # Examples
726 ///
727 /// Basic usage:
728 ///
729 /// ```
730 /// # use uuid::Builder;
731 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
732 ///
733 /// let uuid = Builder::from_u128(v).into_uuid();
734 ///
735 /// assert_eq!(
736 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
737 /// uuid.hyphenated().to_string(),
738 /// );
739 /// ```
740 pub const fn from_u128(v: u128) -> Self {
741 Builder(Uuid::from_u128(v))
742 }
743
744 /// Creates a UUID from a 128bit value in little-endian order.
745 ///
746 /// # Examples
747 ///
748 /// Basic usage:
749 ///
750 /// ```
751 /// # use uuid::Builder;
752 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
753 ///
754 /// let uuid = Builder::from_u128_le(v).into_uuid();
755 ///
756 /// assert_eq!(
757 /// "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
758 /// uuid.hyphenated().to_string(),
759 /// );
760 /// ```
761 pub const fn from_u128_le(v: u128) -> Self {
762 Builder(Uuid::from_u128_le(v))
763 }
764
765 /// Creates a `Builder` with an initial [`Uuid::nil`].
766 ///
767 /// # Examples
768 ///
769 /// Basic usage:
770 ///
771 /// ```
772 /// # use uuid::Builder;
773 /// let uuid = Builder::nil().into_uuid();
774 ///
775 /// assert_eq!(
776 /// "00000000-0000-0000-0000-000000000000",
777 /// uuid.hyphenated().to_string(),
778 /// );
779 /// ```
780 pub const fn nil() -> Self {
781 Builder(Uuid::nil())
782 }
783
784 /// Specifies the variant of the UUID.
785 pub fn set_variant(&mut self, v: Variant) -> &mut Self {
786 *self = Builder(self.0).with_variant(v);
787 self
788 }
789
790 /// Specifies the variant of the UUID.
791 pub const fn with_variant(mut self, v: Variant) -> Self {
792 let byte = (self.0).0[8];
793
794 (self.0).0[8] = match v {
795 Variant::NCS => byte & 0x7f,
796 Variant::RFC4122 => (byte & 0x3f) | 0x80,
797 Variant::Microsoft => (byte & 0x1f) | 0xc0,
798 Variant::Future => byte | 0xe0,
799 };
800
801 self
802 }
803
804 /// Specifies the version number of the UUID.
805 pub fn set_version(&mut self, v: Version) -> &mut Self {
806 *self = Builder(self.0).with_version(v);
807 self
808 }
809
810 /// Specifies the version number of the UUID.
811 pub const fn with_version(mut self, v: Version) -> Self {
812 (self.0).0[6] = ((self.0).0[6] & 0x0f) | ((v as u8) << 4);
813
814 self
815 }
816
817 /// Get a reference to the underlying [`Uuid`].
818 ///
819 /// # Examples
820 ///
821 /// Basic usage:
822 ///
823 /// ```
824 /// # use uuid::Builder;
825 /// let builder = Builder::nil();
826 ///
827 /// let uuid1 = builder.as_uuid();
828 /// let uuid2 = builder.as_uuid();
829 ///
830 /// assert_eq!(uuid1, uuid2);
831 /// ```
832 pub const fn as_uuid(&self) -> &Uuid {
833 &self.0
834 }
835
836 /// Convert the builder into a [`Uuid`].
837 ///
838 /// # Examples
839 ///
840 /// Basic usage:
841 ///
842 /// ```
843 /// # use uuid::Builder;
844 /// let uuid = Builder::nil().into_uuid();
845 ///
846 /// assert_eq!(
847 /// uuid.hyphenated().to_string(),
848 /// "00000000-0000-0000-0000-000000000000"
849 /// );
850 /// ```
851 pub const fn into_uuid(self) -> Uuid {
852 self.0
853 }
854}
855
856#[doc(hidden)]
857impl Builder {
858 #[deprecated(
859 since = "1.10.0",
860 note = "use `Builder::from_gregorian_timestamp(ticks, counter, node_id)`"
861 )]
862 pub const fn from_rfc4122_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self {
863 Builder::from_gregorian_timestamp(ticks, counter, node_id)
864 }
865
866 #[deprecated(
867 since = "1.10.0",
868 note = "use `Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)`"
869 )]
870 pub const fn from_sorted_rfc4122_timestamp(
871 ticks: u64,
872 counter: u16,
873 node_id: &[u8; 6],
874 ) -> Self {
875 Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)
876 }
877}