2017-05-23 20:03:07 +03:00
uuid
2019-05-23 22:54:25 +03:00
---------
2017-05-23 20:03:07 +03:00
2019-05-23 22:54:25 +03:00
[![Latest Version ](https://img.shields.io/crates/v/uuid.svg )](https://crates.io/crates/uuid)
2018-10-02 04:50:56 +03:00
[![Join the chat at https://gitter.im/uuid-rs/Lobby ](https://badges.gitter.im/Join%20Chat.svg )](https://gitter.im/uuid-rs/Lobby?utm_source=badge& utm_medium=badge& utm_content=badge)
2019-12-06 03:33:03 +03:00
![Minimum rustc version ](https://img.shields.io/badge/rustc-1.31.0+-yellow.svg )
2019-05-23 22:54:25 +03:00
[![Build Status ](https://ci.appveyor.com/api/projects/status/github/uuid-rs/uuid?branch=master&svg=true )](https://ci.appveyor.com/project/uuid-rs/uuid/branch/master)
[![Build Status ](https://travis-ci.org/uuid-rs/uuid.svg?branch=master )](https://travis-ci.org/uuid-rs/uuid)
[![Average time to resolve an issue ](https://isitmaintained.com/badge/resolution/uuid-rs/uuid.svg )](https://isitmaintained.com/project/uuid-rs/uuid "Average time to resolve an issue")
[![Percentage of issues still open ](https://isitmaintained.com/badge/open/uuid-rs/uuid.svg )](https://isitmaintained.com/project/uuid-rs/uuid "Percentage of issues still open")
2017-05-23 20:03:07 +03:00
2019-05-23 22:54:25 +03:00
---
2017-05-23 20:03:07 +03:00
2019-05-23 22:54:25 +03:00
Generate and parse UUIDs.
Provides support for Universally Unique Identifiers (UUIDs). A UUID is a
unique 128-bit number, stored as 16 octets. UUIDs are used to assign
unique identifiers to entities without requiring a central allocating
authority.
2017-05-23 20:03:07 +03:00
They are particularly useful in distributed systems, though can be used in
2019-05-23 22:54:25 +03:00
disparate areas, such as databases and network protocols. Typically a UUID
is displayed in a readable string form as a sequence of hexadecimal digits,
2017-05-23 20:03:07 +03:00
separated into groups by hyphens.
2019-05-23 22:54:25 +03:00
The uniqueness property is not strictly guaranteed, however for all
practical purposes, it can be assumed that an unintentional collision would
be extremely unlikely.
## Dependencies
By default, this crate depends on nothing but `std` and cannot generate
[`Uuid`]s. You need to enable the following Cargo features to enable
various pieces of functionality:
2017-05-23 20:03:07 +03:00
2019-05-23 22:54:25 +03:00
* `v1` - adds the `Uuid::new_v1` function and the ability to create a V1
using an implementation of `uuid::v1::ClockSequence` (usually
`uuid::v1::Context` ) and a timestamp from `time::timespec` .
* `v3` - adds the `Uuid::new_v3` function and the ability to create a V3
UUID based on the MD5 hash of some data.
* `v4` - adds the `Uuid::new_v4` function and the ability to randomly
generate a `Uuid` .
* `v5` - adds the `Uuid::new_v5` function and the ability to create a V5
UUID based on the SHA1 hash of some data.
* `serde` - adds the ability to serialize and deserialize a `Uuid` using the
`serde` crate.
2017-05-23 20:03:07 +03:00
2019-05-23 22:54:25 +03:00
You need to enable one of the following Cargo features together with
`v3` , `v4` or `v5` feature if you're targeting `wasm32` architecture:
2017-05-23 20:03:07 +03:00
2019-05-23 22:54:25 +03:00
* `stdweb` - enables support for `OsRng` on `wasm32-unknown-unknown` via
`stdweb` combined with `cargo-web`
* `wasm-bindgen` - `wasm-bindgen` enables support for `OsRng` on
`wasm32-unknown-unknown` via [`wasm-bindgen`]
By default, `uuid` can be depended on with:
2017-05-23 20:03:07 +03:00
```toml
[dependencies]
2019-12-06 03:33:03 +03:00
uuid = "0.8"
2017-05-23 20:03:07 +03:00
```
2019-05-23 22:54:25 +03:00
To activate various features, use syntax like:
2019-05-21 22:36:56 +03:00
2019-05-23 22:54:25 +03:00
```toml
[dependencies]
2019-12-06 03:33:03 +03:00
uuid = { version = "0.8", features = ["serde", "v4"] }
2019-05-23 22:54:25 +03:00
```
You can disable default features with:
```toml
[dependencies]
2019-12-06 03:33:03 +03:00
uuid = { version = "0.8", default-features = false }
2017-05-23 20:03:07 +03:00
```
## Examples
2019-05-23 22:54:25 +03:00
To parse a UUID given in the simple format and print it as a urn:
2017-05-23 20:03:07 +03:00
```rust
use uuid::Uuid;
fn main() {
2019-05-23 22:54:25 +03:00
let my_uuid =
Uuid::parse_str("936DA01F9ABD4d9d80C702AF85C822A8").unwrap();
println!("{}", my_uuid.to_urn());
2017-05-23 20:03:07 +03:00
}
```
2019-05-23 22:54:25 +03:00
To create a new random (V4) UUID and print it out in hexadecimal form:
2018-08-09 22:42:17 +03:00
2019-12-06 03:33:03 +03:00
```rust
2019-05-23 22:54:25 +03:00
// Note that this requires the `v4` feature enabled in the uuid crate.
2018-08-08 23:59:21 +03:00
use uuid::Uuid;
fn main() {
2018-08-09 22:42:17 +03:00
let my_uuid = Uuid::new_v4();
println!("{}", my_uuid);
}
```
2019-05-23 22:54:25 +03:00
## Strings
2018-08-09 22:42:17 +03:00
2019-05-23 22:54:25 +03:00
Examples of string representations:
2019-05-21 22:36:56 +03:00
2019-05-23 22:54:25 +03:00
* simple: `936DA01F9ABD4d9d80C702AF85C822A8`
* hyphenated: `550e8400-e29b-41d4-a716-446655440000`
* urn: `urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4`
2019-05-21 22:36:56 +03:00
2019-05-23 22:54:25 +03:00
## References
2019-05-21 22:36:56 +03:00
2019-05-23 22:54:25 +03:00
* [Wikipedia: Universally Unique Identifier ]( http://en.wikipedia.org/wiki/Universally_unique_identifier )
* [RFC4122: A Universally Unique IDentifier (UUID) URN Namespace ]( http://tools.ietf.org/html/rfc4122 )
2019-05-21 22:36:56 +03:00
2019-05-23 22:54:25 +03:00
[`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen
2019-12-06 03:33:03 +03:00
[`Uuid`]: https://docs.rs/uuid/0.8.1/uuid/struct.Uuid.html
2019-05-23 22:54:25 +03:00
---
# License
Licensed under either of
* Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
* MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
## Contribution
2017-05-23 20:03:07 +03:00
2019-05-23 22:54:25 +03:00
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.