Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit c8cc5bbc3b.

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

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.

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

POD Efficiencies

This library implements a UUID as a POD allowing a UUID to be used in the most efficient ways, including using memcpy, and aggregate initializers. A drawback is that a POD can not have any constructors, and thus declaring a UUID will not initialize it to a value generated by one of the defined mechanisms. But a class based on a UUID can be defined that does initialize itself to a value generated by one of the defined mechanisms.

// example using memcpy and aggregate initializers
// example of a class uuid see boost/libs/uuid/test/test_uuid_class.cpp

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

{ // example using memcpy
    unsigned char uuid_data[16];
    // fill uuid_data

    boost::uuids::uuid u;

    std::memcpy(&u.data, uuid_data, 16);
}

{ // example using aggregate initializers
    boost::uuids::uuid u =
    {{ 0x12 ,0x34, 0x56, 0x78
     , 0x90, 0xab
     , 0xcd, 0xef
     , 0x12, 0x34
     , 0x56, 0x78, 0x90, 0xab, 0xcd, 0xef
    }};
}

// example of creating a uuid class that
// initializes the uuid in the constructor
// using a defined mechanism

class uuid_class : public boost::uuids::uuid
{
public:
    uuid_class()
        : boost::uuids::uuid(boost::uuids::random_generator()())
    {}

    explicit uuid_class(boost::uuids::uuid const& u)
        : boost::uuids::uuid(u)
    {}

    operator boost::uuids::uuid() {
        return static_cast<boost::uuids::uuid&>(*this);
    }

    operator boost::uuids::uuid() const {
        return static_cast<boost::uuids::uuid const&>(*this);
    }
};

uuid_class u1;
uuid_class u2;

assert(u1 != u2);

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
{
public:

    // data

    std::uint8_t data[ 16 ];

public:

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

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

Iteration

Both constant and mutable iterators are provided.

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

data + 0.

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

data + 16.

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

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

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

Copyright 2017 James E. King III

Copyright 2024 Christian Mazakas

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)