# Boost.Uuid

## Introduction

A UUID, or Universally unique identifier, is intended to uniquely identify information in a distributed environment without significant central coordination. It can be used to tag objects with very short lifetimes, or to reliably identify very persistent objects across a network.

A formal definition for UUID can be found in RFC 4122 and RFC 9562.

UUIDs have many applications. Some examples follow: Databases may use UUIDs to identify rows or records in order to ensure that they are unique across different databases, or for publication/subscription services. Network messages may be identified with a UUID to ensure that different parts of a message are put back together again. Distributed computing may use UUIDs to identify a remote procedure call. Transactions and classes involved in serialization may be identified by UUIDs. Microsoft’s component object model (COM) uses UUIDs to distinguish different software component interfaces. UUIDs are inserted into documents from Microsoft Office programs. UUIDs identify audio or video streams in the Advanced Systems Format (ASF). UUIDs are also a basis for OIDs (object identifiers), and URNs (uniform resource name).

An attractive feature of UUIDs when compared to alternatives is their relative small size, of 128-bits, or 16-bytes. Another is that the creation of UUIDs does not require a centralized authority.

When UUIDs are generated by one of the defined mechanisms, they are either guaranteed to be unique, different from all other generated UUIDs (that is, it has never been generated before and it will never be generated again), or it is extremely likely to be unique (depending on the mechanism).

## Revision History

### Changes in Boost 1.87.0

- Restored the ability to construct a `constexpr uuid` that was inadvertently lost in 1.86.

### Changes in Boost 1.86.0 (major update)

- C++03 is no longer supported, a C++11 compiler is required. This includes GCC 4.8 or later, MSVC 14.0 or later, and MinGW-w64.

- Removed direct dependencies on Core, Io, Move, NumericConversion, StaticAssert, TTI, Random, ContainerHash. The library now only has five Boost dependencies in total (as opposed to 39 in Boost 1.85.)

- Moved `std::hash` support from `uuid_hash.hpp` to `uuid.hpp`.

- Moved serialization support from `uuid_serialize.hpp` to `uuid.hpp`.

- Improved the quality and speed of `hash_value`.

- Added `operator<=>`.

- The generic (non-SIMD) implementations of `is_nil`, `operator==`, `operator<`, `swap`, and `operator<=>` now use `__uint128_t` operations when that type is available, and `uint64_t` operations otherwise.

- Added convenience header `<boost/uuid.hpp>`.

- Removed platform-specific entropy providers; the implementation now uses `std::random_device` as the source of entropy.

- `basic_random_generator` has been moved to its own header, `boost/uuid/basic_random_generator.hpp`.

- `basic_random_generator` has been changed to hold the underlying generator by value, to avoid dynamic allocation and restore copyability.

- `random_generator_pure` is now an alias for `basic_random_generator<std::random_device>` and its use is discouraged.

- `random_generator_mt19937` is now an alias for `basic_random_generator<std::mt19937>` and its use is discouraged.

- `random_generator` now uses a cryptographically strong pseudorandom number generator (ChaCha20/12), seeded with entropy from `std::random_device`. It’s the recommended way to generate version 4 UUIDs.

- Since `basic_name_generator` had only two valid instantiations, both of which are already provided (`name_generator_md5` and `name_generator_sha1`), it was made a private implementation detail and is no longer part of the public interface.

- While `name_generator` and `name_generator_latest` are still provided for compatibility, their use is no longer encouraged.

- The name generators now accept Unicode strings; these are converted to UTF-8 before hashing.

- The definitions of the well-known RFC 4122 namespaces have been moved to their own header, `boost/uuid/namespaces.hpp`.

- Added `time_generator_v1`, a generator that produces version 1 time-based UUIDs.

- Added `time_generator_v6`, a generator that produces version 6 time-based UUIDs.

- Added `time_generator_v7`, a generator that produces version 7 time-based UUIDs.

- Added `uuid_clock`, a `<chrono>`-compatible clock with an epoch and a resolution as specified in RFC 4122.

- Accessors for the timestamp, the time point, the clock sequence, and the node identifier have been added to `uuid`.

- Improved the `what()` strings of the `std::runtime_error` exceptions thrown by `string_generator`.

- Added overloads of `to_chars` taking `Ch* first, Ch* last` and `Ch(&)[N]`.

- The default constructor of `uuid` now produces a nil UUID instead of an uninitialized one.

- `u.data()`, where `u` is of type `uuid`, now returns a pointer to the first `uint8_t` of the representation (same as `u.begin()`.) For backward compatibility, `data` is a function object with `operator()`, rather than a member function, which allows most existing uses of `data` as a public member to remain valid, if no longer encouraged.

- `uuid` now has the same alignment as `std::uint64_t`. It was previously unaligned (had alignment of 1, same as `std::uint8_t`.) To restore the 1.85 behavior, define the macro `BOOST_UUID_DISABLE_ALIGNMENT`.

## Configuration

The library does not require building or any special configuration to be used. However, there are a few options that can be enabled by defining macros prior to including library headers.

### Instruction Set

Macro | Description
--- | ---
`BOOST_UUID_NO_SIMD` | If defined, disables any optimizations for SIMD-enabled processors. Generic versions of algorithms will be used instead. This may result in suboptimal performance. By default, optimized algorithms are used, when the library is able to detect the availability of SIMD extensions at compile time.
`BOOST_UUID_USE_SSE2` | If defined, enables optimizations for SSE2 extensions available in x86 processors.
`BOOST_UUID_USE_SSE3` | If defined, enables optimizations for SSE3 extensions available in x86 processors.
`BOOST_UUID_USE_SSE41` | If defined, enables optimizations for SSE4.1 extensions available in x86 processors.
`BOOST_UUID_USE_AVX` | If defined, enables optimizations for AVX extensions available in modern x86 processors.
`BOOST_UUID_USE_AVX10_1` | If defined, enables optimizations for AVX-512 and AVX10.1 extensions available in modern x86 processors. The library does not require 512-bit vectors and is compatible with CPUs implementing AVX-512F, CD, VL, BW and DQ instruction subsets (i.e. equivalent to Intel Skylake-X).

By default the library attempts to detect the availability of SIMD extensions in the target CPU at compile time and automatically defines the appropriate macros if succeeded. The `BOOST_UUID_USE_SSE*` and `BOOST_UUID_USE_AVX*` macros can be defined by users, if auto-detection fails and it is known that the target CPU will have the extension. Do not enable these extensions unless you’re certain that they will always be available on any machine that will run your program. The library performs no run time checks, so if an extension is missing, the program will likely crash. Note that enabling more advanced extensions implies that more basic ones are also available.

### Alignment

Macro | Description
--- | ---
`BOOST_UUID_DISABLE_ALIGNMENT` | If defined, leaves `uuid` unaligned (alignment of 1, same as `std::uint8_t`). This was the behavior before release 1.86.

By default, `uuid` has the same alignment as `std::uint64_t`. Define `BOOST_UUID_DISABLE_ALIGNMENT` to leave it unaligned.

## Examples

### Tagging

    // example of tagging an object with a uuid
    // see boost/libs/uuid/test/test_tagging.cpp

    #include <boost/uuid/uuid.hpp>
    #include <boost/uuid/uuid_generators.hpp>

    class object
    {
    public:
        object()
            : tag(boost::uuids::random_generator()())
            , state(0)
        {}

        explicit object(int state)
            : tag(boost::uuids::random_generator()())
            , state(state)
        {}

        object(object const& rhs)
            : tag(rhs.tag)
            , state(rhs.state)
        {}

        bool operator==(object const& rhs) const {
            return tag == rhs.tag;
        }

        object& operator=(object const& rhs) {
            tag = rhs.tag;
            state = rhs.state;
        }

        int get_state() const { return state; }
        void set_state(int new_state) { state = new_state; }

    private:
        boost::uuids::uuid tag;

        int state;
    };

    object o1(1);
    object o2 = o1;
    o2.set_state(2);
    assert(o1 == o2);

    object o3(3);
    assert(o1 != o3);
    assert(o2 != o3);

### Byte Extraction

It is sometimes useful to get at the 16 bytes of a `uuid` directly. Typical use is as follows:

    boost::uuids::uuid u;
    std::vector<std::uint8_t> v(u.size());
    std::copy(u.begin(), u.end(), v.begin());

Note: `boost::uuids::uuid::size()` always returns 16.

## Reference

### <boost/uuid.hpp>

This convenience header makes the entire library available.

#### Synopsis

    #include <boost/uuid/uuid.hpp>
    #include <boost/uuid/uuid_io.hpp>
    #include <boost/uuid/uuid_generators.hpp>

### <boost/uuid/uuid.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    class uuid
    {
    private:

        std::uint8_t data_[ 16 ] = {}; // exposition only

    public:

        // constructors

        uuid() = default;
        uuid( std::uint8_t const (&r)[ 16 ] );

        // iteration

        using value_type = std::uint8_t;

        using reference = std::uint8_t&;
        using const_reference = std::uint8_t const&;

        using iterator = std::uint8_t*;
        using const_iterator = std::uint8_t const*;

        using size_type = std::size_t;
        using difference_type = std::ptrdiff_t;

        iterator begin() noexcept;
        iterator end() noexcept;

        const_iterator begin() const noexcept;
        const_iterator end() const noexcept;

        // data

        std::uint8_t* data() noexcept;
        std::uint8_t const* data() const noexcept;

        // size

        constexpr size_type size() const noexcept;
        static constexpr size_type static_size() noexcept;

        // is_nil

        bool is_nil() const noexcept;

        // variant

        enum variant_type
        {
            variant_ncs, // NCS backward compatibility
            variant_rfc_4122, // defined in RFC 4122 document
            variant_microsoft, // Microsoft Corporation backward compatibility
            variant_future // future definition
        };

        variant_type variant() const noexcept;

        // version

        enum version_type
        {
            version_unknown = -1,
            version_time_based = 1,
            version_dce_security = 2,
            version_name_based_md5 = 3,
            version_random_number_based = 4,
            version_name_based_sha1 = 5,
            version_time_based_v6 = 6,
            version_time_based_v7 = 7,
            version_custom_v8 = 8
        };

        version_type version() const noexcept;

        // time-based fields

        using timestamp_type = std::uint64_t;
        using clock_seq_type = std::uint16_t;
        using node_type = std::array<std::uint8_t, 6>;

        timestamp_type timestamp_v1() const noexcept;
        uuid_clock::time_point time_point_v1() const noexcept;

        timestamp_type timestamp_v6() const noexcept;
        uuid_clock::time_point time_point_v6() const noexcept;

        timestamp_type timestamp_v7() const noexcept;

        std::chrono::time_point<std::chrono::system_clock, std::chrono::milliseconds>
          time_point_v7() const noexcept;

        clock_seq_type clock_seq() const noexcept;
        node_type node_identifier() const noexcept;

        // swap

        void swap( uuid& rhs ) noexcept;
    };

    // operators

    bool operator==( uuid const& lhs, uuid const& rhs ) noexcept;
    bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;

    bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;
    bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;
    bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;
    bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;

    std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;

    // free swap

    void swap( uuid& lhs, uuid& rhs ) noexcept;

    // hash_value

    std::size_t hash_value( uuid const& u ) noexcept;

    }} // namespace boost::uuids

    // Boost.Serialization support

    BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)

    // std::hash support

    template<> struct std::hash<boost::uuids::uuid>;

#### Constructors

    uuid() = default;

Effects:

  Zero-initializes `data_`.

Postconditions:

  `is_nil()`.

    uuid( std::uint8_t const (&r)[ 16 ] );

Effects:

  Initializes the elements of `data_` from the corresponding elements of `r`.

Example:

      uuid dns = {{ 0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};

#### Iteration

Both constant and mutable iterators are provided.

    iterator begin() noexcept;
    const_iterator begin() const noexcept;

Returns:

  `data()`.

    iterator end() noexcept;
    const_iterator end() const noexcept;

Returns:

  `data() + size()`.

Example:

      using namespace boost::uuids;

      uuid u;

      for( uuid::const_iterator it = u.begin(); it != u.end(); ++it )
      {
          uuid::value_type v = *it;
          // do something with the octet v
      }

      for( uuid::iterator it = u.begin(); it != u.end(); ++it )
      {
          *it = 0;
      }

#### Data

    std::uint8_t* data() noexcept;

    std::uint8_t const* data() const noexcept;

Returns:

  `data_`.

#### Size

The size of a `uuid` (in octets) is fixed at 16.

    constexpr size_type size() const noexcept;

    static constexpr size_type static_size() noexcept;

Returns:

  `16`.

Example:

      using namespace boost::uuids;

      uuid u;

      assert( u.size() == 16 );
      static_assert( uuid::static_size() == 16 );

#### is_nil

    bool is_nil() const noexcept;

Returns:

  `true` when the `uuid` is equal to the nil UUID, `{00000000-0000-0000-0000-000000000000}`, otherwise `false`.

#### Variant

Three bits of a `uuid` determine the variant.

    variant_type variant() const noexcept;

Returns:

  The UUID variant; usually `variant_rfc_4122` for non-nil UUIDs.

#### Version

Four bits of a `uuid` determine the version, that is the mechanism used to generate the `uuid`.

    version_type version() const noexcept;

Returns:

  The UUID version.

#### Time-based Fields

    timestamp_type timestamp_v1() const noexcept;

Returns:

  The UUIDv1 timestamp (number of 100ns intervals since 00:00:00.00, 15 October 1582). The value is only meaningful for version 1 UUIDs.

    uuid_clock::time_point time_point_v1() const noexcept;

Returns:

  The timestamp of a version 1 UUID, expressed as a `<chrono>` `time_point`.

    timestamp_type timestamp_v6() const noexcept;

Returns:

  The UUIDv6 timestamp (number of 100ns intervals since 00:00:00.00, 15 October 1582). The value is only meaningful for version 6 UUIDs.

    uuid_clock::time_point time_point_v6() const noexcept;

Returns:

  The timestamp of a version 6 UUID, expressed as a `<chrono>` `time_point`.

    timestamp_type timestamp_v7() const noexcept;

Returns:

  The UUIDv7 timestamp (number of milliseconds since the Unix epoch - midnight 1 Jan 1970 UTC). The value is only meaningful for version 7 UUIDs.

    std::chrono::time_point<std::chrono::system_clock, std::chrono::milliseconds>
      time_point_v7() const noexcept;

Returns:

  The timestamp of a version 7 UUID, expressed as a `<chrono>` `time_point`.

    clock_seq_type clock_seq() const noexcept;

Returns:

  The clock sequence of a time-based UUID. The value is only meaningful for time-based UUIDs (version 1 and version 6).

    node_type node_identifier() const noexcept;

Returns:

  The node identifier of a time-based UUID. The value is only meaningful for time-based UUIDs (version 1 and version 6).

#### Swap

    void swap( uuid& rhs ) noexcept;

Effects:

  Exchanges the values of `*this` and `rhs`.

#### Operators

    bool operator==( uuid const& lhs, uuid const& rhs ) noexcept;

Returns:

  As if `std::memcmp( lhs.data(), rhs.data(), 16 ) == 0`.

    bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;

Returns:

  `!(lhs == rhs)`.

    bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;

Returns:

  As if `std::memcmp( lhs.data(), rhs.data(), 16 ) < 0`.

    bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;

Returns:

  `rhs < lhs`.

    bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;

Returns:

  `!(rhs < lhs)`.

    bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;

Returns:

  `!(lhs < rhs)`.

    std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;

Returns:

  As if `std::memcmp( lhs.data(), rhs.data(), 16 ) <=> 0`.

#### Free Swap

    void swap( uuid& lhs, uuid& rhs ) noexcept;

Effects:

  `lhs.swap( rhs );`

#### hash_value

This function allows instances of `uuid` to be used with boost::hash.

    std::size_t hash_value( uuid const& u ) noexcept;

Returns:

  The hash value of the `uuid`.

Example:

      boost::unordered_flat_map<boost::uuids::uuid, int> hash_map;

#### Serialization

    BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)

`uuid` is serialized as a primitive type, that is, by its string representation.

#### std::hash

This specialization allows instances of `uuid` to be used with `std::hash`.

    template<> struct std::hash<boost::uuids::uuid>
    {
        std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
    }

    std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;

Returns:

  `boost::uuids::hash_value( v )`.

Example:

      std::unordered_map<boost::uuids::uuid, int> hash_map;

### <boost/uuid/uuid_io.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    // stream insertion

    template<class Ch, class Traits>
      std::basic_ostream<Ch, Traits>&
        operator<<( std::basic_ostream<Ch, Traits>& os, uuid const& u );

    // stream extraction

    template<class Ch, class Traits>
      std::basic_istream<Ch, Traits>&
        operator>>( std::basic_istream<Ch, Traits>& is, uuid& u );

    // to_chars

    template<class OutputIterator>
      OutputIterator to_chars( uuid const& u, OutputIterator out );

    template<class Ch>
      bool to_chars( uuid const& u, Ch* first, Ch* last ) noexcept;

    template<class Ch, std::size_t N>
      Ch* to_chars( uuid const& u, Ch (&buffer)[ N ] ) noexcept;

    // to_string

    std::string to_string( uuid const& u );
    std::wstring to_wstring( uuid const& u );

    }} // namespace boost::uuids

#### Stream Insertion

    template<class Ch, class Traits>
      std::basic_ostream<Ch, Traits>&
        operator<<( std::basic_ostream<Ch, Traits>& os, uuid const& u );

Requires:

  `Ch` must be either `char` or `wchar_t`.

Effects:

  Inserts the string representation of `u` into the output stream `os`.

  The string representation of a `uuid` is `hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh`, where `h` is a lowercase hexadecimal digit.

Note | This operator also enables the use of boost::lexical_cast to convert a `uuid` to a string.

Example:

      using namespace boost::uuids;

      uuid u1 = random_generator()();

      std::cout << u1 << std::endl;

      std::string s1 = boost::lexical_cast<std::string>( u1 );

      std::cout << s1 << std::endl;

#### Stream Extraction

    template<class Ch, class Traits>
      std::basic_istream<Ch, Traits>&
        operator>>( std::basic_istream<Ch, Traits>& is, uuid& u );

Requires:

  `Ch` must be either `char` or `wchar_t`.

Effects:

  Parses a `uuid` string representation from `is` and stores the result into `u`.

Note | This operator also enables the use of boost::lexical_cast to convert a string to a `uuid`.

Example:

      using namespace boost::uuids;

      uuid u1 = random_generator()();

      std::stringstream ss;
      ss << u1;

      uuid u2 = boost::lexical_cast<uuid>( ss.str() );

      assert( u1 == u2 );

      uuid u3;
      ss >> u3;

      assert( u1 == u3 );

#### to_chars

    template<class OutputIterator>
      OutputIterator to_chars( uuid const& u, OutputIterator out );

Effects:

  Outputs the string representation of `u` (exactly 36 characters of type `char`) to the output iterator `out`.

Example:

      using namespace boost::uuids;

      uuid u = random_generator()();

      std::vector<char> v;

      to_chars( u, std::back_inserter( v ) );

    template<class Ch>
      bool to_chars( uuid const& u, Ch* first, Ch* last ) noexcept;

Requires:

  `Ch` must be a character type (one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`.)

Effects:

  If `last - first >= 36`, writes the string representation of `u` (exactly 36 characters, not null terminated) into the buffer starting at `first` and returns `true`. Otherwise, returns `false`.

Example:

      using namespace boost::uuids;

      uuid u = random_generator()();

      char buf[ 36 ];

      bool ret = to_chars( u, std::begin( buf ), std::end( buf ) );
      assert( ret );

      std::cout << std::string( buf, 36 ) << std::endl;

    template<class Ch, std::size_t N>
      Ch* to_chars( uuid const& u, Ch (&buffer)[ N ] ) noexcept;

Requires:

  `Ch` must be a character type (one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`); `N` must be at least 37.

Effects:

  Writes the string representation of `u` (exactly 37 characters, including the null terminator) into `buffer`.

Returns:

  `buffer + 36`.

Example:

      using namespace boost::uuids;

      uuid u = random_generator()();

      char buf[ 37 ];

      to_chars( u, buf );

      std::cout << buf << std::endl;

Note | As a special exception, `N` is allowed to be 36. In this case, the function writes exactly 36 characters into `buffer` and does not write a null terminator. This use is only supported for backward compatibility and is deprecated. Use a buffer of 37 characters instead, to allow for the null terminator.

#### to_string

The functions `to_string` and `to_wstring` are provided as a convenience to convert a `uuid` to a string. They are likely to be more efficient than boost::lexical_cast.

    std::string to_string( uuid const& u );

    std::wstring to_wstring( uuid const& u );

Returns:

  A string containing the string representation of `u`.

Example:

      using namespace boost::uuids;

      uuid u = random_generator()();

      std::string s1 = to_string( u );

      std::wstring s2 = to_wstring( u );

### <boost/uuid/uuid_generators.hpp>

#### Synopsis

This convenience header includes all the UUID generators.

    #include <boost/uuid/nil_generator.hpp>
    #include <boost/uuid/string_generator.hpp>
    #include <boost/uuid/name_generator.hpp>
    #include <boost/uuid/random_generator.hpp>

### <boost/uuid/nil_generator.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    struct nil_generator
    {
        using result_type = uuid;
        uuid operator()() const noexcept;
    };

    uuid nil_uuid() noexcept;

    }} // namespace boost::uuids

#### nil_generator

The `nil_generator` class always generates a nil `uuid`.

    uuid operator()() const noexcept;

Returns:

  A nil UUID.

Example:

      using namespace boost::uuid;

      nil_generator gen;
      uuid u = gen();

      assert( u.is_nil() );

#### nil_uuid

    uuid nil_uuid() noexcept;

Returns:

  A nil UUID.

Example:

      using namespace boost::uuid;

      uuid u = nil_uuid();

      assert( u.is_nil() );

### <boost/uuid/string_generator.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    struct string_generator
    {
        using result_type = uuid;

        template<class Ch, class Traits, class Alloc>
          uuid operator()( std::basic_string<Ch, Traits, Alloc> const& s ) const;

        uuid operator()( char const* s ) const;
        uuid operator()( wchar_t const* s ) const;

        template<class CharIterator>
          uuid operator()( CharIterator begin, CharIterator end ) const;
    };

    }} // namespace boost::uuids

#### string_generator

The `string_generator` class generates a `uuid` from a string.

The standards-defined string format in RFC 4122 (p. 3) is supported, as well as a few variants.

Valid strings match the following PCRE regular expression:

    ^({)?([0-9a-fA-F]{8})(?-)?([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{12})(?(1)})$

Or more generally, the following formats are accepted as valid string formats, where h is hexadecimal, without case sensitivity, and without any leading or trailing whitespace:

    hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh
    {hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh}
    hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
    {hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh}

Invalid input will generate a `std::runtime_error` exception.

    template<class Ch, class Traits, class Alloc>
      uuid operator()( std::basic_string<Ch, Traits, Alloc> const& s ) const;

Requires:

  The character type `Ch` of `s` must be either `char` or `wchar_t`.

Effects:

  Parses the string `s` into a `uuid` and returns the result.

Example:

      using namespace boost::uuids;

      string_generator gen;

      uuid u1 = gen( std::string( "0123456789abcdef0123456789abcdef" ) );
      uuid u2 = gen( std::wstring( L"01234567-89AB-CDEF-0123-456789ABCDEF" ) );

    uuid operator()( char const* s ) const;
    uuid operator()( wchar_t const* s ) const;

Effects:

  Parses the string `s` into a `uuid` and returns the result.

Example:

      using namespace boost::uuids;

      string_generator gen;

      uuid u1 = gen( "{01234567-89ab-cdef-0123-456789abcdef}" );
      uuid u2 = gen( L"01234567-89ab-cdef-0123-456789abcdef" );

    template<class CharIterator>
      uuid operator()( CharIterator begin, CharIterator end ) const;

Requires:

  `CharIterator` must be an input iterator with a value type of either `char` or `wchar_t`.

Effects:

  Parses the character sequence `[begin, end)` into a `uuid` and returns the result.

Example:

      using namespace boost::uuids;

      string_generator gen;

      std::string s1( "0123456789abcdef0123456789abcdef" );
      uuid u1 = gen( s1.begin(), s1.end() );

      std::wstring s2( L"01234567-89AB-CDEF-0123-456789ABCDEF" );
      uuid u2 = gen( s2.begin(), s2.end() );

### <boost/uuid/namespaces.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {
    namespace ns {

    uuid dns() noexcept;
    uuid url() noexcept;
    uuid oid() noexcept;
    uuid x500dn() noexcept;

    }}} // namespace boost::uuids::ns

#### Namespaces

This header provides definitions of the four namespaces defined in RFC 4122, Appendix C.

    uuid dns() noexcept;

Returns:

  The DNS namespace UUID from RFC 4122, `{6ba7b810-9dad-11d1-80b4-00c04fd430c8}`.

    uuid url() noexcept;

Returns:

  The URL namespace UUID from RFC 4122, `{6ba7b811-9dad-11d1-80b4-00c04fd430c8}`.

    uuid oid() noexcept;

Returns:

  The OID namespace UUID from RFC 4122, `{6ba7b812-9dad-11d1-80b4-00c04fd430c8}`.

    uuid x500dn() noexcept;

Returns:

  The X.500 DN namespace UUID from RFC 4122, `{6ba7b814-9dad-11d1-80b4-00c04fd430c8}`.

### <boost/uuid/​name_generator_sha1.hpp>

#### Synopsis

    #include <boost/uuid/namespaces.hpp>

    namespace boost {
    namespace uuids {

    class name_generator_sha1
    {
    public:

        using result_type = uuid;

        explicit name_generator_sha1( uuid const& namespace_uuid ) noexcept;

        template<class Ch> uuid operator()( Ch const* name ) const noexcept;

        template<class Ch, class Traits, class Alloc>
          uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const noexcept;

        uuid operator()( void const* buffer, std::size_t byte_count ) const noexcept;
    };

    }} // namespace boost::uuids

#### name_generator_sha1

The class `name_generator_sha1` generates name-based version 5 UUIDs, using SHA1 as the hashing algorithm.

    explicit name_generator_sha1( uuid const& namespace_uuid );

Effects:

  Constructs a `name_generator_sha1` that uses `namespace_uuid` as the namespace.

    template<class Ch> uuid operator()( Ch const* name ) const noexcept;

Requires:

  `Ch` must be one of `char`, `wchar_t`, `char8_t`, `char16_t`, or `char32_t`.

Returns:

  A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the characters of the string `name`, converted to octets.

Remarks:

  The characters of `name` are converted to a sequence of octets in the following manner:

  - If `Ch` is `char` or `char8_t`, the characters are processed as octets directly;

  - If `Ch` is `wchar_t`, the characters are converted to `uint32_t` and then serialized to four octets each using little-endian representation;

  - Otherwise, the character sequence is converted to UTF-8 and the result is processed as octets.

Example:

      using namespace boost::uuids;

      name_generator_sha1 gen( ns::dns() );

      uuid u1 = gen( "boost.org" );

      std::cout << "\"boost.org\" UUID in DNS namespace, SHA1 version: " << u1 << std::endl;

      // Output:
      //   "boost.org" UUID in DNS namespace, SHA1 version: 0043f363-bbb4-5369-840a-322df6ec1926

      uuid u2 = gen( L"boost.org" );

      std::cout << "L\"boost.org\" UUID in DNS namespace, SHA1 version: " << u2 << std::endl;

      // Output:
      //   L"boost.org" UUID in DNS namespace, SHA1 version: c31c5016-3493-5dc2-8484-5813d495cc18

      uuid u3 = gen( u"boost.org" );

      std::cout << "u\"boost.org\" UUID in DNS namespace, SHA1 version: " << u3 << std::endl;

      // Output:
      //   u"boost.org" UUID in DNS namespace, SHA1 version: 0043f363-bbb4-5369-840a-322df6ec1926

    template<class Ch, class Traits, class Alloc>
      uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const;

Requires:

  `Ch` must be one of `char`, `wchar_t`, `char8_t`, `char16_t`, or `char32_t`.

Returns:

  As if `operator()( name.c_str() )`.

    uuid operator()( void const* buffer, std::size_t byte_count ) const;

Returns:

  A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the `byte_count` octets starting from `buffer`.

### <boost/uuid/​name_generator_md5.hpp>

#### Synopsis

    #include <boost/uuid/namespaces.hpp>

    namespace boost {
    namespace uuids {

    class name_generator_md5
    {
    public:

        using result_type = uuid;

        explicit name_generator_md5( uuid const& namespace_uuid ) noexcept;

        template<class Ch> uuid operator()( Ch const* name ) const noexcept;

        template<class Ch, class Traits, class Alloc>
          uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const noexcept;

        uuid operator()( void const* buffer, std::size_t byte_count ) const noexcept;
    };

    }} // namespace boost::uuids

#### name_generator_md5

The class `name_generator_md5` generates name-based version 3 UUIDs, using MD5 as the hashing algorithm.

Its interface and its operation are the same as those of `name_generator_sha1`, with the only difference being that it uses MD5 instead of SHA1.

There is no reason to use `name_generator_md5` except for compatibility. `name_generator_sha1` should be preferred in almost all cases.

Example:

      using namespace boost::uuids;

      name_generator_md5 gen( ns::dns() );

      uuid u1 = gen( "boost.org" );

      std::cout << "\"boost.org\" UUID in DNS namespace, MD5 version: " << u1 << std::endl;

      // Output:
      //   "boost.org" UUID in DNS namespace, MD5 version: 888eca9c-e655-31a2-a46b-a2a821f6b150

      uuid u2 = gen( L"boost.org" );

      std::cout << "L\"boost.org\" UUID in DNS namespace, MD5 version: " << u2 << std::endl;

      // Output:
      //   L"boost.org" UUID in DNS namespace, MD5 version: 48149232-8cda-361b-b355-0bdb71d2cab3

      uuid u3 = gen( u"boost.org" );

      std::cout << "u\"boost.org\" UUID in DNS namespace, MD5 version: " << u3 << std::endl;

      // Output:
      //   u"boost.org" UUID in DNS namespace, MD5 version: 888eca9c-e655-31a2-a46b-a2a821f6b150

### <boost/uuid/name_generator.hpp>

#### Synopsis

    #include <boost/uuid/name_generator_sha1.hpp>
    #include <boost/uuid/name_generator_md5.hpp>

    namespace boost {
    namespace uuids {

    // only provided for backward compatibility

    using name_generator = name_generator_sha1;
    using name_generator_latest = name_generator_sha1;

    }} // namespace boost::uuids

This header makes `name_generator_sha1` and `name_generator_md5` available and declares the compatibility aliases `name_generator` and `name_generator_latest`.

### <boost/uuid/​basic_random_generator.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    template<class UniformRandomNumberGenerator>
    class basic_random_generator
    {
    private:

        // exposition only
        UniformRandomNumberGenerator* p_;
        UniformRandomNumberGenerator g_;

    public:

        using result_type = uuid;

        basic_random_generator();

        explicit basic_random_generator( UniformRandomNumberGenerator& gen );
        explicit basic_random_generator( UniformRandomNumberGenerator* pGen );

        result_type operator()();
    };

    }} // namespace boost::uuids

#### basic_random_generator

The class template `basic_random_generator` generates a version 4 random number-based UUID from a random number generator (one that conforms to the standard concept UniformRandomBitGenerator or to the Boost.Random concept UniformRandomNumberGenerator).

The default constructor will seed the random number generator with entropy obtained from `std::random_device`.

Additional constructors allow you to provide your own `UniformRandomNumberGenerator` and you are responsible for properly seeding it if necessary.

    basic_random_generator();

Effects:

  Value-initializes `g_` and initializes `p_` to `nullptr`. If `g_.seed()` is a valid expression, calls `g_.seed( seed_seq );` to seed `g_`, where `seed_seq` is an object providing a `generate( first, last )` member function that fills the range `[first, last)` using entropy obtained from `std::random_device`.

Note | Random number generators conforming to the standard concept RandomNumberEngine or the Boost.Random concept PseudoRandomNumberGenerator provide such `seed` member functions.

    explicit basic_random_generator( UniformRandomNumberGenerator& gen );

Effects:

  Value-initializes `g_` and initializes `p_` to `&gen`.

    explicit basic_random_generator( UniformRandomNumberGenerator* pGen );

Effects:

  Value-initializes `g_` and initializes `p_` to `pGen`.

    result_type operator()();

Effects:

  Generates and returns a version 4 UUID using random numbers obtained from `*p_`, if `p_ != nullptr`, or from `g_`, otherwise.

Example:

      using namespace boost::uuids;

      basic_random_generator<boost::mt19937> bulkgen;

      for( int i = 0; i < 1000; ++i )
      {
          uuid u = bulkgen();
          // do something with u
      }

### <boost/uuid/​random_generator.hpp>

#### Synopsis

    #include <boost/uuid/basic_random_generator.hpp>

    namespace boost {
    namespace uuids {

    // recommended for all uses

    class random_generator
    {
    private:

        // exposition only
        unspecified-csprng-type g_;

    public:

        using result_type = uuid;

        random_generator();

        result_type operator()();
    };

    // only provided for backward compatibility

    using random_generator_mt19937 = basic_random_generator<std::mt19937>;
    using random_generator_pure = basic_random_generator<std::random_device>;

    }} // namespace boost::uuids

#### random_generator

The class `random_generator` generates UUIDs using a cryptographically strong random number generator, seeded with entropy from `std::random_device`. It’s the recommended way to generate version 4 random-based UUIDs.

    random_generator();

Effects:

  Initializes `g_`, an instance of a cryptographically strong random number generator, using entropy obtained from `std::random_device`.

    result_type operator()();

Effects:

  Generates and returns a version 4 UUID using random numbers obtained from `g_`.

Example:

      using namespace boost::uuids;

      random_generator gen;

      uuid u1 = gen();
      std::cout << u1 << std::endl;

      uuid u2 = gen();
      std::cout << u2 << std::endl;

      assert( u1 != u2 );

#### random_generator_mt19937

`random_generator_mt19937` is an alias for `basic_random_generator<std::mt19937>` and is only provided for backward compatibility.

#### random_generator_pure

`random_generator_pure` is an alias for `basic_random_generator<std::random_device>` and is only provided for backward compatibility.

### <boost/uuid/uuid_clock.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    class uuid_clock
    {
    public:

        using rep = std::int64_t;
        using period = std::ratio<1, 10000000>; // 100ns
        using duration = std::chrono::duration<rep, period>;
        using time_point = std::chrono::time_point<uuid_clock, duration>;

        static constexpr bool is_steady = false;

        static time_point now() noexcept;

        template<class Duration>
          static time_point from_sys(
            std::chrono::time_point<std::chrono::system_clock, Duration> const& tp ) noexcept;

        static std::chrono::time_point<std::chrono::system_clock, duration>
          to_sys( time_point const& tp ) noexcept;

        static time_point from_timestamp( std::uint64_t timestamp ) noexcept;
        static std::uint64_t to_timestamp( time_point const& tp ) noexcept;
    };

    }} // namespace boost::uuids

The class `uuid_clock` is a `<chrono>`-compatible clock with an epoch of 00:00:00.00, 15 October 1582, and a resolution of 100 ns. These values are specified in RFC 4122 Section 4.1.4.

#### now

    static time_point now() noexcept;

Returns:

  The current system time (`std::chrono::system_clock::now()`, converted to `uuid_clock::time_point`.)

#### from_sys

    template<class Duration>
      static time_point from_sys(
        std::chrono::time_point<std::chrono::system_clock, Duration> const& tp ) noexcept;

Returns:

  The `uuid_clock::time_point` corresponding to `tp`.

#### to_sys

    static std::chrono::time_point<std::chrono::system_clock, duration>
      to_sys( time_point const& tp ) noexcept;

Returns:

  The `std::chrono::system_clock::time_point` corresponding to `tp`.

Example:

      #include <boost/uuid/time_generator_v1.hpp>
      #include <boost/uuid/uuid.hpp>
      #include <boost/uuid/uuid_clock.hpp>
      #include <chrono>

      using namespace boost::uuids;

      int main()
      {
          time_generator_v1 gen;

          uuid u = gen(); // generates a version 1 time-based UUID

          // note that stream output of std::chrono::system_clock::time_point requires C++20

          std::cout << uuid_clock::to_sys( u.time_point_v1() ) << std::endl;
      }

#### from_timestamp

    static time_point from_timestamp( std::uint64_t timestamp ) noexcept;

Returns:

  The `uuid_clock::time_point` corresponding to `timestamp` 100 nanosecond intervals since the `uuid_clock` epoch.

#### to_timestamp

    static std::uint64_t to_timestamp( time_point const& tp ) noexcept;

Returns:

  The number of 100 nanosecond intervals since the `uuid_clock` epoch corresponding to `tp`.

Example:

      using namespace boost::uuids;

      uuid u = time_generator_v1()();

      assert( u.timestamp_v1() == uuid_clock::to_timestamp( u.time_point_v1() ) );

### <boost/uuid/​time_generator_v1.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    class time_generator_v1
    {
    public:

        struct state_type
        {
            std::uint64_t timestamp;
            std::uint16_t clock_seq;
        };

    private: // exposition only

        uuid::node_type node_ = {};

        std::atomic<state_type>* ps_ = nullptr;
        state_type state_ = {};

    public:

        using result_type = uuid;

        time_generator_v1();
        time_generator_v1( uuid::node_type const& node, state_type const& state ) noexcept;
        time_generator_v1( uuid::node_type const& node, std::atomic<state_type>& state ) noexcept;

        result_type operator()() noexcept;
    };

    }} // namespace boost::uuids

The class `time_generator_v1` generates time-based version 1 UUIDs. It supports three modes of operation.

The default and recommended one is by using its default constructor. This instructs the generator to use a pseudorandom node identifier and initial clock sequence.

If more control over the node identifier (or the clock sequence) is desired, for example, if the generated UUIDs must use a specific node identifier that persists for the lifetime of the program or even across different program runs, a constructor that takes a node identifier and a `state_type` is provided. (The `timestamp` field of the provided `state_type` should generally be zero.)

Finally, if the program has several `time_generator_v1` instances (for example, one per thread) that need to use the same node identifier, the third constructor takes a node identifier and a reference to `std::atomic<state_type>`. The atomic state is used by the generators to ensure that no duplicate UUIDs are produced.

#### Constructors

    time_generator_v1();

Effects:

  Using entropy from `std::random_device`, generates a pseudorandom 48 bit node identifier in `node_` and a pseudorandom 14 bit clock sequence in `state_.clock_seq`. Initalizes `state_.timestamp` to zero.

Remarks:

  The multicast bit of `node_` is set to denote a local node identifier, as recommended in RFC 4122 Section 4.5.

    time_generator_v1( uuid::node_type const& node, state_type const& state ) noexcept;

Effects:

  Initializes `node_` to `node` and `state_` to `state`.

    time_generator_v1( uuid::node_type const& node, std::atomic<state_type>& state ) noexcept;

Effects:

  Initializes `node_` to `node` and `ps_` to `&state`.

#### operator()

    result_type operator()() noexcept;

Effects:

  Using the state in `state_`, if `ps_` is `nullptr`, or the state in `*ps_`, if `ps_` is not `nullptr`, atomically computes and sets a new state by retrieving the system time as if by `uuid_clock::now()`, converting it to a timestamp as if by `uuid_clock::to_timestamp`, storing the result in `state.timestamp`, and incrementing `state.clock_seq` modulo 0x4000 if the new timestamp is lower than or equal to the previous timestamp.

  Creates a version 1 UUID using the node identifier from `node_` and the new timestamp and clock sequence and returns it.

### <boost/uuid/​time_generator_v6.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    class time_generator_v6
    {
    public:

        struct state_type
        {
            std::uint64_t timestamp;
            std::uint16_t clock_seq;
        };

    private: // exposition only

        uuid::node_type node_ = {};

        std::atomic<state_type>* ps_ = nullptr;
        state_type state_ = {};

    public:

        using result_type = uuid;

        time_generator_v6();
        time_generator_v6( uuid::node_type const& node, state_type const& state ) noexcept;
        time_generator_v6( uuid::node_type const& node, std::atomic<state_type>& state ) noexcept;

        result_type operator()() noexcept;
    };

    }} // namespace boost::uuids

The class `time_generator_v6` generates time-based version 6 UUIDs, as described in RFC 9562 section 5.6.

It operates in the exact same manner as `time_generator_v1`, with the only difference being that it produces version 6 UUIDs rather than version 1 ones.

### <boost/uuid/​time_generator_v7.hpp>

#### Synopsis

    namespace boost {
    namespace uuids {

    class time_generator_v7
    {
    private:

        // exposition only
        unspecified-csprng-type rng_;

    public:

        using result_type = uuid;

        time_generator_v7();

        time_generator_v7( time_generator_v7 const& rhs );
        time_generator_v7( time_generator_v7&& rhs ) noexcept;

        time_generator_v7& operator=( time_generator_v7 const& rhs ) noexcept;
        time_generator_v7& operator=( time_generator_v7&& rhs ) noexcept;

        result_type operator()() noexcept;
    };

    }} // namespace boost::uuids

The class `time_generator_v7` generates time-based version 7 UUIDs, as described in RFC 9562 section 5.7.

#### Constructors

    time_generator_v7();

Effects:

  Initializes the internal cryptographically strong pseudorandom number generator (CSPRNG) `rng_` using entropy from `std::random_device`.

    time_generator_v7( time_generator_v7 const& rhs );

Effects:

  Copies the state of `rhs` into `*this`, then reseeds `this->rng_` using entropy from `std::random_device`.

Remarks:

  Reseeding ensures that the two generators don’t produce the same random number sequence after the copy.

    time_generator_v7( time_generator_v7&& rhs ) noexcept;

Effects:

  Copies the state of `rhs` into `*this`, then perturbs the state of `rhs.rng_` such that it no longer produces the same random number sequence.

#### Assignment

    time_generator_v7& operator=( time_generator_v7 const& rhs ) noexcept;

Effects:

  Copies the state of `rhs` into `*this`, except for `this->rng_`, which is left unmodified.

Returns:

  `*this`.

Remarks:

  Not modifying `this->rng_` ensures that the two generators continue to produce different random numbers.

    time_generator_v7& operator=( time_generator_v7&& rhs ) noexcept;

Effects:

  Copies the state of `rhs` into `*this`, then perturbs the state of `rhs.rng_` such that it no longer produces the same random number sequence.

Returns:

  `*this`.

#### operator()

    result_type operator()() noexcept;

Effects:

  1. Obtains a new timestamp as if by getting the system time from `std::chrono::system_clock::now()` and converting it to a number of microseconds from the Unix epoch.

  2. Creates a new version 7 UUID and initializes its `unix_ts_ms` field with the number of milliseconds in the timestamp.

  3. Initializes the `rand_a` field with the residual number of microseconds from the timestamp.

  4. Initializes the 6 bits of the `rand_b` field following the variant to a conflict resolution counter, such that if more than one UUID is generated using the same timestamp, monotonicity is still ensured.

  5. Initializes the rest of the `rand_b` field to random values obtained from the internal CSPRNG `rng_`.

  6. Returns the UUID.

Remarks:

  `operator()` generates a monotonically increasing sequence of UUIDs, if the following requirements are met:

  - The system clock never goes backwards;

  - The system clock has at least millisecond resolution;

  - No more than 64 UUIDs are generated per microsecond (no more than one every 16 nanoseconds.)

### <boost/uuid/time_generator.hpp>

#### Synopsis

    #include <boost/uuid/time_generator_v1.hpp>
    #include <boost/uuid/time_generator_v6.hpp>
    #include <boost/uuid/time_generator_v7.hpp>

This convenience header makes the three time-based generators `time_generator_v1`, `time_generator_v6`, and `time_generator_v7`, available.

### Design Notes

The document http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf was used to design and implement the `uuid` struct.

All functions are re-entrant. Classes are as thread-safe as an int. That is an instance cannot be shared between threads without proper synchronization.

### Acknowledgements

A number of people on the boost.org mailing list provided useful comments and greatly helped to shape the library.

The documentation was converted to Asciidoc format by Christian Mazakas.

## Copyright and License

Copyright 2006 Andy Tompkins

Copyright 2017 James E. King III

Copyright 2024 Christian Mazakas

Copyright 2024 Peter Dimov

Distributed under the Boost Software License, Version 1.0.

## Old Revision History

This section contains the old revision history that used to be maintained as comments in the library header files.

### boost/uuid/uuid.hpp

    // Revision History
    //  06 Feb 2006 - Initial Revision
    //  09 Nov 2006 - fixed variant and version bits for v4 guids
    //  13 Nov 2006 - added serialization
    //  17 Nov 2006 - added name-based guid creation
    //  20 Nov 2006 - add fixes for gcc (from Tim Blechmann)
    //  07 Mar 2007 - converted to header only
    //  10 May 2007 - removed need for Boost.Thread
    //              - added better seed - thanks Peter Dimov
    //              - removed null()
    //              - replaced byte_count() and output_bytes() with size() and begin() and end()
    //  11 May 2007 - fixed guid(ByteInputIterator first, ByteInputIterator last)
    //              - optimized operator>>
    //  14 May 2007 - converted from guid to uuid
    //  29 May 2007 - uses new implementation of sha1
    //  01 Jun 2007 - removed using namespace directives
    //  09 Nov 2007 - moved implementation to uuid.ipp file
    //  12 Nov 2007 - moved serialize code to uuid_serialize.hpp file
    //  25 Feb 2008 - moved to namespace boost::uuids
    //  19 Mar 2009 - changed to a POD, reorganized files
    //  28 Nov 2009 - disabled deprecated warnings for MSVC
    //  30 Nov 2009 - used BOOST_STATIC_CONSTANT
    //  02 Dec 2009 - removed BOOST_STATIC_CONSTANT - not all compilers like it
    //  29 Apr 2013 - added support for noexcept and constexpr, added optimizations for SSE/AVX

### boost/uuid/uuid_io.hpp

    // Revision History
    //  20 Mar 2009 - Initial Revision
    //  28 Nov 2009 - disabled deprecated warnings for MSVC

### boost/uuid/detail/sha1.hpp

    // Revision History
    //  29 May 2007 - Initial Revision
    //  25 Feb 2008 - moved to namespace boost::uuids::detail
    //  10 Jan 2012 - can now handle the full size of messages (2^64 - 1 bits)