Debian Codegraph @

.cargo/vendor/uuid/src/builder.rs

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