AuroraMiddleware/stduuid
1
0
Fork 0
Code Issues 1 Pull Requests Releases Wiki Activity

added UUID format specification from RFC 4122 and revision history section

Browse Source
This commit is contained in:
Marius Bancila 2018-06-27 16:16:11 +03:00
parent 54b54bdab5
commit 50e9562617
2 changed files with 86 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
P0959.md
View File

@ -1,14 +1,35 @@
| | |
| --- | --- |
| Doc. No.: | P0959R0 |
| Date: | 2018-02-12 |
| Doc. No.: | P0959R1 |
| Date: | 2018-06-27 |
| Reply to: | Marius Bancila |
| Audience: | Library WG |
| Title: | A Proposal for a Universally Unique Identifier Library |
# A Proposal for a Universally Unique Identifier Library
## I. Motivation
## I. Revision History
### 1.1 P0959R0
Original UUID library paper with motivation, specification, and examples.
### 1.2 P0959R1
Revised with feedback from the LWG and the community.
* Removed string constructors and replaced with free overloaded function `from_string()`.
* Parsing strings to `uuid` throws exception `uuid_error` instead of creating a nil uuid when the operation fails.
* {} included in the supported format, i.e. `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`.
* Removed `state_size`.
* Rename member function `nil()` to `is_nil()`.
* The default constructor is defaulted.
* Added a conversion construct from `std::span<uint_8, 16>`.
* Added the free function `as_bytes()` to convert the `uuid` into a view of its underlying bytes.
* Constructing a `uuid` from a range with a size other than 16 is undefined behaviour.
* Removed mutable iterators (but preserved the constant iterators).
* Removed typedefs and others container-like parts.
* Defined the correlation between the interal UUID bytes and the string representation.
* Added UUID layout and byte order specification from the RFC 4122 document.
## II. Motivation
Universally unique identifiers (*uuid*), also known as Globally Unique Identifiers (*guid*s), are commonly used in many types of applications to uniquely identify data. A standard uuid library would benefit developers that currently have to either use operating system specific APIs for creating new uuids or resort to 3rd party libraries, such as *boost::uuid*.
@ -16,11 +37,11 @@ UUIDs are 128-bit numbers that are for most practical purposes unique, without d
The library proposed on this paper is a light one: it enables developers to generate random and name-based UUIDs, serialize and deserialize UUIDs to and from strings, validate UUIDs and other common operations.
## II. Impact On the Standard
## III. Impact On the Standard
This proposal is a pure library extension. It does not require changes to any standard classes, functions or headers. It does not require any changes in the core language, and it has been implemented in standard C++ as per ISO/IEC 14882:2017. The implementation is available at https://github.com/mariusbancila/stduuid.
## III. Design Decisions
## IV. Design Decisions
The proposed library, that should be available in a new header called `<uuid>` in the namespace `std`, provides:
* a class called `uuid` that represents a universally unique identifier
@ -190,6 +211,8 @@ auto id1 = from_string("47183823-2574-4bfd-b411-99ed177d3e43");
auto id2 = from_string(L"{47183823-2574-4bfd-b411-99ed177d3e43}");
```
The order of the bytes in the input string reflects directly into the internal representation of the UUID. That is, for an input string in the form `"aabbccdd-eeff-gghh-iijj-kkllmmnnoopp"` or `"{aabbccdd-eeff-gghh-iijj-kkllmmnnoopp}"` the internal byte order of the resulted UUID is `aa,bb,cc,dd,ee,ff,gg,hh,ii,jj,kk,ll,mm,nn,oo,pp`.
### String conversion
Non-member functions `to_string()` and `to_wstring()` return a string with the UUID formatted to the canonical textual representation `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, where `x` is a lower case hexadecimal digit.
@ -200,6 +223,8 @@ assert(to_string(id) == "47183823-2574-4bfd-b411-99ed177d3e43");
assert(to_wstring(id) == L"47183823-2574-4bfd-b411-99ed177d3e43");
```
The order of the internal UUID bytes reflects directly into the string bytes order. That is, for a UUID with the internal bytes in the form `aa,bb,cc,dd,ee,ff,gg,hh,ii,jj,kk,ll,mm,nn,oo,pp` the resulted string has the form `"aabbccdd-eeff-gghh-iijj-kkllmmnnoopp"`.
### `operator==` and `operator!=`
Non-member `operators ==` and `operator !=` are provided in order to test the equality/inequality of two `uuid` values.
@ -326,7 +351,7 @@ assert(id2 == id3);
assert(id3 != id4);
```
## IV. Technical Specifications
## V. Technical Specifications
### Header
Add a new header called `<uuid>`.
@ -491,7 +516,60 @@ namespace std {
}
```
## V. References
## VI. UUID format specification
The content of this section is copied from the RFC 4122 document that describes the UUID standard.
The UUID format is 16 octets; some bits of the eight octet variant field determine the layout of the UUID. That is, the interpretation of all other bits in the UUID depends on the setting of the bits in the variant field. The variant field consists of a variable number of the most significant bits of octet 8 of the UUID. The following table lists the contents of the variant field, where the letter "x" indicates a "don't-care" value.
| Msb0 | Msb1 | Msb2 | Description |
| ---- | ---- | ---- | ----------- |
| 0 | x | x | Reserved, NCS backward compatibility. |
| 1 | 0 | x | The variant specified in this document. |
| 1 | 1 | 0 | Reserved, Microsoft Corporation backward compatibility. |
| 1 | 1 | 1 | Reserved for future definition. |
Only UUIDs of the variant with the bit pattern 10x are considered in this document. All the other references to UUIDs in this document refer to this variant. For simplicity, we will call this the RFC variant UUID.
The UUID record definition is defined only in terms of fields that are integral numbers of octets. The fields are presented with the most significant one first.
| Field | Data Type | Octet number | Note |
| ----- | --------- | ------------ | ---- |
| `time_low` | unsigned 32 bit integer | 0-3 | The low field of the timestamp |
| `time_mid` | unsigned 16 bit integer | 4-5 | The middle field of the timestamp |
| `time_hi_and_version` | unsigned 16 bit integer | 6-7 | The high field of the timestamp multiplexed with the version number |
| `clock_seq_hi_and_reserved` | unsigned 8 bit integer | 8 | The high field of the clock sequence multiplexed with the variant |
| `clock_seq_low` | unsigned 8 bit integer | 9 | The low field of the clock sequence |
| `node` | unsigned 48 bit integer | 10-15 | The spatially unique node identifier |
In the absence of explicit application or presentation protocol specification to the contrary, a UUID is encoded as a 128-bit object, as follows:
The fields are encoded as 16 octets, with the sizes and order of the fields defined above, and with each field encoded with the Most Significant Byte first (known as network byte order).
```
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| time_low |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| time_mid | time_hi_and_version |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|clk_seq_hi_res | clk_seq_low | node (0-1) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| node (2-5) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
The version number is in the most significant 4 bits of the timestamp (bits 4 through 7 of the `time_hi_and_version` field). The following table lists the currently-defined versions for the RFC variant.
| Msb0 | Msb1 | Msb2 | Msb3 | Version | Description |
| ---- | ---- | ---- | ---- | ------- | ----------- |
| 0 | 0 | 0 | 1 | 1 | The time-based version specified in this document. |
| 0 | 0 | 1 | 0 | 2 | DCE Security version, with embedded POSIX UIDs. |
| 0 | 0 | 1 | 1 | 3 | The name-based version specified in this document that uses MD5 hashing. |
| 0 | 1 | 0 | 0 | 4 | The randomly or pseudo-randomly generated version specified in this document. |
| 0 | 1 | 0 | 1 | 5 | The name-based version specified in this document that uses SHA-1 hashing. |
## VII. References
* [1] Universally unique identifier, https://en.wikipedia.org/wiki/Universally_unique_identifier
* [2] A Universally Unique IDentifier (UUID) URN Namespace, https://tools.ietf.org/html/rfc4122

16
README.md
View File

@ -45,21 +45,7 @@ Other:
This project is currently under development and should be ignored until further notice.
## Library history
This library is an implementation of the proposal P0959. As the proposal evolves based on the standard commity and the C++ community feedback, this library implementation will reflect those changes.
### Revision 1
Changes from the first draft:
* Removed string constructors and replaced with free overloaded function `from_string()`.
* Parsing strings to `uuid` throws exception `uuid_error` instead of creating a nil uuid when the operation fails.
* {} included in the supported format, i.e. `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`.
* Removed `state_size`.
* Rename member function `nil()` to `is_nil()`.
* The default constructor is defaulted.
* Added a conversion construct from `std::span<uint_8, 16>`.
* Added the free function `as_bytes()` to convert the `uuid` into a view of its underlying bytes.
* Constructing a `uuid` from a range with a size other than 16 is undefined behaviour.
* Removed mutable iterators (but preserved the constant iterators).
* Removed typedefs and others container-like parts.
This library is an implementation of the proposal [P0959](P0959.md). As the proposal evolves based on the standard commity and the C++ community feedback, this library implementation will reflect those changes. See the revision history of the proposal for history of changes.
## Using the library
The following is a list of examples for using the library: