euui 1.3.0

An Extended Universal Unique Identifier
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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

# Euui - Extended Universal Unique Identifier

## Description

`Euui` is a Rust library (`no_std` compatible) that provides a 512-bit (64 bytes) unique identifier, which is **4 times
larger** than traditional UUIDs or GUIDs. This allows for enhanced uniqueness and adaptability in scenarios where more
significant identifiers are required.

The `Euui` type can be utilized for various applications, offering readable formats and flexible access to its
components (`Uuid`, `u128`, `u64`, `u8`), for unique identification in embedded or resource-constrained environments.

### Key Features

- **Size**: A single `Euui` consists of 512 bits (64 bytes), making it exceptionally unique.
- **Formatting**:
    - A raw hexadecimal string representation of 128 characters.
    - A formatted string with 131 characters, including separators (`-`) and line breaks (`\n`).

- **Components Access**:
    - Retrieve identifiers parts as 4×`u128`, 8×`u64`, 64×`u8` or 4x`Uuid` (with the feature `uuid`).

- **Generation**:
    - Create a zero-initialized `Euui` using `default()`.
    - Generate a random `Euui` using `random()`.

## Usage

Here are examples of how to use the `Euui` library:

### Creation and Basic Operations

```rust
use euui::Euui;

fn test() {
    // Generate a zero-initialized Euui
    let zero_euui = Euui::default();
    println!("Zero Euui: {}", zero_euui);

    // Generate a random Euui
    let random_euui = Euui::random();
    println!("Random Euui: {}", random_euui);

    // Format the Euui into a readable structure
    println!("Formatted Euui:\n{}", random_euui.format());
}
```

### Accessing Parts of an Euui

You can retrieve specific components (`u128`, `u64`, or `u8`) of the `Euui` as needed:

```rust
// Access one of the u128 components

fn test() {
    if let Some(first_u128) = random_euui.u128(0) {
        println!("First u128: {:032x}", first_u128);
    }

    // Access one of the u64 components
    if let Some(second_u64) = random_euui.u64(1) {
        println!("Second u64: {:016x}", second_u64);
    }

    // Access one of the u8 components
    if let Some(last_u8) = random_euui.u8(63) {
        println!("Last u8: {:02x}", last_u8);
    }
}
```

### Advanced Initialization

You can initialize an `Euui` using custom GUIDs or bytes:

#### From GUIDs (`u128` array)

```rust
pub fn test() {
    let guids = [
        0x1234567890abcdef1234567890abcdef,
        0xabcdef1234567890abcdef1234567890,
        0x7890abcdef1234567890abcdef123456,
        0x567890abcdef1234567890abcdef1234,
    ];
    let euui = Euui::from_be_guids(guids);
}
```

#### From Bytes (`u8` array)

```rust
pub fn test() {
    let bytes = [0x12, 0x34, /* 61 other bytes... */ 0xef];
    let euui = Euui::from_be_bytes(bytes);
}
```

## API Overview

The main functionalities of the `Euui` type are:

### Creation Methods

- **`Euui::zero() -> Euui`**
- **`Euui::default() -> Euui`**
- **`Euui::from_be_guids([u128; 4]) -> Euui`**
- **`Euui::from_be_longs([u64; 8]) -> Euui`**
- **`Euui::from_be_bytes([u8; 64]) -> Euui`**

### Accessor Methods

- **`u128(index: usize) -> Option<u128>`**
- **`u64(index: usize) -> Option<u64>`**
- **`u8(index: usize) -> Option<u8>`**
- **`to_be_bytes() -> [u8; 64]`** `Euui`
- **`to_be_longs() -> [u64; 8]`** `Euui`
- **`to_be_guids() -> [u128; 4]`** `Euui`

### Display Methods

- **`to_string()`**  
  Converts the `Euui` to a single hexadecimal string representation.
- **`format() -> String`**  
  Formats the `Euui` into a structured string, following the pattern:
```
#1-#2  
#3-#4
```  

### Features

#### With the feature `random`

- **`Euui::random() -> Euui`**
- **`Euui::random_from_first(u128)`**   
  & (`random_from_second`, `random_from_third`, `random_from_fourth`)
- **`Euui::regenerate_first(&self)`**    
  & (`regenerate_second`, `regenerate_third`, `regenerate_fourth`).

#### With the feature `uuid`

- **`Euui::with_uuid_part(Uuid, usize)`**  
  & (`with_first(Uuid)`, `with_second`, `with_third`, `with_fourth`).
- **`Euui::from_uuids([Uuid; 4])`**
- **`uuid(index: usize) -> Option<Uuid>`**

#### With the feature `random_uuid`

- **`Euui::random_uuids()`** (`Uuid:v4`)

### Documentation

> Read the complete API documentation [here](https://docs.rs/euui).

## Use Cases : Large-Scale Unique ID Generation

With 512 bits of entropy, `Euui` can be useful for applications where traditional 128-bit UUIDs are insufficient:

- Large enough to have **UUID/GUID parts**,
- Distributed systems,
- Cryptographic key identifiers,
- Unique identifiers in high-throughput environments.

## License

&copy; 2024-2025 [Sébastien GELDREICH](mailto:dev@trehinos.eu)  
This project is licensed under the MIT License. See [LICENSE](LICENSE) for more details.