Debian Codegraph @

.cargo/vendor/uuid/README.md

raw
1 # `uuid`
2
3 [![Latest Version](https://img.shields.io/crates/v/uuid.svg)](https://crates.io/crates/uuid)
4 [![Continuous integration](https://github.com/uuid-rs/uuid/actions/workflows/ci.yml/badge.svg)](https://github.com/uuid-rs/uuid/actions/workflows/ci.yml)
5
6 Here's an example of a UUID:
7
8 ```text
9 67e55044-10b1-426f-9247-bb680e5fe0c8
10 ```
11
12 A UUID is a unique 128-bit value, stored as 16 octets, and regularly
13 formatted as a hex string in five groups. UUIDs are used to assign unique
14 identifiers to entities without requiring a central allocating authority.
15
16 They are particularly useful in distributed systems, though can be used in
17 disparate areas, such as databases and network protocols. Typically a UUID
18 is displayed in a readable string form as a sequence of hexadecimal digits,
19 separated into groups by hyphens.
20
21 The uniqueness property is not strictly guaranteed, however for all
22 practical purposes, it can be assumed that an unintentional collision would
23 be extremely unlikely.
24
25 ## Getting started
26
27 Add the following to your `Cargo.toml`:
28
29 ```toml
30 [dependencies.uuid]
31 version = "1.8.0"
32 features = [
33 "v4", # Lets you generate random UUIDs
34 "fast-rng", # Use a faster (but still sufficiently random) RNG
35 "macro-diagnostics", # Enable better diagnostics for compile-time UUIDs
36 ]
37 ```
38
39 When you want a UUID, you can generate one:
40
41 ```rust
42 use uuid::Uuid;
43
44 let id = Uuid::new_v4();
45 ```
46
47 If you have a UUID value, you can use its string literal form inline:
48
49 ```rust
50 use uuid::{uuid, Uuid};
51
52 const ID: Uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");
53 ```
54
55 You can also parse UUIDs without needing any crate features:
56
57 ```rust
58 use uuid::{Uuid, Version};
59
60 let my_uuid = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8")?;
61
62 assert_eq!(Some(Version::Random), my_uuid.get_version());
63 ```
64
65 If you'd like to parse UUIDs _really_ fast, check out the [`uuid-simd`](https://github.com/nugine/uuid-simd)
66 library.
67
68 For more details on using `uuid`, [see the library documentation](https://docs.rs/uuid/1.8.0/uuid).
69
70 ## References
71
72 * [`uuid` library docs](https://docs.rs/uuid/1.8.0/uuid).
73 * [Wikipedia: Universally Unique Identifier](http://en.wikipedia.org/wiki/Universally_unique_identifier).
74 * [RFC4122: A Universally Unique IDentifier (UUID) URN Namespace](http://tools.ietf.org/html/rfc4122).
75 * [Revision of RFC4122: Universally Unique IDentifiers (UUID)](https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-14.html).
76
77 ---
78 # License
79
80 Licensed under either of
81
82 * Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
83 * MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
84
85 at your option.
86
87
88 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fuuid-rs%2Fuuid.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fuuid-rs%2Fuuid?ref=badge_large)
89
90 ## Contribution
91
92 Unless you explicitly state otherwise, any contribution intentionally submitted
93 for inclusion in the work by you, as defined in the Apache-2.0 license, shall
94 be dual licensed as above, without any additional terms or conditions.