README.md
1# `uuid`
2
3[](https://crates.io/crates/uuid)
4[](https://github.com/uuid-rs/uuid/actions/workflows/ci.yml)
5
6Here's an example of a UUID:
7
8```text
967e55044-10b1-426f-9247-bb680e5fe0c8
10```
11
12A UUID is a unique 128-bit value, stored as 16 octets, and regularly
13formatted as a hex string in five groups. UUIDs are used to assign unique
14identifiers to entities without requiring a central allocating authority.
15
16They are particularly useful in distributed systems, though can be used in
17disparate areas, such as databases and network protocols. Typically a UUID
18is displayed in a readable string form as a sequence of hexadecimal digits,
19separated into groups by hyphens.
20
21The uniqueness property is not strictly guaranteed, however for all
22practical purposes, it can be assumed that an unintentional collision would
23be extremely unlikely.
24
25## Getting started
26
27Add the following to your `Cargo.toml`:
28
29```toml
30[dependencies.uuid]
31version = "1.7.0"
32features = [
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
39When you want a UUID, you can generate one:
40
41```rust
42use uuid::Uuid;
43
44let id = Uuid::new_v4();
45```
46
47If you have a UUID value, you can use its string literal form inline:
48
49```rust
50use uuid::{uuid, Uuid};
51
52const ID: Uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");
53```
54
55You can also parse UUIDs without needing any crate features:
56
57```rust
58use uuid::{Uuid, Version};
59
60let my_uuid = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8")?;
61
62assert_eq!(Some(Version::Random), my_uuid.get_version());
63```
64
65If you'd like to parse UUIDs _really_ fast, check out the [`uuid-simd`](https://github.com/nugine/uuid-simd)
66library.
67
68For more details on using `uuid`, [see the library documentation](https://docs.rs/uuid/1.7.0/uuid).
69
70## References
71
72* [`uuid` library docs](https://docs.rs/uuid/1.7.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
76---
77# License
78
79Licensed under either of
80
81* Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
82* MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
83
84at your option.
85
86
87[](https://app.fossa.com/projects/git%2Bgithub.com%2Fuuid-rs%2Fuuid?ref=badge_large)
88
89## Contribution
90
91Unless you explicitly state otherwise, any contribution intentionally submitted
92for inclusion in the work by you, as defined in the Apache-2.0 license, shall
93be dual licensed as above, without any additional terms or conditions.
94
){kind=link}
){kind=link}
){kind=link}