diff --git a/README.md b/README.md index d9b3048..40bd514 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # stduuid -A C++ cross-platform implementation **for universally unique identifiers**, simply know as either UUID or GUID (mostly on Windows). A UUID is a 128-bit number used to uniquely identify information in computer systems, such as database table keys, COM interfaces, classes and type libraries, and many others. +A C++ cross-platform single-header library implementation **for universally unique identifiers**, simply know as either UUID or GUID (mostly on Windows). A UUID is a 128-bit number used to uniquely identify information in computer systems, such as database table keys, COM interfaces, classes and type libraries, and many others. For information about UUID/GUIDs see: * [Universally unique identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier) @@ -7,16 +7,39 @@ For information about UUID/GUIDs see: ## Library overview The library defines a namespace `uuids` with the following types and functions: -* `uuid` is a class representing a UUID; this can be default constructed (a nil UUID), constructed from an array of bytes, or from a string. -sentation (in lowercase) -* `uuid_variant` is a strongly type enum representing the type of a UUID -* `uuid_version` is a strongly type enum representing the version of a UUID -* `make_uuid` is a parameterless function that creates a new UUID using the typical platform-specific method to create one (`CoCreateGuid` on Windows, `uuid_generate` on Linux, `CFUUIDCreate` on Mac). -* `operator==` and `operator!=` for UUIDs comparison for equality/inequality -* `operator<` for comparing whether one UUIDs is less than another. Although this operation does not make much logical sense, it is necessary in order to store UUIDs in a std::set. -* `operator<<` to write a UUID to an output string using the standard repre -* `std::swap<>` specialization for `uuid` -* `std::hash<>` specialization for `uuid`, necessary for storing UUIDs in unordered associative containers, such as `std::unordered_set` + +Basic types: + +| Name | Description | +| ---- | ----------- | +| `uuid` | a class representing a UUID; this can be default constructed (a nil UUID), constructed from a range (defined by a pair of iterators), or from a string. | +| `uuid_variant` | a strongly type enum representing the type of a UUID | +| `uuid_version` | a strongly type enum representing the version of a UUID | + +Generators: + +| Name | Description | +| ---- | ----------- | +| `uuid_default_generator` | a function object that generates new UUIDs, using an operating system method to create one (`CoCreateGuid` on Windows, `uuid_generate` on Linux, `CFUUIDCreate` on Mac) | +| ` basic_uuid_random_generator` | a function object that generates version 4 UUIDs using a pseudo-random number generator engine. | +| `uuid_random_generator` | a basic_uuid_random_generator using the Marsenne Twister engine, i.e. `basic_uuid_random_generator` | + +Utilities: + +| Name | Description | +| ---- | ----------- | +| `std::swap<>` | specialization of `swap` for `uuid` | +| `std::hash<>` | specialization of `hash` for `uuid` (necessary for storing UUIDs in unordered associative containers, such as `std::unordered_set`) | + +Other: + +| Name | Description | +| ---- | ----------- | +| `operator==` and `operator!=` | for UUIDs comparison for equality/inequality | +| `operator<` | for comparing whether one UUIDs is less than another. Although this operation does not make much logical sense, it is necessary in order to store UUIDs in a std::set. | +| `operator<<` | to write a UUID to an output stream using the canonical textual representation. | +| `to_string()` | creates a `std::string` with the canonical textual representation of a UUID. | +| `to_wstring()` | creates a `std::wstring` with the canonical textual representation of a UUID. | This project is currently under development and should be ignored until further notice. @@ -30,7 +53,7 @@ assert(empty.size() == 16); ``` * Creating a new UUID ``` -uuid const guid = uuids::make_uuid(); +uuid const guid = uuids::uuid_default_generator{}(); assert(!guid.nil()); assert(guid.size() == 16); assert(guid.version() == uuids::uuid_version::random_number_based); @@ -52,31 +75,30 @@ assert(guid.wstring() == str); ``` * Creating a UUID from an array ``` -std::array arr{{ - std::byte{ 0x47 }, std::byte{ 0x18 }, std::byte{ 0x38 }, std::byte{ 0x23 }, - std::byte{ 0x25 }, std::byte{ 0x74 }, - std::byte{ 0x4b }, std::byte{ 0xfd }, - std::byte{ 0xb4 }, std::byte{ 0x11 }, - std::byte{ 0x99 }, std::byte{ 0xed }, std::byte{ 0x17 }, std::byte{ 0x7d }, std::byte{ 0x3e }, std::byte{ 0x43 } -}}; +std::array arr{{ + 0x47, 0x18, 0x38, 0x23, + 0x25, 0x74, + 0x4b, 0xfd, + 0xb4, 0x11, + 0x99, 0xed, 0x17, 0x7d, 0x3e, 0x43}}; uuid guid(std::begin(arr), std::end(arr)); assert(id.string() == "47183823-2574-4bfd-b411-99ed177d3e43"); ``` or ``` -std::byte arr[16] = { - std::byte{ 0x47 }, std::byte{ 0x18 }, std::byte{ 0x38 }, std::byte{ 0x23 }, - std::byte{ 0x25 }, std::byte{ 0x74 }, - std::byte{ 0x4b }, std::byte{ 0xfd }, - std::byte{ 0xb4 }, std::byte{ 0x11 }, - std::byte{ 0x99 }, std::byte{ 0xed }, std::byte{ 0x17 }, std::byte{ 0x7d }, std::byte{ 0x3e }, std::byte{ 0x43 } }; +uuids::uuid::value_type arr[16] = { + 0x47, 0x18, 0x38, 0x23, + 0x25, 0x74, + 0x4b, 0xfd, + 0xb4, 0x11, + 0x99, 0xed, 0x17, 0x7d, 0x3e, 0x43 }; uuid guid(std::begin(arr), std::end(arr)); assert(guid.string() == "47183823-2574-4bfd-b411-99ed177d3e43"); ``` * Comparing UUIDS ``` uuid empty; -uuid guid = uuids::make_uuid(); +uuid guid = uuids::uuid_default_generator{}(); assert(empty == empty); assert(guid == guid); @@ -85,7 +107,7 @@ assert(empty != guid); * Swapping UUIDS ``` uuid empty; -uuid guid = uuids::make_uuid(); +uuid guid = uuids::uuid_default_generator{}(); assert(empty.nil()); assert(!guid.nil()); @@ -103,18 +125,17 @@ assert(!guid.nil()); * Converting to string ``` uuid empty; -assert(empty.string() == "00000000-0000-0000-0000-000000000000"); -assert(empty.wstring() == L"00000000-0000-0000-0000-000000000000"); +assert(uuids::to_string(empty) == "00000000-0000-0000-0000-000000000000"); +assert(uuids::to_wstring(empty) == L"00000000-0000-0000-0000-000000000000"); ``` * Iterating through the UUID data ``` -std::array arr{{ - std::byte{ 0x47 }, std::byte{ 0x18 }, std::byte{ 0x38 }, std::byte{ 0x23 }, - std::byte{ 0x25 }, std::byte{ 0x74 }, - std::byte{ 0x4b }, std::byte{ 0xfd }, - std::byte{ 0xb4 }, std::byte{ 0x11 }, - std::byte{ 0x99 }, std::byte{ 0xed }, std::byte{ 0x17 }, std::byte{ 0x7d }, std::byte{ 0x3e }, std::byte{ 0x43 } -}}; +std::array arr{{ + 0x47, 0x18, 0x38, 0x23, + 0x25, 0x74, + 0x4b, 0xfd, + 0xb4, 0x11, + 0x99, 0xed, 0x17, 0x7d, 0x3e, 0x43}}; uuid guid; assert(guid.nil()); @@ -129,26 +150,16 @@ for (auto const & b : guid) ``` * Using with an orderered associative container ``` -std::set ids{ - uuid{}, - uuids::make_uuid(), - uuids::make_uuid(), - uuids::make_uuid(), - uuids::make_uuid() -}; +uuids::uuid_default_generator gen; +std::set ids{uuid{}, gen(), gen(), gen(), gen()}; assert(ids.size() == 5); assert(ids.find(uuid{}) != ids.end()); ``` * Using in an unordered associative container ``` -std::unordered_set ids{ - uuid{}, - uuids::make_uuid(), - uuids::make_uuid(), - uuids::make_uuid(), - uuids::make_uuid() -}; +uuids::uuid_default_generator gen; +std::unordered_set ids{uuid{}, gen(), gen(), gen(), gen()}; assert(ids.size() == 5); assert(ids.find(uuid{}) != ids.end());