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