Académique Documents
Professionnel Documents
Culture Documents
This
...one is the
of the documentation
most highly regardedfor
andanexpertly
old version of Boost.
designed C++ library projects in the
Click here to view this page for the latest version. world.
Herb Sutter and Andrei Alexandrescu, C++ Coding Standards
Uuid
Contents
1. Introduction
2. Conguration
3. Examples
Tagging
POD Eiciencies
Byte Extraction
Reference
boost/uuid/uuid.hpp
Synopsis
Size
Iteration
Nil uuid
Variant
Version
Swap
Operators
Hash
boost/uuid/uuid_generators.hpp
Synopsis
boost/uuid/nil_generator.hpp
Synopsis
Nil Generator
boost/uuid/string_generator.hpp
Synopsis
String Generator
boost/uuid/name_generator.hpp
Synopsis
Name Generator
boost/uuid/random_generator.hpp
Synopsis
Random Generator
boost/uuid/uuid_io.hpp
Synopsis
Stream Operators
To String
boost/uuid/uuid_serialize.hpp
Synopsis
Serialization
4. Design notes
5. History and Acknowledgements
Introduction
A UUID, or Universally unique identier, is intended to uniquely identify information in a
1 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
distributed environment without signicant 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 dierent databases, or for
publication/subscription services. Network messages may be identied with a UUID to ensure
that dierent 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 identied by UUIDs. Microsoft's component object model (COM) uses UUIDs to distinguish
dierent software component interfaces. UUIDs are inserted into documents from Microsoft
Oice programs. UUIDs identify audio or video streams in the Advanced Systems Format (ASF).
UUIDs are also a basis for OIDs (object identiers), 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 dened mechanisms, they are either guaranteed to be
unique, dierent 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).
Conguration
The library does not require building or any special conguration to be used. However, there are
a few options that can be enabled by dening macros prior to including library headers. These
macros are summarized in the following table.
Macro Description
If dened, disables any optimizations for SIMD-enabled processors. Generic
versions of algorithms will be used instead. This may result in suboptimal
BOOST_UUID_NO_SIMD
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 dened, enables optimizations for SSE2 exstensions available in modern
x86 processors.
If dened, enables optimizations for SSE3 exstensions available in modern
BOOST_UUID_USE_SSE3
x86 processors.
If dened, enables optimizations for SSE4.1 exstensions available in modern
BOOST_UUID_USE_SSE41
x86 processors.
By default the library attempts to detect the availability of SIMD extensions in the target CPU at
compile time and automatically denes the appropriate macros if succeeded. The
BOOST_UUID_USE_SSE* macros can be dened 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
2 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
// 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)
{}
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 Eiciencies
This library implements a UUID as a POD allowing a UUID to be used in the most eicient 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
dened mechanisms. But a class based on a UUID can be dened that does initialize itself to a
value generated by one of the dened mechanisms.
Note that boost::is_pod is specialized for boost::uuids::uuid and depends on Boost.TypeTraits. Dene
BOOST_UUID_NO_TYPE_TRAITS before including boost/uuid/uuid.hpp to remove the dependency on
Boost.TypeTraits.
#include <boost/uuid/uuid.hpp>
#include <boost/uuid/uuid_generators.hpp>
3 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
boost::uuids::uuid u;
operator boost::uuids::uuid() {
return static_cast<boost::uuids::uuid&>(*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<char> v(u.size());
std::copy(u.begin(), u.end(), v.begin());
Reference
boost/uuid/uuid.hpp
Synopsis
4 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
namespace boost {
namespace uuids {
class uuid {
public:
typedef uint8_t value_type;
typedef uint8_t& reference;
typedef uint8_t const& const_reference;
typedef uint8_t* iterator;
typedef uint8_t const* const_iterator;
typedef std::size_t size_type;
typedef std::ptrdiff_t difference_type;
// iteration
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
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;
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_type version() const noexcept;
// Swap function
void swap(uuid& rhs) noexcept;
uint8_t data[static_size()];
};
// standard 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;
}} // namespace boost::uuids
Size
The size of a uuid (in bytes) can be obtained either by calling the function boost::uuids::uuid::size()
or by calling the static function boost::uuids::uuid::static_size(), both always return 16.
5 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
boost::uuids::uuid u;
assert(16 == u.size());
assert(16 == boost::uuids::uuid::static_size());
Iteration
boost::uuids::uuid u;
for (boost::uuids::uuid::const_iterator it=u.begin(); it!=u.end(); ++it) {
boost::uuids::uuid::value_type v = *it;
}
for (boost::uuids::uuid::iterator it=u.begin(); it!=u.end(); ++it) {
*it = 0;
}
Nil uuid
The function, boost::uuids::uuid::is_nil() returns true if and only if the uuid is equal to
{00000000-0000-0000-0000-000000000000}.
Variant
boost::uuids::uuid u;
boost::uuids::uuid::variant_type v = u.variant();
Version
Four bits of a uuid determine the variant, that is the mechanism used to generate the uuid.
boost::uuids::uuid u;
boost::uuids::uuid::version_type v = u.version();
Swap
Operators
All of the standard numeric operators are dened for the uuid class. These include:
operator==
operator!=
operator<
operator>
operator<=
6 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
operator>=
Hash Function
boost::hash<boost::uuids::uuid> uuid_hasher;
std::size_t uuid_hash_value = uuid_hasher(boost::uuids::uuid());
boost/uuid/uuid_generators.hpp
Synopsis
#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 {
typedef uuid result_type;
}} //namespace boost::uuids
Nil Generator
boost::uuids::nil_generator gen;
boost::uuids::uuid u = gen();
assert(u.is_nil() == true);
// or for convenience
boost::uuids::uuid u = boost::uuids::nil_uuid();
assert(u.is_nil() == true);
boost/uuid/string_generator.hpp
Synopsis
namespace boost {
namespace uuids {
7 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
struct string_generator {
typedef uuid result_type;
}} //namespace boost::uuids
String Generator
boost::uuids::string_generator gen;
boost::uuids::uuid u1 = gen("{01234567-89ab-cdef-0123-456789abcdef}");
boost::uuids::uuid u2 = gen(L"01234567-89ab-cdef-0123-456789abcdef");
boost::uuids::uuid u3 = gen(std::string("0123456789abcdef0123456789abcdef"));
boost::uuids::uuid u4 = gen(std::wstring(L"01234567-89ab-cdef-0123-456789abcdef"));
boost/uuid/name_generator.hpp
Synopsis
namespace boost {
namespace uuids {
class name_generator {
public:
typedef uuid result_type;
}} //namespace boost::uuids
Name Generator
The boost::uuids::name_generator class generates a name based uuid from a namespace uuid and a
name.
boost::uuids::name_generator gen(dns_namespace_uuid);
boost::uuids::uuid u = gen("boost.org");
boost/uuid/random_generator.hpp
Synopsis
namespace boost {
8 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
namespace uuids {
basic_random_generator();
explicit basic_random_generator(UniformRandomNumberGenerator& gen);
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
uuid operator()();
};
typedef basic_random_generator<mt19937> random_generator;
}} // namespace boost::uuids
Random Generator
The boost::uuids::basic_random_generator class generates a random number based uuid from a random
number generator (one that conforms to the UniformRandomNumberGenerator concept).
boost/uuid/uuid_io.hpp
Synopsis
namespace boost {
namespace uuids {
}} // namespace boost::uuids
Stream Operators
The standard input and output stream operators << and >> are provided by including boost/uuid
/uuid_io.hpp. The string representation of a uuid is hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh where h is a
hexidecimal digit.
9 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
std::stringstream ss;
ss << u1;
boost::uuids::uuid u2;
ss >> u2;
assert(u1, u2);
std::string s = boost::lexical_cast<std::string>(u);
boost::uuids::uuid u2 = boost::lexical_cast<boost::uuids::uuid>(s);
assert(u1 == u2);
To String
The functions to_string and to_wstring are provided as a convenience to convert a uuid to a string.
They are also likely faster than the stream operators or using boost::lexical_cast.
std::string s1 = to_string(u);
std::wstring s2 = to_wstring(u);
boost/uuid/uuid_serialize.hpp
Synopsis
namespace boost {
namespace uuids {
BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
}} // namespace boost::uuids
Serialization
Design notes
The document, http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf, was used to design
and implement the boost::uuids::uuid struct.
10 of 11 18/04/17 11:52
Uuid Library - 1.61.0 http://www.boost.org/doc/libs/1_61_0/libs/uuid/uu...
Using Valgrind produces a number of false positives with the default constructor of
boost::uuids::basic_random_generator. One solution is to suppress the errors as described in Valgrind's
documentation. Another solution is to use a dierent constructor of
boost::uuids::basic_random_generator and explicitly pass in a random number generator.
boost::mt19937 ran;
ran.seed(time(NULL)); // one should likely seed in a better way
boost::uuids::basic_random_generator<boost::mt19937> gen(&ran);
boost::uuids::uuid u = gen();
The boost::uuids::name_generator class uses the SHA-1 hash function to compute the uuid.
All functions are re-entrant. Classes are as thread-safe as an int. That is an instance can not be
shared between threads without proper synchronization.
Distributed under the Boost Software License, Version 1.0. (See accompanying le
LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)
11 of 11 18/04/17 11:52