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.
UUIDs have many applications. Some examples follow: Databases may use UUIDs to identify rows or records in order to ensure that they are unique across different databases, or for publication/subscription services. Network messages may be identified with a UUID to ensure that different parts of a message are put back together again. Distributed computing may use UUIDs to identify a remote procedure call. Transactions and classes involved in serialization may be identified by UUIDs. Microsoft’s component object model (COM) uses UUIDs to distinguish different software component interfaces. UUIDs are inserted into documents from Microsoft Office programs. UUIDs identify audio or video streams in the Advanced Systems Format (ASF). UUIDs are also a basis for OIDs (object identifiers), and URNs (uniform resource name).
An attractive feature of UUIDs when compared to alternatives is their relative small size, of 128-bits, or 16-bytes. Another is that the creation of UUIDs does not require a centralized authority.
When UUIDs are generated by one of the defined mechanisms, they are either guaranteed to be unique, different from all other generated UUIDs (that is, it has never been generated before and it will never be generated again), or it is extremely likely to be unique (depending on the mechanism).
Revision History
Changes in Boost 1.87.0
-
Restored the ability to construct a
constexpr uuid
that was inadvertently lost in 1.86.
Changes in Boost 1.86.0 (major update)
-
C++03 is no longer supported, a C++11 compiler is required. This includes GCC 4.8 or later, MSVC 14.0 or later, and MinGW-w64.
-
Removed direct dependencies on Core, Io, Move, NumericConversion, StaticAssert, TTI, Random, ContainerHash. The library now only has five Boost dependencies in total (as opposed to 39 in Boost 1.85.)
-
Moved
std::hash
support fromuuid_hash.hpp
touuid.hpp
. -
Moved serialization support from
uuid_serialize.hpp
touuid.hpp
. -
Improved the quality and speed of
hash_value
. -
Added
operator<=>
. -
The generic (non-SIMD) implementations of
is_nil
,operator==
,operator<
,swap
, andoperator<=>
now use__uint128_t
operations when that type is available, anduint64_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 forbasic_random_generator<std::random_device>
and its use is discouraged. -
random_generator_mt19937
is now an alias forbasic_random_generator<std::mt19937>
and its use is discouraged. -
random_generator
now uses a cryptographically strong pseudorandom number generator (ChaCha20/12), seeded with entropy fromstd::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
andname_generator_sha1
), it was made a private implementation detail and is no longer part of the public interface. -
While
name_generator
andname_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 thestd::runtime_error
exceptions thrown bystring_generator
. -
Added overloads of
to_chars
takingCh* first, Ch* last
andCh(&)[N]
. -
The default constructor of
uuid
now produces a nil UUID instead of an uninitialized one. -
u.data()
, whereu
is of typeuuid
, now returns a pointer to the firstuint8_t
of the representation (same asu.begin()
.) For backward compatibility,data
is a function object withoperator()
, rather than a member function, which allows most existing uses ofdata
as a public member to remain valid, if no longer encouraged. -
uuid
now has the same alignment asstd::uint64_t
. It was previously unaligned (had alignment of 1, same asstd::uint8_t
.) To restore the 1.85 behavior, define the macroBOOST_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 |
---|---|
|
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. |
|
If defined, enables optimizations for SSE2 extensions available in x86 processors. |
|
If defined, enables optimizations for SSE3 extensions available in x86 processors. |
|
If defined, enables optimizations for SSE4.1 extensions available in x86 processors. |
|
If defined, enables optimizations for AVX extensions available in modern x86 processors. |
|
If defined, enables optimizations for AVX-512 and AVX10.1 extensions available in modern x86 processors. The library does not require 512-bit vectors and is compatible with CPUs implementing AVX-512F, CD, VL, BW and DQ instruction subsets (i.e. equivalent to Intel Skylake-X). |
By default the library attempts to detect the availability of SIMD extensions in the target CPU at compile time and automatically defines the appropriate macros if succeeded.
The BOOST_UUID_USE_SSE*
and BOOST_UUID_USE_AVX*
macros can be defined by users, if auto-detection fails and it is known that the target CPU will have the extension.
Do not enable these extensions unless you’re certain that they will always be available on any machine that will run your program.
The library performs no run time checks, so if an extension is missing, the program will likely crash.
Note that enabling more advanced extensions implies that more basic ones are also available.
Alignment
Macro | Description |
---|---|
|
If defined, leaves |
By default, uuid
has the same alignment as std::uint64_t
. Define BOOST_UUID_DISABLE_ALIGNMENT
to leave it unaligned.
Examples
Tagging
// example of tagging an object with a uuid
// see boost/libs/uuid/test/test_tagging.cpp
#include <boost/uuid/uuid.hpp>
#include <boost/uuid/uuid_generators.hpp>
class object
{
public:
object()
: tag(boost::uuids::random_generator()())
, state(0)
{}
explicit object(int state)
: tag(boost::uuids::random_generator()())
, state(state)
{}
object(object const& rhs)
: tag(rhs.tag)
, state(rhs.state)
{}
bool operator==(object const& rhs) const {
return tag == rhs.tag;
}
object& operator=(object const& rhs) {
tag = rhs.tag;
state = rhs.state;
}
int get_state() const { return state; }
void set_state(int new_state) { state = new_state; }
private:
boost::uuids::uuid tag;
int state;
};
object o1(1);
object o2 = o1;
o2.set_state(2);
assert(o1 == o2);
object o3(3);
assert(o1 != o3);
assert(o2 != o3);
Byte Extraction
It is sometimes useful to get at the 16 bytes of a uuid
directly. Typical use is as follows:
boost::uuids::uuid u;
std::vector<std::uint8_t> v(u.size());
std::copy(u.begin(), u.end(), v.begin());
Note: boost::uuids::uuid::size()
always returns 16.
Reference
<boost/uuid.hpp>
This convenience header makes the entire library available.
Synopsis
#include <boost/uuid/uuid.hpp>
#include <boost/uuid/uuid_io.hpp>
#include <boost/uuid/uuid_generators.hpp>
<boost/uuid/uuid.hpp>
Synopsis
namespace boost {
namespace uuids {
class uuid
{
private:
std::uint8_t data_[ 16 ] = {}; // exposition only
public:
// constructors
uuid() = default;
uuid( std::uint8_t const (&r)[ 16 ] );
// iteration
using value_type = std::uint8_t;
using reference = std::uint8_t&;
using const_reference = std::uint8_t const&;
using iterator = std::uint8_t*;
using const_iterator = std::uint8_t const*;
using size_type = std::size_t;
using difference_type = std::ptrdiff_t;
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
// data
std::uint8_t* data() noexcept;
std::uint8_t const* data() const noexcept;
// size
constexpr size_type size() const noexcept;
static constexpr size_type static_size() noexcept;
// is_nil
bool is_nil() const noexcept;
// variant
enum variant_type
{
variant_ncs, // NCS backward compatibility
variant_rfc_4122, // defined in RFC 4122 document
variant_microsoft, // Microsoft Corporation backward compatibility
variant_future // future definition
};
variant_type variant() const noexcept;
// version
enum version_type
{
version_unknown = -1,
version_time_based = 1,
version_dce_security = 2,
version_name_based_md5 = 3,
version_random_number_based = 4,
version_name_based_sha1 = 5,
version_time_based_v6 = 6,
version_time_based_v7 = 7,
version_custom_v8 = 8
};
version_type version() const noexcept;
// time-based fields
using timestamp_type = std::uint64_t;
using clock_seq_type = std::uint16_t;
using node_type = std::array<std::uint8_t, 6>;
timestamp_type timestamp_v1() const noexcept;
uuid_clock::time_point time_point_v1() const noexcept;
timestamp_type timestamp_v6() const noexcept;
uuid_clock::time_point time_point_v6() const noexcept;
timestamp_type timestamp_v7() const noexcept;
std::chrono::time_point<std::chrono::system_clock, std::chrono::milliseconds>
time_point_v7() const noexcept;
clock_seq_type clock_seq() const noexcept;
node_type node_identifier() const noexcept;
// swap
void swap( uuid& rhs ) noexcept;
};
// operators
bool operator==( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;
std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;
// free swap
void swap( uuid& lhs, uuid& rhs ) noexcept;
// hash_value
std::size_t hash_value( uuid const& u ) noexcept;
}} // namespace boost::uuids
// Boost.Serialization support
BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
// std::hash support
template<> struct std::hash<boost::uuids::uuid>;
Constructors
uuid() = default;
- Effects:
-
Zero-initializes
data_
. - Postconditions:
-
is_nil()
.
uuid( std::uint8_t const (&r)[ 16 ] );
- Effects:
-
Initializes the elements of
data_
from the corresponding elements ofr
. - Example:
-
uuid dns = {{ 0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
Iteration
Both constant and mutable iterators are provided.
iterator begin() noexcept;
const_iterator begin() const noexcept;
- Returns:
-
data()
.
iterator end() noexcept;
const_iterator end() const noexcept;
- Returns:
-
data() + size()
. - Example:
-
using namespace boost::uuids; uuid u; for( uuid::const_iterator it = u.begin(); it != u.end(); ++it ) { uuid::value_type v = *it; // do something with the octet v } for( uuid::iterator it = u.begin(); it != u.end(); ++it ) { *it = 0; }
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 theuuid
is equal to the nil UUID,{00000000-0000-0000-0000-000000000000}
, otherwisefalse
.
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).
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
.
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 eitherchar
orwchar_t
. - Effects:
-
Inserts the string representation of
u
into the output streamos
.The string representation of a
uuid
ishhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh
, whereh
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 eitherchar
orwchar_t
. - Effects:
-
Parses a
uuid
string representation fromis
and stores the result intou
.
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 typechar
) to the output iteratorout
. - 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 ofchar
,wchar_t
,char8_t
,char16_t
,char32_t
.) - Effects:
-
If
last - first >= 36
, writes the string representation ofu
(exactly 36 characters, not null terminated) into the buffer starting atfirst
and returnstrue
. Otherwise, returnsfalse
. - 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 ofchar
,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) intobuffer
. - 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
ofs
must be eitherchar
orwchar_t
. - Effects:
-
Parses the string
s
into auuid
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 auuid
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 eitherchar
orwchar_t
. - Effects:
-
Parses the character sequence
[begin, end)
into auuid
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 usesnamespace_uuid
as the namespace.
template<class Ch> uuid operator()( Ch const* name ) const noexcept;
- Requires:
-
Ch
must be one ofchar
,wchar_t
,char8_t
,char16_t
, orchar32_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
ischar
orchar8_t
, the characters are processed as octets directly; -
If
Ch
iswchar_t
, the characters are converted touint32_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 ofchar
,wchar_t
,char8_t
,char16_t
, orchar32_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 frombuffer
.
<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 initializesp_
tonullptr
. Ifg_.seed()
is a valid expression, callsg_.seed( seed_seq );
to seedg_
, whereseed_seq
is an object providing agenerate( first, last )
member function that fills the range[first, last)
using entropy obtained fromstd::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 initializesp_
to&gen
.
explicit basic_random_generator( UniformRandomNumberGenerator* pGen );
- Effects:
-
Value-initializes
g_
and initializesp_
topGen
.
result_type operator()();
- Effects:
-
Generates and returns a version 4 UUID using random numbers obtained from
*p_
, ifp_ != nullptr
, or fromg_
, 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 fromstd::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 touuid_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 totp
.
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 totp
. - 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 totimestamp
100 nanosecond intervals since theuuid_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 totp
. - 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 innode_
and a pseudorandom 14 bit clock sequence instate_.clock_seq
. Initalizesstate_.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_
tonode
andstate_
tostate
.
time_generator_v1( uuid::node_type const& node, std::atomic<state_type>& state ) noexcept;
- Effects:
-
Initializes
node_
tonode
andps_
to&state
.
operator()
result_type operator()() noexcept;
- Effects:
-
Using the state in
state_
, ifps_
isnullptr
, or the state in*ps_
, ifps_
is notnullptr
, atomically computes and sets a new state by retrieving the system time as if byuuid_clock::now()
, converting it to a timestamp as if byuuid_clock::to_timestamp
, storing the result instate.timestamp
, and incrementingstate.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 fromstd::random_device
.
time_generator_v7( time_generator_v7 const& rhs );
- Effects:
-
Copies the state of
rhs
into*this
, then reseedsthis->rng_
using entropy fromstd::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 ofrhs.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 forthis->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 ofrhs.rng_
such that it no longer produces the same random number sequence. - Returns:
-
*this
.
operator()
result_type operator()() noexcept;
- Effects:
-
-
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. -
Creates a new version 7 UUID and initializes its
unix_ts_ms
field with the number of milliseconds in the timestamp. -
Initializes the
rand_a
field with the residual number of microseconds from the timestamp. -
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. -
Initializes the rest of the
rand_b
field to random values obtained from the internal CSPRNGrng_
. -
Returns the UUID.
-
- Remarks:
-
operator()
generates a monotonically increasing sequence of UUIDs, if the following requirements are met:-
The system clock never goes backwards;
-
The system clock has at least millisecond resolution;
-
No more than 64 UUIDs are generated per microsecond (no more than one every 16 nanoseconds.)
-
<boost/uuid/time_generator.hpp>
Synopsis
#include <boost/uuid/time_generator_v1.hpp>
#include <boost/uuid/time_generator_v6.hpp>
#include <boost/uuid/time_generator_v7.hpp>
This convenience header makes the three time-based generators time_generator_v1
, time_generator_v6
, and time_generator_v7
, available.
Design Notes
The document http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf was used to design and implement the uuid
struct.
All functions are re-entrant. Classes are as thread-safe as an int. That is an instance cannot be shared between threads without proper synchronization.
Acknowledgements
A number of people on the boost.org mailing list provided useful comments and greatly helped to shape the library.
The documentation was converted to Asciidoc format by Christian Mazakas.
Copyright and License
Copyright 2006 Andy Tompkins
Copyright 2017 James E. King III
Copyright 2024 Christian Mazakas
Copyright 2024 Peter Dimov
Distributed under the Boost Software License, Version 1.0.
Old Revision History
This section contains the old revision history that used to be maintained as comments in the library header files.
boost/uuid/uuid.hpp
// Revision History
// 06 Feb 2006 - Initial Revision
// 09 Nov 2006 - fixed variant and version bits for v4 guids
// 13 Nov 2006 - added serialization
// 17 Nov 2006 - added name-based guid creation
// 20 Nov 2006 - add fixes for gcc (from Tim Blechmann)
// 07 Mar 2007 - converted to header only
// 10 May 2007 - removed need for Boost.Thread
// - added better seed - thanks Peter Dimov
// - removed null()
// - replaced byte_count() and output_bytes() with size() and begin() and end()
// 11 May 2007 - fixed guid(ByteInputIterator first, ByteInputIterator last)
// - optimized operator>>
// 14 May 2007 - converted from guid to uuid
// 29 May 2007 - uses new implementation of sha1
// 01 Jun 2007 - removed using namespace directives
// 09 Nov 2007 - moved implementation to uuid.ipp file
// 12 Nov 2007 - moved serialize code to uuid_serialize.hpp file
// 25 Feb 2008 - moved to namespace boost::uuids
// 19 Mar 2009 - changed to a POD, reorganized files
// 28 Nov 2009 - disabled deprecated warnings for MSVC
// 30 Nov 2009 - used BOOST_STATIC_CONSTANT
// 02 Dec 2009 - removed BOOST_STATIC_CONSTANT - not all compilers like it
// 29 Apr 2013 - added support for noexcept and constexpr, added optimizations for SSE/AVX
boost/uuid/uuid_io.hpp
// Revision History
// 20 Mar 2009 - Initial Revision
// 28 Nov 2009 - disabled deprecated warnings for MSVC
boost/uuid/detail/sha1.hpp
// Revision History
// 29 May 2007 - Initial Revision
// 25 Feb 2008 - moved to namespace boost::uuids::detail
// 10 Jan 2012 - can now handle the full size of messages (2^64 - 1 bits)