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.91.0

  • Added from_chars to boost/uuid/uuid_io.hpp.

  • Added a noexcept operator() overload to string_generator.

  • string_generator now supports the Unicode character types in addition to char and wchar_t.

  • Most uuid accessors, operations, and to_chars are now constexpr when possible (on C++14 and higher and on recent compilers).

  • Added SIMD implementation of to_chars, which can offer up to 5.5x performance improvement in UUID formatting. (Andrey Semashev)

  • Added SIMD implementation of from_chars, which can offer up to 13x performance improvement in UUID parsing. (Andrey Semashev)

  • Added uuid_from_string to boost/uuid/uuid_io.hpp.

  • Added a dedicated invalid_uuid exception class, derived from std::runtime_error for backward compatibility.

Changes in Boost 1.90.0

  • string_generator is now constexpr on C++14 and higher.

  • Added header boost/uuid/constants.hpp.

  • Renamed boost/uuid/uuid_generators.hpp to boost/uuid/generators.hpp. The old name is retained for compatibility.

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_SSSE3

If defined, enables optimizations for SSSE3 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 x86 processors.

BOOST_UUID_USE_AVX2

If defined, enables optimizations for AVX2 extensions available in x86 processors.

BOOST_UUID_USE_AVX512_V1

If defined, enables optimizations for AVX-512 F, VL, CD, BW and DQ extensions available in x86 processors (e.g. in Intel Skylake-X).

BOOST_UUID_USE_AVX10_1

If defined, enables optimizations for AVX-512 and AVX10.1 extensions available in x86 processors. When defined by the user, this macro indicates support for the full set of instructions defined in AVX10.1. When auto-detected by the library, this macro may be defined even when not all AVX10.1 subsets are enabled, but rather when the detected subset is sufficient for the library.

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/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/generators.hpp>
#include <boost/uuid/constants.hpp>

<boost/uuid/uuid.hpp>

Synopsis

namespace boost {
namespace uuids {

class uuid
{
private:

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

public:

    // constructors

    constexpr uuid() = default;
    constexpr 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;

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

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

    // data

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

    // size

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

    // is_nil

    constexpr 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
    };

    constexpr 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
    };

    constexpr 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>;

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

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

    constexpr timestamp_type timestamp_v7() const noexcept;

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

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

    // swap

    constexpr void swap( uuid& rhs ) noexcept;
};

// operators

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

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

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

// free swap

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

// hash_value

constexpr 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

constexpr uuid() = default;
Effects:

Zero-initializes data_.

Postconditions:

is_nil().

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

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

Note
 This constructor is only constexpr under C++14 or later.
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.

constexpr iterator begin() noexcept;
constexpr const_iterator begin() const noexcept;
Returns:

data().

Note
 The non-const overload is only constexpr under C++14 or later. 
constexpr iterator end() noexcept;
constexpr const_iterator end() const noexcept;
Returns:

data() + size().

Note
 The non-const overload is only constexpr under C++14 or later.
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

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

data_.

Note
 The non-const overload is only constexpr under C++14 or later.

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

constexpr bool is_nil() const noexcept;
Returns:

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

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.

Variant

Three bits of a uuid determine the variant.

constexpr variant_type variant() const noexcept;
Returns:

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

Note
 This function is only constexpr under C++14 or later.

Version

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

constexpr version_type version() const noexcept;
Returns:

The UUID version.

Note
 This function is only constexpr under C++14 or later.

Time-based Fields

constexpr 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.

Note
 This function is only constexpr under C++14 or later. 
uuid_clock::time_point time_point_v1() const noexcept;
Returns:

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

constexpr 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.

Note
 This function is only constexpr under C++14 or later. 
uuid_clock::time_point time_point_v6() const noexcept;
Returns:

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

constexpr 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.

Note
 This function is only constexpr under C++14 or later. 
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.

constexpr 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).

Note
 This function is only constexpr under C++14 or later. 
constexpr 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).

Note
 This function is only constexpr under C++14 or later.

Swap

constexpr void swap( uuid& rhs ) noexcept;
Effects:

Exchanges the values of *this and rhs.

Note
 This function is only constexpr under C++14 or later.

Operators

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

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

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later. 
constexpr bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;
Returns:

!(lhs == rhs).

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later. 
constexpr bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;
Returns:

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

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later. 
constexpr bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;
Returns:

rhs < lhs.

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later. 
constexpr bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;
Returns:

!(rhs < lhs).

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later. 
constexpr bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;
Returns:

!(lhs < rhs).

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later. 
constexpr std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;
Returns:

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

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.

Free Swap

constexpr void swap( uuid& lhs, uuid& rhs ) noexcept;
Effects:

lhs.swap( rhs );

Note
 This function is only constexpr under C++14 or later.

hash_value

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

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

The hash value of the uuid.

Note
 This function is only constexpr under C++14 or later.
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>
{
    constexpr std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
}
constexpr std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
Returns:

boost::uuids::hash_value( v ).

Note
 This function is only constexpr under C++14 or later.
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>
  constexpr OutputIterator to_chars( uuid const& u, OutputIterator out );

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

template<class Ch, std::size_t N>
  constexpr 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 );

// from_chars

enum class from_chars_error
{
    none = 0,

    unexpected_end_of_input,
    hex_digit_expected,
    dash_expected,
    closing_brace_expected,
    unexpected_extra_input
};

template<class Ch> struct from_chars_result
{
    Ch const* ptr;
    from_chars_error ec;

    constexpr explicit operator bool() const noexcept;
};

template<class Ch>
  constexpr from_chars_result<Ch>
    from_chars( Ch const* first, Ch const* last, uuid& u ) noexcept;

// uuid_from_string

template<class Ch> constexpr uuid uuid_from_string( Ch const* str );
template<class Str> constexpr uuid uuid_from_string( Str const& str );

}} // 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 a character type (one of char, wchar_t, char8_t, char16_t, char32_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 a character type (one of char, wchar_t, char8_t, char16_t, char32_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>
  constexpr 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.

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
Example: 
using namespace boost::uuids;

uuid u = random_generator()();

std::vector<char> v;

to_chars( u, std::back_inserter( v ) );
template<class Ch>
  constexpr 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.

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
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>
  constexpr 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.

Note
 This function is only constexpr under C++14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
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 );

from_chars_result

The from_chars_result structure contains the result of a from_chars call, where the ptr member points to the first character that was not consumed during parsing and ec is from_chars_error::none, if parsing succeeded, otherwise the error code returned by the parser.

constexpr explicit operator bool() const noexcept;
Returns:

this->ec == from_chars_error::none.

from_chars

template<class Ch>
  constexpr from_chars_result<Ch>
    from_chars( Ch const* first, Ch const* last, uuid& u ) noexcept;
Requires:

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

Effects:

Parses a uuid string representation from the characters in the range [first, last) and stores the result in u. On error, the returned from_chars_result struct contains the error code in ec and ptr points to the character at which parsing failed. On success, ec contains from_chars_error::none and ptr points to the character immediately after the last uuid character.

Note
 The values from_chars_error::closing_brace_expected and from_chars_error::unexpected_extra_input are never returned by from_chars. They can be returned from the nonthrowing string_generator::operator() overload.

uuid_from_string

template<class Ch> constexpr uuid uuid_from_string( Ch const* str );
Requires:

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

Effects:

Parses a uuid string representation from the characters in the range [str, str + std::char_traits<Ch>::length(str)) and stores the result in u. On error, throws invalid_uuid.

Note
 Unlike from_chars, this function does not allow extra input; if after a complete UUID is parsed, unconsumed characters remain, an exception is thrown. 
template<class Str> constexpr uuid uuid_from_string( Str const& str );
Requires:

Str must be a string-like type; that is, one with a nested value_type type (Ch) and with a nested traits_type type. str.data() must return Ch const*. str.data() + str.size() must be of type Ch const*. Ch must be a character type (one of char, wchar_t, char8_t, char16_t, char32_t).

Effects:

Parses a uuid string representation from the characters in the range [str.data(), str.data() + str.size()) and stores the result in u. On error, throws invalid_uuid.

Note
 Unlike from_chars, this function does not allow extra input; if after a complete UUID is parsed, unconsumed characters remain, an exception is thrown.

<boost/uuid/invalid_uuid.hpp>

Synopsis

namespace boost {
namespace uuids {

class invalid_uuid: public std::runtime_error
{
public:

    invalid_uuid( std::ptrdiff_t pos, from_chars_error err );

    std::ptrdiff_t position() const noexcept;
    from_chars_error error() const noexcept;
};

}} // namespace boost::uuids

invalid_uuid

Functions that parse a string UUID representation throw an exception of type invalid_uuid to indicate failure.

invalid_uuid( std::ptrdiff_t pos, from_chars_error err );
Effects:

Constructs an invalid_uuid object, initializing its internal members to pos and err and the runtime_error base class with an appropriate error message.

Postconditions:

this->position() == pos && this->error() == err.

std::ptrdiff_t position() const noexcept;
Returns:

The zero-based position in the input string at which parsing failed.

from_chars_error error() const noexcept;
Returns:

The error code describing the reason parsing failed.

<boost/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 Str>
      constexpr uuid operator()( Str const& s ) const;

    template<class Ch>
      constexpr uuid operator()( Ch const* s ) const;

    template<class CharIterator>
      constexpr uuid operator()( CharIterator first, CharIterator last ) const;

    template<class CharIterator>
      constexpr uuid operator()( CharIterator first, CharIterator last,
        std::ptrdiff_t& pos, from_chars_error& err ) const noexcept;
};

}} // 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 throw an invalid_uuid exception.

template<class Str>
  constexpr uuid operator()( Str const& s ) const;
Requires:

Str must be a string-like type; that is, one with a nested value_type type (Ch) and with a nested traits_type type. str.data() must return Ch const*. str.data() + str.size() must be of type Ch const*. Ch must be a character type (one of char, wchar_t, char8_t, char16_t, char32_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" ) );
template<class Ch>
  constexpr uuid operator()( Ch const* s ) const;
Requires:

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

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>
  constexpr uuid operator()( CharIterator first, CharIterator last ) const;
Requires:

CharIterator must be an input iterator with a character value type (one of char, wchar_t, char8_t, char16_t, char32_t).

Effects:

Parses the character sequence [first, last) 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() );
template<class CharIterator>
  constexpr uuid operator()( CharIterator first, CharIterator last,
    std::ptrdiff_t& pos, from_chars_error& err ) const noexcept;
Requires:

CharIterator must be an input iterator with a character value type (one of char, wchar_t, char8_t, char16_t, char32_t).

Effects:

Parses the character sequence [first, last) into a uuid and returns the result. On error, pos contains the position at which parsing failed, and err contains the error. On success, err contains from_chars_error::none.

Note
 Unlike from_chars, this function does not allow extra input; if after a complete UUID is parsed, unconsumed characters remain, err is set to from_chars_error::unexpected_extra_input.

<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. Initializes 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.

<boost/uuid/constants.hpp>

Synopsis

#include <boost/uuid/namespaces.hpp>

namespace boost {
namespace uuids {

uuid nil_uuid() noexcept;

}} // namespace boost::uuids

Constants

This header provides definitions of some well known UUID constants.

uuid nil_uuid() noexcept;
Returns:

The nil UUID, {00000000-0000-0000-0000-000000000000}.

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 2006 Andy Tompkins

Copyright 2017 James E. King III

Copyright 2024 Christian Mazakas

Copyright 2024-2026 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)