leachuuid7 0.1.0

A UUIDv7 generator conforming 100% to the proposed UUID-7 specification. Named as a clever homage in the UUID space.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# leachuuid7

A UUIDv7 generator written in Rust, conforming 100% to the proposed UUID-7 specification.  
This crate generates UUIDs using the current Unix timestamp in milliseconds, a version number of 7, the binary variant `10`, and 62 bits of randomness.

## Overview

UUIDv7 is designed with high concurrency in mind and provides an effective means of generating unique identifiers in distributed systems and asynchronous environments.

**UUID layout (128 bits total):**
- **60 bits:** Unix timestamp in milliseconds (since the Unix epoch)
- **4 bits:** Version (always 7)
- **2 bits:** Variant (always binary `10`)
- **62 bits:** Random

The resulting UUID is formatted in the canonical form: `8-4-4-4-12` hexadecimal digits.

## Features

- **Standards-Compliant:** Fully conforms to the UUIDv7 specification.
- **High Concurrency:** Uses thread-local RNG for safe and efficient generation in multi-threaded environments.
- **Custom RNG Support:** Option to inject a custom RNG for greater control over randomness.
- **Robust Parsing:** Validates UUID format, version, and variant.
- **Comprehensive Testing:** Includes unit tests for formatting, parsing, and uniqueness.

## Installation

Add `leachuuid7` to your `Cargo.toml`:

```toml
[dependencies]
leachuuid7 = "0.1.0"
```

## Usage

Generate a new UUIDv7:

```rust
use leachuuid7::Uuid7;

fn main() {
    let uuid = Uuid7::new();
    println!("Generated UUIDv7: {}", uuid);
}
```

Parse a UUIDv7 string:

```rust
use leachuuid7::Uuid7;
use std::str::FromStr;

fn main() {
    let uuid_str = "0184e1a0-7e2a-7d40-8f3b-5c1a2b3c4d5e";
    let uuid = Uuid7::from_str(uuid_str).expect("Invalid UUIDv7 string");
    println!("Parsed UUIDv7: {}", uuid);
}
```

## Testing

Run the tests with:

```bash
cargo test
```

## Continuous Integration

This project uses GitHub Actions for continuous integration. The CI workflow performs:

- Code formatting checks with `cargo fmt`
- Linting with `cargo clippy`
- Running tests with `cargo test`
- Building in release mode with `cargo build --release`
- Packaging the crate with `cargo package`

See [`.github/workflows/ci.yml`](.github/workflows/ci.yml) for more details.

## Contributing

Contributions, issues, and feature requests are welcome!  
Feel free to check the [issues page](https://github.com/copyleftdev/leachuuid7/issues) if you have any questions or suggestions.

## Repository

The repository for this project is hosted on GitHub:  
[https://github.com/copyleftdev/leachuuid7](https://github.com/copyleftdev/leachuuid7)

## License

This project is licensed under the [MIT License](LICENSE).

## Acknowledgements

A special thanks to P. Leach and R. Salz, pioneers in UUID development, for inspiring the naming of this crate.