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