stduuid

A C++17 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
• A Universally Unique IDentifier (UUID) URN Namespace

Library overview

Although the specification puts the uuid library in the std namespace, this implementation uses the namespace uuids for this purpose, in order to make the library usable without violating the restrictions imposed on the std namespace. The following types and utilities are available:

Basic types:

Generators:

Utilities:

Constants:

Other:

Library history

This library is an implementation of the proposal P0959.

As the proposal evolves based on the standard committee 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:

• Creating a nil UUID

  uuid empty;
  assert(empty.is_nil());
  

• Creating a new UUID

  uuid const id = uuids::uuid_system_generator{}();
  assert(!id.is_nil());
  assert(id.version() == uuids::uuid_version::random_number_based);
  assert(id.variant() == uuids::uuid_variant::rfc);
  

• Creating a new UUID with a default random generator

  std::random_device rd;
  auto seed_data = std::array<int, std::mt19937::state_size> {};
  std::generate(std::begin(seed_data), std::end(seed_data), std::ref(rd));
  std::seed_seq seq(std::begin(seed_data), std::end(seed_data));
  std::mt19937 generator(seq);
  uuids::uuid_random_generator gen{generator};
  
  uuid const id = gen();
  assert(!id.is_nil());
  assert(id.as_bytes().size() == 16);
  assert(id.version() == uuids::uuid_version::random_number_based);
  assert(id.variant() == uuids::uuid_variant::rfc);
  

• Creating a new UUID with a particular random generator

  std::random_device rd;
  auto seed_data = std::array<int, 6> {};
  std::generate(std::begin(seed_data), std::end(seed_data), std::ref(rd));
  std::seed_seq seq(std::begin(seed_data), std::end(seed_data));
  std::ranlux48_base generator(seq);
  
  uuids::basic_uuid_random_generator<std::ranlux48_base> gen(&generator);
  uuid const id = gen();
  assert(!id.is_nil());
  assert(id.as_bytes().size() == 16);
  assert(id.version() == uuids::uuid_version::random_number_based);
  assert(id.variant() == uuids::uuid_variant::rfc);
  

• Creating a new UUID with the name generator

  uuids::uuid_name_generator gen(uuids::uuid::from_string("47183823-2574-4bfd-b411-99ed177d3e43").value());
  uuid const id = gen("john");
  
  assert(!id.is_nil());
  assert(id.version() == uuids::uuid_version::name_based_sha1);
  assert(id.variant() == uuids::uuid_variant::rfc);
  

• Create a UUID from a string

  auto str = "47183823-2574-4bfd-b411-99ed177d3e43"s;
  auto id = uuids::uuid::from_string(str);
  assert(id.has_value());
  assert(uuids::to_string(id.value()) == str);
  
  // or
  
  auto str = L"47183823-2574-4bfd-b411-99ed177d3e43"s;
  uuid id = uuids::uuid::from_string(str).value();
  assert(uuids::to_string<wchar_t>(id) == str);
  

• Creating a UUID from a sequence of 16 bytes

  std::array<uuids::uuid::value_type, 16> arr{{
     0x47, 0x18, 0x38, 0x23,
     0x25, 0x74,
     0x4b, 0xfd,
     0xb4, 0x11,
     0x99, 0xed, 0x17, 0x7d, 0x3e, 0x43}};
  uuid id(arr);
  
  assert(uuids::to_string(id) == "47183823-2574-4bfd-b411-99ed177d3e43");
  
  // or
  
  uuids::uuid::value_type arr[16] = {
     0x47, 0x18, 0x38, 0x23,
     0x25, 0x74,
     0x4b, 0xfd,
     0xb4, 0x11,
     0x99, 0xed, 0x17, 0x7d, 0x3e, 0x43 };
  uuid id(std::begin(arr), std::end(arr));
  assert(uuids::to_string(id) == "47183823-2574-4bfd-b411-99ed177d3e43");
  
  // or 
  
  uuids::uuid id{{
     0x47, 0x18, 0x38, 0x23,
     0x25, 0x74,
     0x4b, 0xfd,
     0xb4, 0x11,
     0x99, 0xed, 0x17, 0x7d, 0x3e, 0x43}};
  
  assert(uuids::to_string(id) == "47183823-2574-4bfd-b411-99ed177d3e43");
  

• Comparing UUIDs

  uuid empty;
  uuid id = uuids::uuid_system_generator{}();
  assert(empty == empty);
  assert(id == id);
  assert(empty != id);
  

• Swapping UUIDs

  uuid empty;
  uuid id = uuids::uuid_system_generator{}();
  
  assert(empty.is_nil());
  assert(!id.is_nil());
  
  std::swap(empty, id);
  
  assert(!empty.is_nil());
  assert(id.is_nil());
  
  empty.swap(id);
  
  assert(empty.is_nil());
  assert(!id.is_nil());
  

• Converting to string

  uuid empty;
  assert(uuids::to_string(empty) == "00000000-0000-0000-0000-000000000000");
  assert(uuids::to_string<wchar_t>(empty) == L"00000000-0000-0000-0000-000000000000");
  

• Using with an orderered associative container

  std::random_device rd;
  auto seed_data = std::array<int, std::mt19937::state_size> {};
  std::generate(std::begin(seed_data), std::end(seed_data), std::ref(rd));
  std::seed_seq seq(std::begin(seed_data), std::end(seed_data));
  std::mt19937 engine(seq);
  uuids::uuid_random_generator gen(&engine);
   
  std::set<uuids::uuid> ids{uuid{}, gen(), gen(), gen(), gen()};
  
  assert(ids.size() == 5);
  assert(ids.find(uuid{}) != ids.end());
  

• Using in an unordered associative container

  std::random_device rd;
  auto seed_data = std::array<int, std::mt19937::state_size> {};
  std::generate(std::begin(seed_data), std::end(seed_data), std::ref(rd));
  std::seed_seq seq(std::begin(seed_data), std::end(seed_data));
  std::mt19937 engine(seq);
  uuids::uuid_random_generator gen(&engine);
  
  std::unordered_set<uuids::uuid> ids{uuid{}, gen(), gen(), gen(), gen()};
  
  assert(ids.size() == 5);
  assert(ids.find(uuid{}) != ids.end());
  

• Hashing UUIDs

  using namespace std::string_literals;
  auto str = "47183823-2574-4bfd-b411-99ed177d3e43"s;
  uuid id = uuids::uuid::from_string(str).value();
  
  auto h1 = std::hash<std::string>{};
  auto h2 = std::hash<uuid>{};
  assert(h1(str) == h2(id));
  

Support

The library is supported on all major operating systems: Windows, Linux and Mac OS.

Dependencies

Because no major compiler supports std::span yet the Microsoft Guidelines Support Library (aka GSL) is used for its span implementation (from which the standard version was defined).

Testing

A testing project is available in the sources. To build and execute the tests do the following:

• Clone or download this repository
• Create a build directory in the root directory of the sources
• Run the command cmake .. from the build directory; if you do not have CMake you must install it first.
• Build the project created in the previous step
• Run the executable.

Credits

The SHA1 implementation is based on the TinySHA1 library.