| 1 |
# `uuid` |
| 2 |
|
| 3 |
[](https://crates.io/crates/uuid) |
| 4 |
[](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 |
[](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. |