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::ByteLength { 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::ByteLength { 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 // SAFETY: `Bytes` and `Uuid` have the same ABI
435 unsafe { &*(bytes as *const Bytes as *const Uuid) }
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::convert::TryInto;
575 /// use std::time::{Duration, SystemTime};
576 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
577 /// # use uuid::{Builder, Uuid, Variant, Version, Timestamp, NoContext};
578 /// # let rng = || [
579 /// # 70, 235, 208, 238, 14, 109, 67, 201, 185, 13
580 /// # ];
581 /// let ts = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)?;
582 ///
583 /// let random_bytes = rng();
584 ///
585 /// let uuid = Builder::from_unix_timestamp_millis(ts.as_millis().try_into()?, &random_bytes).into_uuid();
586 ///
587 /// assert_eq!(Some(Version::SortRand), uuid.get_version());
588 /// assert_eq!(Variant::RFC4122, uuid.get_variant());
589 /// # Ok(())
590 /// # }
591 /// ```
592 pub const fn from_unix_timestamp_millis(millis: u64, counter_random_bytes: &[u8; 10]) -> Self {
593 Builder(timestamp::encode_unix_timestamp_millis(
594 millis,
595 counter_random_bytes,
596 ))
597 }
598
599 /// Creates a `Builder` for a version 8 UUID using the supplied user-defined bytes.
600 ///
601 /// This method won't interpret the given bytes in any way, except to set the appropriate
602 /// bits for the UUID version and variant.
603 pub const fn from_custom_bytes(custom_bytes: Bytes) -> Self {
604 Builder::from_bytes(custom_bytes)
605 .with_variant(Variant::RFC4122)
606 .with_version(Version::Custom)
607 }
608
609 /// Creates a `Builder` using the supplied bytes.
610 ///
611 /// # Errors
612 ///
613 /// This function will return an error if `b` has any length other than 16.
614 ///
615 /// # Examples
616 ///
617 /// Basic usage:
618 ///
619 /// ```
620 /// # use uuid::Builder;
621 /// # fn main() -> Result<(), uuid::Error> {
622 /// let bytes = [
623 /// 0xa1, 0xa2, 0xa3, 0xa4,
624 /// 0xb1, 0xb2,
625 /// 0xc1, 0xc2,
626 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
627 /// ];
628 ///
629 /// let uuid = Builder::from_slice(&bytes)?.into_uuid();
630 ///
631 /// assert_eq!(
632 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
633 /// uuid.hyphenated().to_string(),
634 /// );
635 /// # Ok(())
636 /// # }
637 /// ```
638 pub fn from_slice(b: &[u8]) -> Result<Self, Error> {
639 Ok(Builder(Uuid::from_slice(b)?))
640 }
641
642 /// Creates a `Builder` using the supplied bytes in little endian order.
643 ///
644 /// The individual fields encoded in the buffer will be flipped.
645 ///
646 /// # Errors
647 ///
648 /// This function will return an error if `b` has any length other than 16.
649 ///
650 /// # Examples
651 ///
652 /// Basic usage:
653 ///
654 /// ```
655 /// # use uuid::Builder;
656 /// # fn main() -> Result<(), uuid::Error> {
657 /// let bytes = [
658 /// 0xa1, 0xa2, 0xa3, 0xa4,
659 /// 0xb1, 0xb2,
660 /// 0xc1, 0xc2,
661 /// 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
662 /// ];
663 ///
664 /// let uuid = Builder::from_slice_le(&bytes)?.into_uuid();
665 ///
666 /// assert_eq!(
667 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
668 /// uuid.hyphenated().to_string(),
669 /// );
670 /// # Ok(())
671 /// # }
672 /// ```
673 pub fn from_slice_le(b: &[u8]) -> Result<Self, Error> {
674 Ok(Builder(Uuid::from_slice_le(b)?))
675 }
676
677 /// Creates a `Builder` from four field values.
678 ///
679 /// # Examples
680 ///
681 /// Basic usage:
682 ///
683 /// ```
684 /// # use uuid::Builder;
685 /// let d1 = 0xa1a2a3a4;
686 /// let d2 = 0xb1b2;
687 /// let d3 = 0xc1c2;
688 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
689 ///
690 /// let uuid = Builder::from_fields(d1, d2, d3, &d4).into_uuid();
691 ///
692 /// assert_eq!(
693 /// uuid.hyphenated().to_string(),
694 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
695 /// );
696 /// ```
697 pub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self {
698 Builder(Uuid::from_fields(d1, d2, d3, d4))
699 }
700
701 /// Creates a `Builder` from four field values.
702 ///
703 /// # Examples
704 ///
705 /// Basic usage:
706 ///
707 /// ```
708 /// # use uuid::Builder;
709 /// let d1 = 0xa1a2a3a4;
710 /// let d2 = 0xb1b2;
711 /// let d3 = 0xc1c2;
712 /// let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];
713 ///
714 /// let uuid = Builder::from_fields_le(d1, d2, d3, &d4).into_uuid();
715 ///
716 /// assert_eq!(
717 /// uuid.hyphenated().to_string(),
718 /// "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8"
719 /// );
720 /// ```
721 pub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self {
722 Builder(Uuid::from_fields_le(d1, d2, d3, d4))
723 }
724
725 /// Creates a `Builder` from a 128bit value.
726 ///
727 /// # Examples
728 ///
729 /// Basic usage:
730 ///
731 /// ```
732 /// # use uuid::Builder;
733 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
734 ///
735 /// let uuid = Builder::from_u128(v).into_uuid();
736 ///
737 /// assert_eq!(
738 /// "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
739 /// uuid.hyphenated().to_string(),
740 /// );
741 /// ```
742 pub const fn from_u128(v: u128) -> Self {
743 Builder(Uuid::from_u128(v))
744 }
745
746 /// Creates a UUID from a 128bit value in little-endian order.
747 ///
748 /// # Examples
749 ///
750 /// Basic usage:
751 ///
752 /// ```
753 /// # use uuid::Builder;
754 /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
755 ///
756 /// let uuid = Builder::from_u128_le(v).into_uuid();
757 ///
758 /// assert_eq!(
759 /// "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
760 /// uuid.hyphenated().to_string(),
761 /// );
762 /// ```
763 pub const fn from_u128_le(v: u128) -> Self {
764 Builder(Uuid::from_u128_le(v))
765 }
766
767 /// Creates a `Builder` with an initial [`Uuid::nil`].
768 ///
769 /// # Examples
770 ///
771 /// Basic usage:
772 ///
773 /// ```
774 /// # use uuid::Builder;
775 /// let uuid = Builder::nil().into_uuid();
776 ///
777 /// assert_eq!(
778 /// "00000000-0000-0000-0000-000000000000",
779 /// uuid.hyphenated().to_string(),
780 /// );
781 /// ```
782 pub const fn nil() -> Self {
783 Builder(Uuid::nil())
784 }
785
786 /// Specifies the variant of the UUID.
787 pub fn set_variant(&mut self, v: Variant) -> &mut Self {
788 *self = Builder(self.0).with_variant(v);
789 self
790 }
791
792 /// Specifies the variant of the UUID.
793 pub const fn with_variant(mut self, v: Variant) -> Self {
794 let byte = (self.0).0[8];
795
796 (self.0).0[8] = match v {
797 Variant::NCS => byte & 0x7f,
798 Variant::RFC4122 => (byte & 0x3f) | 0x80,
799 Variant::Microsoft => (byte & 0x1f) | 0xc0,
800 Variant::Future => byte | 0xe0,
801 };
802
803 self
804 }
805
806 /// Specifies the version number of the UUID.
807 pub fn set_version(&mut self, v: Version) -> &mut Self {
808 *self = Builder(self.0).with_version(v);
809 self
810 }
811
812 /// Specifies the version number of the UUID.
813 pub const fn with_version(mut self, v: Version) -> Self {
814 (self.0).0[6] = ((self.0).0[6] & 0x0f) | ((v as u8) << 4);
815
816 self
817 }
818
819 /// Get a reference to the underlying [`Uuid`].
820 ///
821 /// # Examples
822 ///
823 /// Basic usage:
824 ///
825 /// ```
826 /// # use uuid::Builder;
827 /// let builder = Builder::nil();
828 ///
829 /// let uuid1 = builder.as_uuid();
830 /// let uuid2 = builder.as_uuid();
831 ///
832 /// assert_eq!(uuid1, uuid2);
833 /// ```
834 pub const fn as_uuid(&self) -> &Uuid {
835 &self.0
836 }
837
838 /// Convert the builder into a [`Uuid`].
839 ///
840 /// # Examples
841 ///
842 /// Basic usage:
843 ///
844 /// ```
845 /// # use uuid::Builder;
846 /// let uuid = Builder::nil().into_uuid();
847 ///
848 /// assert_eq!(
849 /// uuid.hyphenated().to_string(),
850 /// "00000000-0000-0000-0000-000000000000"
851 /// );
852 /// ```
853 pub const fn into_uuid(self) -> Uuid {
854 self.0
855 }
856}
857
858#[doc(hidden)]
859impl Builder {
860 #[deprecated(
861 since = "1.10.0",
862 note = "use `Builder::from_gregorian_timestamp(ticks, counter, node_id)`"
863 )]
864 pub const fn from_rfc4122_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self {
865 Builder::from_gregorian_timestamp(ticks, counter, node_id)
866 }
867
868 #[deprecated(
869 since = "1.10.0",
870 note = "use `Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)`"
871 )]
872 pub const fn from_sorted_rfc4122_timestamp(
873 ticks: u64,
874 counter: u16,
875 node_id: &[u8; 6],
876 ) -> Self {
877 Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)
878 }
879}