README.md
1uuid
2---------
3
4[](https://crates.io/crates/uuid)
5[](https://gitter.im/uuid-rs/Lobby?utm_source=badge&utm_medium=badge&utm_content=badge)
6
7[](https://ci.appveyor.com/project/uuid-rs/uuid/branch/master)
8[](https://travis-ci.org/uuid-rs/uuid)
9[](https://isitmaintained.com/project/uuid-rs/uuid "Average time to resolve an issue")
10[](https://isitmaintained.com/project/uuid-rs/uuid "Percentage of issues still open")
11[](https://app.fossa.com/projects/git%2Bgithub.com%2Fuuid-rs%2Fuuid?ref=badge_shield)
12
13---
14
15Generate and parse UUIDs.
16
17Provides support for Universally Unique Identifiers (UUIDs). A UUID is a
18unique 128-bit number, stored as 16 octets. UUIDs are used to assign
19unique identifiers to entities without requiring a central allocating
20authority.
21
22They are particularly useful in distributed systems, though they can be used in
23disparate areas, such as databases and network protocols. Typically a UUID
24is displayed in a readable string form as a sequence of hexadecimal digits,
25separated into groups by hyphens.
26
27The uniqueness property is not strictly guaranteed, however for all
28practical purposes, it can be assumed that an unintentional collision would
29be extremely unlikely.
30
31## Dependencies
32
33By default, this crate depends on nothing but `std` and cannot generate
34[`Uuid`]s. You need to enable the following Cargo features to enable
35various pieces of functionality:
36
37* `v1` - adds the `Uuid::new_v1` function and the ability to create a V1
38 using an implementation of `uuid::v1::ClockSequence` (usually
39`uuid::v1::Context`) and a timestamp from `time::timespec`.
40* `v3` - adds the `Uuid::new_v3` function and the ability to create a V3
41 UUID based on the MD5 hash of some data.
42* `v4` - adds the `Uuid::new_v4` function and the ability to randomly
43 generate a `Uuid`.
44* `v5` - adds the `Uuid::new_v5` function and the ability to create a V5
45 UUID based on the SHA1 hash of some data.
46* `serde` - adds the ability to serialize and deserialize a `Uuid` using the
47 `serde` crate.
48
49You need to enable one of the following Cargo features together with
50`v3`, `v4` or `v5` feature if you're targeting `wasm32-unknown-unknown` target:
51
52* `stdweb` - enables support for `OsRng` on `wasm32-unknown-unknown` via
53 `stdweb` combined with `cargo-web`
54* `wasm-bindgen` - `wasm-bindgen` enables support for `OsRng` on
55 `wasm32-unknown-unknown` via [`wasm-bindgen`]
56
57By default, `uuid` can be depended on with:
58
59```toml
60[dependencies]
61uuid = "0.8"
62```
63
64To activate various features, use syntax like:
65
66```toml
67[dependencies]
68uuid = { version = "0.8", features = ["serde", "v4"] }
69```
70
71You can disable default features with:
72
73```toml
74[dependencies]
75uuid = { version = "0.8", default-features = false }
76```
77
78## Examples
79
80To parse a UUID given in the simple format and print it as a urn:
81
82```rust
83use uuid::Uuid;
84
85fn main() -> Result<(), uuid::Error> {
86 let my_uuid =
87 Uuid::parse_str("936DA01F9ABD4d9d80C702AF85C822A8")?;
88 println!("{}", my_uuid.to_urn());
89 Ok(())
90}
91```
92
93To create a new random (V4) UUID and print it out in hexadecimal form:
94
95```rust
96// Note that this requires the `v4` feature enabled in the uuid crate.
97
98use uuid::Uuid;
99
100fn main() {
101 let my_uuid = Uuid::new_v4();
102 println!("{}", my_uuid);
103 Ok(())
104}
105```
106
107## Strings
108
109Examples of string representations:
110
111* simple: `936DA01F9ABD4d9d80C702AF85C822A8`
112* hyphenated: `550e8400-e29b-41d4-a716-446655440000`
113* urn: `urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4`
114
115## References
116
117* [Wikipedia: Universally Unique Identifier]( http://en.wikipedia.org/wiki/Universally_unique_identifier)
118* [RFC4122: A Universally Unique IDentifier (UUID) URN Namespace]( http://tools.ietf.org/html/rfc4122)
119
120[`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen
121
122[`Uuid`]: https://docs.rs/uuid/0.8.2/uuid/struct.Uuid.html
123
124---
125# License
126
127Licensed under either of
128
129* Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
130* MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
131
132at your option.
133
134
135[](https://app.fossa.com/projects/git%2Bgithub.com%2Fuuid-rs%2Fuuid?ref=badge_large)
136
137## Contribution
138
139Unless you explicitly state otherwise, any contribution intentionally submitted
140for inclusion in the work by you, as defined in the Apache-2.0 license, shall
141be dual licensed as above, without any additional terms or conditions.
README.tpl
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}