boost.org

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

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

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.

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

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.

Read the original on boost.org ↗