boost/uuid
2
0
Fork 0
mirror of https://github.com/boostorg/uuid.git synced 2026-01-19 04:42:16 +00:00
Code Issues Projects Releases Wiki Activity

transliterate docs to adoc

Browse Source
This commit is contained in:
Christian Mazakas
2024-04-24 09:21:43 -07:00
parent ca1e2d94b3
commit b217e8dd04
20 changed files with 837 additions and 922 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
doc/Jamfile.v2 Normal file
View File

@@ -0,0 +1,21 @@
# Copyright 2024 Christian Mazakas
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
import asciidoctor ;
html uuid.html : uuid.adoc ;
install html_ : uuid.html : <location>html ;
pdf uuid.pdf : uuid.adoc ;
explicit uuid.pdf ;
install pdf_ : uuid.pdf : <location>pdf ;
explicit pdf_ ;
###############################################################################
alias boostdoc ;
explicit boostdoc ;
alias boostrelease : html_ ;
explicit boostrelease ;

43
doc/index.html
View File

@@ -1,43 +0,0 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Uuid Library</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../../../boost.png" alt="boost.png (6897 bytes)" WIDTH="277" HEIGHT="86"></td>
<td><a href="../../../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font></a></td>
<td><a href="../../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big></font></a></td>
<td><a href="http://www.boost.org/users/people.html"><font face="Arial" color="#FFFFFF"><big>People </big></font></a></td>
<td><a href="http://www.boost.org/users/faq.html"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font></a></td>
<td><a href="../../../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font></a></td>
</tr>
</table>
<h1>Uuid library</h1>
<p>The header uuid.hpp provides an implementation of Universally Unique Identifiers.
</p>
<p>This implementation is intended for general use.</p>
<ul>
<li><a href="uuid.html">Documentation</a> (HTML).</li>
<li>Header <a href="../../../boost/uuid/uuid.hpp">uuid.hpp</a>.</li>
<li>See the <a href="uuid.html">documentation</a> for links to sample programs.</li>
<li>Submitted by Andy Tompkins</a>.</li>
</ul>
<p>Revised&nbsp; May 14, 2007</p>
<hr>
<p>© Copyright Andy Tompkins, 2006</p>
<p> Distributed under the Boost Software
License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="https://www.boost.org/LICENSE_1_0.txt">
www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

20
doc/uuid.adoc Normal file
View File

@@ -0,0 +1,20 @@
= Boost.Uuid
:toc: left
:toclevels: 3
:idprefix:
:docinfo: private-footer
:source-highlighter: rouge
:source-language: c++
:nofooter:
:sectlinks:
:leveloffset: +1
include::uuid/introduction.adoc[]
include::uuid/configuration.adoc[]
include::uuid/examples.adoc[]
include::uuid/reference.adoc[]
include::uuid/concepts.adoc[]
include::uuid/design_notes.adoc[]
include::uuid/acknowledgements.adoc[]
include::uuid/copyright.adoc[]

879
doc/uuid.html
View File

@@ -1,879 +0,0 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Uuid Library</title>
<style type="text/css">
pre { margin: 1em; padding: 1em; border: 1px solid #ddd; }
</style>
</head>
<body>
<h1><img src="../../../boost.png" alt="Boost" WIDTH="277" HEIGHT="86">Uuid</h1>
<h2><a name="Contents">Contents</a></h2>
<ol>
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#Configuration">Configuration</a></li>
<li><a href="#Examples">Examples</a></li>
<ul>
<li><a href="#Tagging">Tagging</a></li>
<li><a href="#POD Efficiencies">POD Efficiencies</a></li>
<li><a href="#Byte Extraction">Byte Extraction</a></li>
</ul
<li><a href="#Reference">Reference</a></li>
<ul>
<li><a href="#boost/uuid/uuid.hpp">boost/uuid/uuid.hpp</a></li>
<ul>
<li><a href="#Synopsis">Synopsis</a></li>
<li><a href="#Size">Size</a></li>
<li><a href="#Iteration">Iteration</a></li>
<li><a href="#Nil">Nil uuid</a></li>
<li><a href="#Variant">Variant</a></li>
<li><a href="#Version">Version</a></li>
<li><a href="#Swap">Swap</a></li>
<li><a href="#Operators">Operators</a></li>
<li><a href="#Hash">Hash</a></li>
</ul>
<li><a href="#boost/uuid/uuid_generators.hpp">boost/uuid/uuid_generators.hpp</a></li>
<ul>
<li><a href="#Synopsis_generators">Synopsis</a></li>
</ul>
<li><a href="#boost/uuid/nil_generator.hpp">boost/uuid/nil_generator.hpp</a></li>
<ul>
<li><a href="#Synopsis_nil_generator">Synopsis</a></li>
<li><a href="#Nil Generator">Nil Generator</a></li>
</ul>
<li><a href="#boost/uuid/string_generator.hpp">boost/uuid/string_generator.hpp</a></li>
<ul>
<li><a href="#Synopsis_string_generator">Synopsis</a></li>
<li><a href="#String Generator">String Generator</a></li>
</ul>
<li><a href="#boost/uuid/name_generator.hpp">boost/uuid/name_generator.hpp</a></li>
<ul>
<li><a href="#Synopsis_name_generator">Synopsis</a></li>
<li><a href="#Name Generator">Name Generator</a></li>
</ul>
<li><a href="#boost/uuid/random_generator.hpp">boost/uuid/random_generator.hpp</a></li>
<ul>
<li><a href="#Synopsis_random_generator">Synopsis</a></li>
<li><a href="#Random Generator">Random Generator</a></li>
</ul>
<li><a href="#boost/uuid/uuid_io.hpp">boost/uuid/uuid_io.hpp</a></li>
<ul>
<li><a href="#Synopsis_io">Synopsis</a></li>
<li><a href="#Stream_operators">Stream Operators</a></li>
<li><a href="#to_chars">To Chars</a></li>
<li><a href="#to_string">To String</a></li>
</ul>
<li><a href="#boost/uuid/uuid_serialize.hpp">boost/uuid/uuid_serialize.hpp</a></li>
<ul>
<li><a href="#Synopsis_serialize">Synopsis</a></li>
<li><a href="#Serialization">Serialization</a></li>
</ul>
</ul>
<li><a href="#Concepts">Concepts</a></li>
<ul>
<li><a href="#Concept:NameHashProvider">NameHashProvider</a></li>
</ul>
<li><a href="#Design notes">Design notes</a></li>
<li><a href="#History and Acknowledgements">History and Acknowledgements</a></li>
</ol>
<h2><a name="Introduction">Introduction</a></h2>
<p>
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.
<p>
A formal definition for UUID can be found in <A HREF="https://www.ietf.org/rfc/rfc4122.txt">RFC 4122</A>.
<p>
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).
<p>
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.
<p>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).
<h2><a name="Configuration">Configuration</a></h2>
<p>
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. These macros are summarized in the following table.
<p>
<table border="1">
<tr>
<th>Macro</th><th>Description</th>
</tr>
<tr>
<td><tt>BOOST_UUID_NO_SIMD</tt></td><td>If defined, disables any optimizations for <a href="http://en.wikipedia.org/wiki/SIMD">SIMD</a>-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.</td>
</tr>
<tr>
<td><tt>BOOST_UUID_USE_SSE2</tt></td><td>If defined, enables optimizations for <a href="http://en.wikipedia.org/wiki/SSE2">SSE2</a> exstensions available in modern x86 processors.</td>
</tr>
<tr>
<td><tt>BOOST_UUID_USE_SSE3</tt></td><td>If defined, enables optimizations for <a href="http://en.wikipedia.org/wiki/SSE3">SSE3</a> exstensions available in modern x86 processors.</td>
</tr>
<tr>
<td><tt>BOOST_UUID_USE_SSE41</tt></td><td>If defined, enables optimizations for <a href="http://en.wikipedia.org/wiki/SSE4#SSE4.1">SSE4.1</a> exstensions available in modern x86 processors.</td>
</tr>
</table>
<p>
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 <tt>BOOST_UUID_USE_SSE*</tt> 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.
<h2><a name="Examples">Examples</a></h2>
<h3><a name="Tagging">Tagging</a></h3>
<pre>
// example of tagging an object with a uuid
// see <a href="../test/test_tagging.cpp"><tt>boost/libs/uuid/test/test_tagging.cpp</tt></a>
#include &lt;<a href="../../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>&gt;
#include &lt;<a href="../../../boost/uuid/uuid_generators.hpp"><tt>boost/uuid/uuid_generators.hpp</tt></a>&gt;
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&amp; rhs)
: tag(rhs.tag)
, state(rhs.state)
{}
bool operator==(object const&amp; rhs) const {
return tag == rhs.tag;
}
object&amp; operator=(object const&amp; 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);
</pre>
<h3><a name="POD Efficiencies">POD Efficiencies</a></h3>
<p>
This library implements a UUID as a POD allowing a UUID
to be used in the most efficient ways, including using memcpy,
and aggregate initializers. A drawback is that a POD can
not have any constructors, and thus declaring a UUID will not
initialize it to a value generated by one of the defined
mechanisms. But a class based on a UUID can be defined
that does initialize itself to a value generated by one of
the defined mechanisms.
<p>
Note that <tt>boost::is_pod</tt> is specialized for <tt>boost::uuids::uuid</tt>
and depends on <a href="http://www.boost.org/libs/type_traits">Boost.TypeTraits</a>.
Define <tt>BOOST_UUID_NO_TYPE_TRAITS</tt> before including <a href="../../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>
to remove the dependency on <a href="http://www.boost.org/libs/type_traits">Boost.TypeTraits</a>.
<pre>
// example using memcpy and aggregate initializers
// example of a class uuid see <a href="../test/test_uuid_class.cpp"><tt>boost/libs/uuid/test/test_uuid_class.cpp</tt></a>
#include &lt;<a href="../../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>&gt;
#include &lt;<a href="../../../boost/uuid/uuid_generators.hpp"><tt>boost/uuid/uuid_generators.hpp</tt></a>&gt;
{ // example using memcpy
unsigned char uuid_data[16];
// fill uuid_data
boost::uuids::uuid u;
memcpy(&amp;u, uuid_data, 16);
}
{ // example using aggregate initializers
boost::uuids::uuid u =
{ 0x12 ,0x34, 0x56, 0x78
, 0x90, 0xab
, 0xcd, 0xef
, 0x12, 0x34
, 0x56, 0x78, 0x90, 0xab, 0xcd, 0xef
};
}
// example of creating a uuid class that
// initializes the uuid in the constructor
// using a defined mechanism
class uuid_class : public boost::uuids::uuid
{
public:
uuid_class()
: boost::uuids::uuid(boost::uuids::random_generator()())
{}
explicit uuid_class(boost::uuids::uuid const&amp; u)
: boost::uuids::uuid(u)
{}
operator boost::uuids::uuid() {
return static_cast&lt;boost::uuids::uuid&amp;&gt;(*this);
}
operator boost::uuids::uuid() const {
return static_cast&lt;boost::uuids::uuid const&amp;&gt;(*this);
}
};
uuid_class u1;
uuid_class u2;
assert(u1 != u2);
</pre>
<h3><a name="Byte Extraction">Byte Extraction</a></h3>
<p>It is sometimes useful to get at the 16 bytes of a <b>uuid</b> directly.
Typical use is as follows:
<pre>
boost::uuids::uuid u;
std::vector&lt;uint8_t&gt; v(u.size());
std::copy(u.begin(), u.end(), v.begin());
</pre>
<p>Note: <tt>boost::uuids::uuid::size()</tt> always returns 16.
<h2><a name="Reference">Reference</a></h2>
<h3><a name="boost/uuid/uuid.hpp" href="../../../boost/uuid/uuid.hpp">boost/uuid/uuid.hpp</a></h3>
<h4><a name="Synopsis">Synopsis</a></h4>
<pre>
namespace boost {
namespace uuids {
class uuid {
public:
typedef uint8_t value_type;
typedef uint8_t&amp; reference;
typedef uint8_t const&amp; const_reference;
typedef uint8_t* iterator;
typedef uint8_t const* const_iterator;
typedef std::size_t size_type;
typedef std::ptrdiff_t difference_type;
static constexpr size_type static_size() noexcept;
// iteration
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
constexpr size_type size() const noexcept;
bool is_nil() 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&amp; rhs) noexcept;
uint8_t data[static_size()];
};
// standard operators
bool operator==(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
bool operator!=(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
bool operator&lt;(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
bool operator&gt;(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
bool operator&lt;=(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
bool operator&gt;=(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
void swap(uuid&amp; lhs, uuid&amp; rhs) noexcept;
std::size_t hash_value(uuid const&amp; u) noexcept;
}} // namespace boost::uuids
</pre>
<h4><a name="Size">Size</a></h4>
<p>The size of a <b>uuid</b> (in bytes) can be obtained either by
calling the function <tt>boost::uuids::uuid::size()</tt> or by
calling the static function <tt>boost::uuids::uuid::static_size()</tt>,
both always return 16.
<pre>
boost::uuids::uuid u;
assert(16 == u.size());
assert(16 == boost::uuids::uuid::static_size());
</pre>
<h4><a name="Iteration">Iteration</a></h4>
<p>Both iterators and constant iterators are provided.
<pre>
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;
}
</pre>
<h4><a name="Nil">Nil uuid</a></h4>
<p>The function, <tt>boost::uuids::uuid::is_nil()</tt> returns true if and
only if the <b>uuid</b> is equal to {00000000-0000-0000-0000-000000000000}.
</p>
<h4><a name="Variant">Variant</a></h4>
<p>Three bits of a <b>uuid</b> determine the variant.</p>
<pre>
boost::uuids::uuid u;
boost::uuids::uuid::variant_type v = u.variant();
</pre>
<h4><a name="Version">Version</a></h4>
<p>Four bits of a <b>uuid</b> determine the variant, that is the mechanism
used to generate the <b>uuid</b>.
</p>
<pre>
boost::uuids::uuid u;
boost::uuids::uuid::version_type v = u.version();
</pre>
<h4><a name="Swap">Swap</a></h4>
<p>Both <tt>boost::uuids::uuid::swap()</tt> and <tt>boost::uuids::swap()</tt>
are provided.
</p>
<pre>
boost::uuids::uuid u1, u2;
u1.swap(u2);
swap(u1, u2);
</pre>
<h4><a name="Operators">Operators</a></h4>
<p>
All of the standard numeric operators are defined for the <b>uuid</b>
class. These include:
<pre>
operator==
operator!=
operator&lt;
operator&gt;
operator&lt;=
operator&gt;=
</pre>
<h4><a name="Hash">Hash Function</a></h4>
<p>
This function allows <b>uuid</b>s to be used with
<a href="http://www.boost.org/doc/html/hash.html"><b>boost::hash</b></a>
<pre>
boost::hash&lt;boost::uuids::uuid&gt; uuid_hasher;
std::size_t uuid_hash_value = uuid_hasher(boost::uuids::uuid());
</pre>
<h3><a name="boost/uuid/uuid_generators.hpp" href="../../../boost/uuid/uuid_generators.hpp">boost/uuid/uuid_generators.hpp</a></h3>
<h4><a name="Synopsis_generators">Synopsis</a></h4>
This file includes all the <b>uuid</b> generators for convenience.
<pre>
#include &lt;<a href="../../../boost/uuid/nil_generator.hpp"><tt>boost/uuid/nil_generator.hpp</tt></a>&gt;
#include &lt;<a href="../../../boost/uuid/string_generator.hpp"><tt>boost/uuid/string_generator.hpp</tt></a>&gt;
#include &lt;<a href="../../../boost/uuid/name_generator.hpp"><tt>boost/uuid/name_generator.hpp</tt></a>&gt;
#include &lt;<a href="../../../boost/uuid/random_generator.hpp"><tt>boost/uuid/random_generator.hpp</tt></a>&gt;
</pre>
<h3><a name="boost/uuid/nil_generator.hpp" href="../../../boost/uuid/nil_generator.hpp">boost/uuid/nil_generator.hpp</a></h3>
<h4><a name="Synopsis_nil_generator">Synopsis</a></h4>
<pre>
namespace boost {
namespace uuids {
struct nil_generator {
typedef uuid result_type;
uuid operator()() const;
};
uuid nil_uuid();
}} //namespace boost::uuids
</pre>
<h4><a name="Nil Generator">Nil Generator</a></h4>
<p>The <tt>boost::uuids::nil_generator</tt> class always generates a nil <b>uuid</b>.
<pre>
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);
</pre>
<h3><a name="boost/uuid/string_generator.hpp" href="../../../boost/uuid/string_generator.hpp">boost/uuid/string_generator.hpp</a></h3>
<h4><a name="Synopsis_string_generator">Synopsis</a></h4>
<pre>
namespace boost {
namespace uuids {
struct string_generator {
typedef uuid result_type;
template &lt;typename ch, typename char_traits, typename alloc&gt;
uuid operator()(std::basic_string&lt;ch, char_traits, alloc&gt; const&amp; s) const;
};
}} //namespace boost::uuids
</pre>
<h4><a name="String Generator">String Generator</a></h4>
<p>The <tt>boost::uuids::string_generator</tt> class generates a <b>uuid</b> from a string. In addition to the standards-defined string
format in <A HREF="https://www.ietf.org/rfc/rfc4122.txt">RFC 4122</A> (p. 3), the string generator accepts a few variants. Valid strings
match the following PCRE regular expression:
<pre>
^({)?([0-9a-fA-F]{8})(?<DASH>-)?([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{4})(?(DASH)-)([0-9a-fA-F]{12})(?(1)})$
</pre>
Or more generally, the following formats are accepted as valid string formats, where <tt>h</tt> is hexadecimal, without case sensitivity, and without any leading or trailing whitespace:
<pre>
hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh
{hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh}
hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
{hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh}
</pre>
For example:
<pre>
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"));
</pre>
Invalid input will generate a <tt>std::runtime_error</tt> exception.
<h3><a name="boost/uuid/name_generator.hpp" href="../../../boost/uuid/name_generator.hpp">boost/uuid/name_generator.hpp</a></h3>
<h4><a name="Synopsis_name_generator">Synopsis</a></h4>
<pre>
namespace boost {
namespace uuids {
template&lt;class NameHashProvider&gt;
class basic_name_generator {
public:
typedef uuid result_type;
explicit basic_name_generator(uuid const&amp; namespace_uuid);
uuid operator()(const char* name) const;
uuid operator()(const wchar_t* name) const;
tempate &lt;typename ch, typename char_traits, typename alloc&gt;
uuid operator()(std::basic_string&lt;ch, char_traits, alloc&gt; const&amp; name) const;
uuid operator()(void const* buffer, std::size_t byte_count) const;
};
typedef basic_name_generator&lt;detail::md5&gt; name_generator_md5;
typedef basic_name_generator&lt;detail::sha1&gt; name_generator_sha1;
typedef name_generator_sha1 name_generator; // deprecated
typedef name_generator_sha1 name_generator_latest;
}} //namespace boost::uuids
</pre>
<h4><a name="Name Generator">Name Generator</a></h4>
<p>
RFC 4122 specifies that a name-based <b>uuid</b> is derived from content in
a namespace. A <b>uuid</b> with identical content in an identical namespace shall
yield the same <b>uuid</b> as long as the same hasing algorithm is used.
<h5>Hashing Algorithms</h5>
RFC 4122 defines two hashing mechanisms for <b>uuid</b> generation:
<ul>
<li>MD5</li>
<li>SHA1</li>
</ul>
Since RFC 4122 was written, both of these hash algorithms have been rendered
insecure. In anticipation of a new RFC for <b>uuid</b> arriving,
<tt>name_generator</tt> has been deprecated, and replaced with:
<ul>
<li><tt>boost::uuids::name_generator_latest</tt></li>
<li><tt>boost::uuids::name_generator_md5</tt></li>
<li><tt>boost::uuids::name_generator_sha1</tt></li>
</ul>
<tt>name_generator</tt>, while deprecated, remains a type alias for
<tt>name_generator_sha1</tt> so the behavior is identical to previous
releases. When the successor to SHA1 is chosen,
it will be implemented under a new name similar to those above.
If your application does not rely on stable hashing over time, you can
use <tt>name_generator_latest</tt> to always use the latest hashing
algorithm available.
</p>
<p>Consumers are free to use their own hash provider as long as it satisfies the
<tt><A href="#Concept:NameHashProvider">NameHashProvider</A></tt> concept.
<h5>Namespaces</h5>
There are four well-known namespaces defined in
<A HREF="https://tools.ietf.org/html/rfc4122#appendix-C">RFC 4122, Appendix C</A> which
are defined as:
<pre>
boost::uuids::ns::dns() // == {6ba7b810-9dad-11d1-80b4-00c04fd430c8}
boost::uuids::ns::url() // == {6ba7b811-9dad-11d1-80b4-00c04fd430c8}
boost::uuids::ns::oid() // == {6ba7b812-9dad-11d1-80b4-00c04fd430c8}
boost::uuids::ns::x500dn() // == {6ba7b814-9dad-11d1-80b4-00c04fd430c8}
</pre>
of course, you are free to use your own namespace if you prefer. Here is an
example of name generator usage:
<pre>
boost::uuids::name_generator_sha1 gen(boost::uuids::ns::dns());
boost::uuids::uuid udoc = gen("boost.org");
std::cout << "boost.org uuid in dns namespace, sha1 version: " << udoc << std::endl;
</pre>
produces the output:
<pre>
boost.org uuid in dns namespace, sha1 version: 0043f363-bbb4-5369-840a-322df6ec1926
</pre>
<h3><a name="boost/uuid/random_generator.hpp" href="../../../boost/uuid/random_generator.hpp">boost/uuid/random_generator.hpp</a></h3>
<h4><a name="Synopsis_random_generator">Synopsis</a></h4>
<pre>
namespace boost {
namespace uuids {
class random_generator {
public:
typedef uuid result_type;
result_type operator()();
};
template &lt;typename UniformRandomNumberGenerator&gt;
class basic_random_generator {
public:
typedef uuid result_type;
basic_random_generator();
explicit basic_random_generator(UniformRandomNumberGenerator&amp; gen);
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
result_type operator()();
};
typedef basic_random_generator&lt;boost::mt19937&gt; random_generator_mt19937;
}} // namespace boost::uuids
</pre>
<h4><a name="Random Generator">Random Generator</a></h4>
<p>
<tt>boost::uuids::random_generator</tt> class generates uuids using
operating system provided entropy. For the majority of use cases this
should be sufficient, as this generator has very low startup overhead
when compared to a generator with seeding requirements.
</p>
<p>
<tt>boost::uuids::basic_random_generator</tt> class generates a random number
based uuid from a random number generator (one that conforms to the
<a href="http://www.boost.org/libs/random/random-concepts.html#uniform-rng">UniformRandomNumberGenerator</a>
concept). The default constructor will properly seed the random number generator
if it requires the behavior for proper operation. Additional constructors allow you
to provide your own <tt>UniformRandomNumberGenerator</tt> and you are responsible for
properly seeding it if necessary.
</p>
<p>
<tt>boost::uuids::random_generator_mt19937</tt> is a type definition for:
<tt>boost::uuids::basic_random_generator&lt;mt19937&gt;</tt> and is provided for
convenience.
</p>
<h5>Platforms</h5>
<p>
The following platforms are supported and entropy selection logic explained:
<ul>
<li>CloudABI</li>
<li>Unix
<ul>
<li>OpenBSD: use <a href="https://man.openbsd.org/arc4random.3"><tt>arc4random(3)</tt></a></li>
<li>Linux 3.17 or later: use <a href="http://man7.org/linux/man-pages/man2/getrandom.2.html"><tt>getrandom(2)</tt></a></li>
<li>Other systems with glibc 2.25 or later: use <tt>getentropy(3)</tt></li>
<li>All other cases: use <tt>/dev/urandom</tt></li>
</ul>
</li>
<li>Windows (UWP Compatible): use BCrypt if available, otherwise use Wincrypt
</ul>
</p>
<h5>Preprocessor Macros</h5>
<p>
<ul>
<li>
<tt>BOOST_UUID_RANDOM_PROVIDER_FORCE_POSIX</tt>: on Unix this will force the
selection of <tt>/dev/*random</tt> over <tt>getrandom(2)</tt> or <tt>getentropy(3)</tt>.
</li>
<li>
<tt>BOOST_UUID_RANDOM_PROVIDER_FORCE_WINCRYPT</tt>: on Windows this will force the
selection of Wincrypt over BCrypt.
</li>
<li>
<tt>BOOST_UUID_RANDOM_PROVIDER_NO_LIB</tt> (or <tt>BOOST_ALL_NO_LIB</tt>): disable Windows auto linking.
</li>
<li>
<tt>BOOST_UUID_RANDOM_PROVIDER_GETRANDOM_DISABLE_LIBC_WRAPPER</tt>: disable <tt>getrandom(2)</tt>
on Linux even if it's available.
</li>
</ul>
</p>
<h5>Performance</h5>
<p>
In most cases <tt>random_generator</tt> will be optimal. A benchmark can be found
in the tests (test_bench_random) that will determine the cutoff point where
<tt>random_generator_mt19937</tt> outperforms <tt>random_generator</tt> in wall time.
</p>
<p>
On Windows when using the wincrypt entropy provider, a measurable delay may occur the
first time a <tt>random_generator</tt> is constructed within a running instance. This
has been observed using <tt>test_bench_random</tt> and was so significant that the
benchmark was changed to throw out the first loop of measurements.
</p>
<h5>Exceptions</h5>
<p>
The exception <tt>boost::uuids::entropy_error</tt> is thrown if there is an error
getting entropy from the operating system.
</p>
<h5>Examples</h5>
<pre>
// Depending on the platform there may be a setup cost in
// initializing the generator so plan to reuse it if you can.
boost::uuids::random_generator gen;
boost::uuids::uuid id = gen();
std::cout << id << std::endl;
boost::uuids::uuid id2 = gen();
std::cout << id2 << std::endl;
assert(id != id2);
// You can still use a PseudoRandomNumberGenerator to create
// UUIDs, however this is not the preferred mechanism.
boost::uuids::random_generator_mt19937 bulkgen;
for (size_t i = 0; i < 1000; ++i)
{
boost::uuids::uuid u = bulkgen();
// do something with u
boost::ignore_unused(u);
}
</pre>
<h3><a name="boost/uuid/uuid_io.hpp" href="../../../boost/uuid/uuid_io.hpp">boost/uuid/uuid_io.hpp</a></h3>
<h4><a name="Synopsis_io">Synopsis</a></h4>
<pre>
namespace boost {
namespace uuids {
template &lt;typename ch, typename char_traits&gt;
std::basic_ostream&lt;ch, char_traits&gt;&amp; operator&lt;&lt;(std::basic_ostream&lt;ch, char_traits&gt; &amp;os, uuid const&amp; u);
template &lt;typename ch, typename char_traits&gt;
std::basic_istream&lt;ch, char_traits&gt;&amp; operator&gt;&gt;(std::basic_istream&lt;ch, char_traits&gt; &amp;is, uuid &amp;u);
template&lt;class OutputIterator&gt;
OutputIterator to_chars(uuid const&amp; u, OutputIterator out);
bool to_chars(uuid const&amp; u, char* first, char* last);
std::string to_string(uuid const&amp; u);
std::wstring to_wstring(uuid const&amp; u);
}} // namespace boost::uuids
</pre>
<h4><a name="Stream_operators">Stream Operators</a></h4>
<p>
The standard input and output stream operators <tt>&lt;&lt;</tt> and <tt>&gt;&gt;</tt>
are provided by including <a href="../../../boost/uuid/uuid_io.hpp"><tt>boost/uuid/uuid_io.hpp</tt></a>.
The string representation of a <b>uuid</b> is <tt>hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh</tt>
where <tt>h</tt> is hexadecimal.
<pre>
boost::uuids::uuid u1; // initialize uuid
std::stringstream ss;
ss &lt;&lt; u1;
boost::uuids::uuid u2;
ss &gt;&gt; u2;
assert(u1, u2);
</pre>
<p>
One can also use <a href="http://www.boost.org/libs/conversion/lexical_cast.htm"><tt>boost::lexical_cast</tt></a>.
<pre>
boost::uuids::uuid u1; // initialize uuid
std::string s = boost::lexical_cast&lt;std::string&gt;(u);
boost::uuids::uuid u2 = boost::lexical_cast&lt;boost::uuids::uuid&gt;(s);
assert(u1 == u2);
</pre>
<h4><a name="to_chars">To Chars</a></h4>
<p>
The function <tt>to_chars</tt> is a fast non-allocating (and non-throwing if the
iterator does not throw) function to write a <b>uuid</b> to a string buffer.
It writes exactly 36 characters to the iterator on success (not null-terminated).
<pre>
boost::uuids::uuid u; // initialize uuid
char buf[36];
boost::uuids::to_chars(u, buf);
// OR
bool ret = boost::uuids::to_chars(u, std::begin(buf), std::end(buf));
assert(ret);
</pre>
<h4><a name="to_string">To String</a></h4>
<p>
The functions <tt>to_string</tt> and <tt>to_wstring</tt> are provided as a
convenience to convert a <b>uuid</b> to a string. They are also likely faster than
the stream operators or using <a href="http://www.boost.org/libs/conversion/lexical_cast.htm"><tt>boost::lexical_cast</tt></a>.
<pre>
boost::uuids::uuid u; // initialize uuid
std::string s1 = to_string(u);
std::wstring s2 = to_wstring(u);
</pre>
<h3><a name="boost/uuid/uuid_serialize.hpp" href="../../../boost/uuid/uuid_serialize.hpp">boost/uuid/uuid_serialize.hpp</a></h3>
<h4><a name="Synopsis_serialize">Synopsis</a></h4>
<pre>
namespace boost {
namespace uuids {
BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
}} // namespace boost::uuids
</pre>
<h4><a name="Serialization">Serialization</a></h4>
<p>
Serialization is accomplished with the <a href="http://www.boost.org/libs/serialization/doc/index.html">
Boost Serialization</a> library. A <b>uuid</b> is serialized as a
<a href="http://www.boost.org/libs/serialization/doc/serialization.html#primitiveoperators">
primitive type</a>, thus only the <b>uuid</b> value will be saved to/loaded from an archive.
<p>
Include <a href="../../../boost/uuid/uuid_serialize.hpp"><tt>boost/uuid/uuid_serialize.hpp</tt></a> to enable serialization for <b>uuid</b>s.
<h2><A name="Concepts">Concepts</a></h2>
This section describes all of the concepts defined by the library.
<h3><a name="Concept:NameHashProvider">NameHashProvider</a></h3>
A NameHashProvder type is supplied as a template argument to the <tt>basic_name_generator</tt> class. It provides
the hashing function that the name generator uses to generate a <b>uuid</b>.
<h4>Requirements</h4>
In this table, <i>G</i> is a type meeting the requirements of NameHashProvider:
<p><center><table width="85%" summary="Valid expressions">
<thead>
<tr bgcolor="lightgray">
<th>Expression</th>
<th>Semantics, Pre/Post-conditions</th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>typedef G::digest_type</tt></td>
<td>A type definition of contiguous raw storage at least 16 bytes in length.</td>
</tr>
<tr>
<td><tt>void G::process_byte(unsigned char)</tt></td>
<td></td>
</tr>
<tr>
<td><tt>void G::process_bytes(void const*, std::size_t)</tt></td>
<td></td>
</tr>
<tr>
<td><tt>void G::get_digest(typename G::digest_type&amp;)</tt></td>
<td>Copies the digest into the supplied parameter. Called once.</td>
</tr>
<tr>
<td><tt>unsigned char G::get_version() const</tt></td>
<td>Returns the RFC 4122 version for the hashing algorithm (4 bits) in 0x07.</td>
</tr>
</tbody>
</table>
</center></p>
<h2><a name="Design notes">Design notes</a></h2>
<p>
The document, <a href="http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf">
http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf</a>, was used to design
and implement the <b>boost::uuids::uuid</b> struct.
<p>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.
<h2><a name="History and Acknowledgements">History and Acknowledgements</a></h2>
<p>
A number of people on the <a href="http://www.boost.org/">boost.org</a>
mailing list provided useful comments and greatly helped to shape the library.
<p>Revised November 8, 2017</p>
<hr>
<p>© Copyright Andy Tompkins, 2006</p>
<p>© Copyright 2017 James E. King III</p>
<p> Distributed under the Boost Software
License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="https://www.boost.org/LICENSE_1_0.txt">
www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

6
doc/uuid/acknowledgements.adoc Normal file
View File

@@ -0,0 +1,6 @@
[#acknowledgements]
== Acknowledgements
:idprefix: acknowledgements_
A number of people on the https://www.boost.org/[boost.org] mailing list provided useful comments and greatly helped to shape the library.

34
doc/uuid/concepts.adoc Normal file
View File

@@ -0,0 +1,34 @@
[#concepts]
== Concepts
:idprefix: concepts_
This section describes all of the concepts defined by the library.
=== NameHashProvider
A NameHashProvder type is supplied as a template argument to the `basic_name_generator` class. It provides the hashing function that the name generator uses to generate a *uuid*.
==== Requirements
In this table, G is a type meeting the requirements of NameHashProvider:
[%autowidth]
|===
|Expression |Semantics, Pre/Post-conditions
|`typedef G::digest_type`
|A type definition of contiguous raw storage at least 16 bytes in length.
|`void G::process_byte(unsigned char)`
|
|`void G::process_bytes(void const*, std::size_t)`
|
|`void G::get_digest(typename G::digest_type&)`
|Copies the digest into the supplied parameter. Called once.
unsigned char G::get_version() const Returns the RFC 4122 version for the hashing algorithm (4 bits) in 0x07.
|===

28
doc/uuid/configuration.adoc Normal file
View File

@@ -0,0 +1,28 @@
[#configuration]
= Configuration
:idprefix: configuration_
:cpp: C++
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. These macros are summarized in the following table.
[%autowidth]
|===
|Macro |Description
|`BOOST_UUID_NO_SIMD`
|If defined, disables any optimizations for http://en.wikipedia.org/wiki/SIMD[SIMD]-enabled processors. Generic versions of algorithms will be used instead. This may result in suboptimal performance. By default, optimized algorithms are used, when the library is able to detect the availability of SIMD extensions at compile time.
|`BOOST_UUID_USE_SSE2`
|If defined, enables optimizations for http://en.wikipedia.org/wiki/SSE2[SSE2] exstensions available in modern x86 processors.
|`BOOST_UUID_USE_SSE3`
|If defined, enables optimizations for http://en.wikipedia.org/wiki/SSE3[SSE3] exstensions available in modern x86 processors.
|`BOOST_UUID_USE_SSE41`
|If defined, enables optimizations for http://en.wikipedia.org/wiki/SSE4#SSE4.1[SSE4.1] exstensions available in modern x86 processors.
|===
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*` 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.

10
doc/uuid/copyright.adoc Normal file
View File

@@ -0,0 +1,10 @@
[#copyright]
= Copyright and License
:idprefix: copyright_
Copyright (C) 2006 Andy Tompkins
Copyright (C) 2017 James E. King III
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

8
doc/uuid/design_notes.adoc Normal file
View File

@@ -0,0 +1,8 @@
[#design_notes]
== Design Notes
:idprefix: 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.
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.

137
doc/uuid/examples.adoc Normal file
View File

@@ -0,0 +1,137 @@
[#examples]
= Examples
:idprefix: examples_
:cpp: C++
== Tagging
[source,c++]
----
// example of tagging an object with a uuid
// see boost/libs/uuid/test/test_tagging.cpp
#include <boost/uuid/uuid.hpp>
#include <boost/uuid/uuid_generators.hpp>
class object
{
public:
object()
: tag(boost::uuids::random_generator()())
, state(0)
{}
explicit object(int state)
: tag(boost::uuids::random_generator()())
, state(state)
{}
object(object const& rhs)
: tag(rhs.tag)
, state(rhs.state)
{}
bool operator==(object const& rhs) const {
return tag == rhs.tag;
}
object& operator=(object const& rhs) {
tag = rhs.tag;
state = rhs.state;
}
int get_state() const { return state; }
void set_state(int new_state) { state = new_state; }
private:
boost::uuids::uuid tag;
int state;
};
object o1(1);
object o2 = o1;
o2.set_state(2);
assert(o1 == o2);
object o3(3);
assert(o1 != o3);
assert(o2 != o3);
----
== POD Efficiencies
This library implements a UUID as a POD allowing a UUID to be used in the most efficient ways, including using memcpy, and aggregate initializers. A drawback is that a POD can not have any constructors, and thus declaring a UUID will not initialize it to a value generated by one of the defined mechanisms. But a class based on a UUID can be defined that does initialize itself to a value generated by one of the defined mechanisms.
Note that `boost::is_pod` is specialized for `boost::uuids::uuid` and depends on https://www.boost.org/libs/type_traits[Boost.TypeTraits]. Define `BOOST_UUID_NO_TYPE_TRAITS` before including `boost/uuid/uuid.hpp` to remove the dependency on Boost.TypeTraits.
[source,c++]
----
// example using memcpy and aggregate initializers
// example of a class uuid see boost/libs/uuid/test/test_uuid_class.cpp
#include <boost/uuid/uuid.hpp>
#include <boost/uuid/uuid_generators.hpp>
{ // example using memcpy
unsigned char uuid_data[16];
// fill uuid_data
boost::uuids::uuid u;
memcpy(&u, uuid_data, 16);
}
{ // example using aggregate initializers
boost::uuids::uuid u =
{ 0x12 ,0x34, 0x56, 0x78
, 0x90, 0xab
, 0xcd, 0xef
, 0x12, 0x34
, 0x56, 0x78, 0x90, 0xab, 0xcd, 0xef
};
}
// example of creating a uuid class that
// initializes the uuid in the constructor
// using a defined mechanism
class uuid_class : public boost::uuids::uuid
{
public:
uuid_class()
: boost::uuids::uuid(boost::uuids::random_generator()())
{}
explicit uuid_class(boost::uuids::uuid const& u)
: boost::uuids::uuid(u)
{}
operator boost::uuids::uuid() {
return static_cast<boost::uuids::uuid&>(*this);
}
operator boost::uuids::uuid() const {
return static_cast<boost::uuids::uuid const&>(*this);
}
};
uuid_class u1;
uuid_class u2;
assert(u1 != u2);
----
== Byte Extraction
It is sometimes useful to get at the 16 bytes of a *uuid* directly. Typical use is as follows:
[source,c++]
----
boost::uuids::uuid u;
std::vector<uint8_t> v(u.size());
std::copy(u.begin(), u.end(), v.begin());
----
Note: `boost::uuids::uuid::size()` always returns 16.

15
doc/uuid/introduction.adoc Normal file
View File

@@ -0,0 +1,15 @@
[#introduction]
= Introduction
:idprefix: introduction_
:cpp: C++
A UUID, or Universally unique identifier, is intended to uniquely identify information in a distributed environment without significant central coordination. It can be used to tag objects with very short lifetimes, or to reliably identify very persistent objects across a network.
A formal definition for UUID can be found in https://www.ietf.org/rfc/rfc4122.txt[RFC 4122].
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).

82
doc/uuid/name_generator.adoc Normal file
View File

@@ -0,0 +1,82 @@
[#name_generator]
== boost/uuid/name_generator.hpp
:idprefix: name_generator_
=== Synopsis
[source,c++]
----
// #include <boost/uuid/name_generator.hpp>
namespace boost {
namespace uuids {
template<class NameHashProvider>
class basic_name_generator {
public:
typedef uuid result_type;
explicit basic_name_generator(uuid const& namespace_uuid);
uuid operator()(const char* name) const;
uuid operator()(const wchar_t* name) const;
tempate <typename ch, typename char_traits, typename alloc>
uuid operator()(std::basic_string<ch, char_traits, alloc> const& name) const;
uuid operator()(void const* buffer, std::size_t byte_count) const;
};
typedef basic_name_generator<detail::md5> name_generator_md5;
typedef basic_name_generator<detail::sha1> name_generator_sha1;
typedef name_generator_sha1 name_generator; // deprecated
typedef name_generator_sha1 name_generator_latest;
}} //namespace boost::uuids
----
=== Name Generator
RFC 4122 specifies that a name-based *uuid* is derived from content in a namespace. A *uuid* with identical content in an identical namespace shall yield the same *uuid* as long as the same hasing algorithm is used.
==== Hashing Algorithms
RFC 4122 defines two hashing mechanisms for *uuid* generation:
* MD5
* SHA1
Since RFC 4122 was written, both of these hash algorithms have been rendered insecure. In anticipation of a new RFC for *uuid* arriving, `name_generator` has been deprecated, and replaced with:
* `boost::uuids::name_generator_latest`
* `boost::uuids::name_generator_md5`
* `boost::uuids::name_generator_sha1`
`name_generator`, while deprecated, remains a type alias for `name_generator_sha1` so the behavior is identical to previous releases. When the successor to SHA1 is chosen, it will be implemented under a new name similar to those above. If your application does not rely on stable hashing over time, you can use `name_generator_latest` to always use the latest hashing algorithm available.
// todo: cross reference this
Consumers are free to use their own hash provider as long as it satisfies the <<NameHashProvider>> concept.
==== Namespaces
There are four well-known namespaces defined in RFC https://tools.ietf.org/html/rfc4122#appendix-C[4122, Appendix C] which are defined as:
```c++
boost::uuids::ns::dns() // == {6ba7b810-9dad-11d1-80b4-00c04fd430c8}
boost::uuids::ns::url() // == {6ba7b811-9dad-11d1-80b4-00c04fd430c8}
boost::uuids::ns::oid() // == {6ba7b812-9dad-11d1-80b4-00c04fd430c8}
boost::uuids::ns::x500dn() // == {6ba7b814-9dad-11d1-80b4-00c04fd430c8}
```
Of course, you are free to use your own namespace if you prefer. Here is an example of name generator usage:
```c++
boost::uuids::name_generator_sha1 gen(boost::uuids::ns::dns());
boost::uuids::uuid udoc = gen("boost.org");
std::cout << "boost.org uuid in dns namespace, sha1 version: " << udoc << std::endl;
```
produces the output:
```txt
boost.org uuid in dns namespace, sha1 version: 0043f363-bbb4-5369-840a-322df6ec1926
```

37
doc/uuid/nil_generator.adoc Normal file
View File

@@ -0,0 +1,37 @@
[#nil_generator]
== boost/uuid/nil_generator.hpp
:idprefix: nil_generator_
=== Synopsis
[source,c++]
----
// #include <boost/uuid/nil_generator.hpp>
namespace boost {
namespace uuids {
struct nil_generator {
typedef uuid result_type;
uuid operator()() const;
};
uuid nil_uuid();
}} //namespace boost::uuids
----
=== Nil Generator
The `boost::uuids::nil_generator` class always generates a nil *uuid*.
```c++
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);
```

96
doc/uuid/random_generator.adoc Normal file
View File

@@ -0,0 +1,96 @@
[#random_generator]
== boost/uuid/random_generator.hpp
:idprefix: random_generator_
=== Synopsis
[source,c++]
----
// #include <boost/uuid/random_generator.hpp>
namespace boost {
namespace uuids {
class random_generator {
public:
typedef uuid result_type;
result_type operator()();
};
template <typename UniformRandomNumberGenerator>
class basic_random_generator {
public:
typedef uuid result_type;
basic_random_generator();
explicit basic_random_generator(UniformRandomNumberGenerator& gen);
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
result_type operator()();
};
typedef basic_random_generator<boost::mt19937> random_generator_mt19937;
}} // namespace boost::uuids
----
=== Random Generator
`boost::uuids::random_generator` class generates uuids using operating system provided entropy. For the majority of use cases this should be sufficient, as this generator has very low startup overhead when compared to a generator with seeding requirements.
`boost::uuids::basic_random_generator` class generates a random number based uuid from a random number generator (one that conforms to the https://www.boost.org/libs/random/random-concepts.html#uniform-rng[UniformRandomNumberGenerator] concept). The default constructor will properly seed the random number generator if it requires the behavior for proper operation. Additional constructors allow you to provide your own `UniformRandomNumberGenerator` and you are responsible for properly seeding it if necessary.
`boost::uuids::random_generator_mt19937` is a type definition for: `boost::uuids::basic_random_generator<mt19937>` and is provided for convenience.
==== Platforms
The following platforms are supported and entropy selection logic explained:
* CloudABI
* Unix
** OpenBSD: use https://man.openbsd.org/arc4random.3[arc4random(3)]
** Linux 3.17 or later: use http://man7.org/linux/man-pages/man2/getrandom.2.html[getrandom(2)]
** Other systems with glibc 2.25 or later: use https://www.man7.org/linux/man-pages/man3/getentropy.3.html[getentropy(3)]
** All other cases: use `/dev/urandom`
* Windows (UWP Compatible): use BCrypt if available, otherwise use Wincrypt
==== Preprocessor Macros
* `BOOST_UUID_RANDOM_PROVIDER_FORCE_POSIX`: on Unix this will force the selection of `/dev/*random` over `getrandom(2)` or `getentropy(3)`.
* `BOOST_UUID_RANDOM_PROVIDER_FORCE_WINCRYPT`: on Windows this will force the selection of Wincrypt over BCrypt.
* `BOOST_UUID_RANDOM_PROVIDER_NO_LIB` (or `BOOST_ALL_NO_LIB`): disable Windows auto linking.
* `BOOST_UUID_RANDOM_PROVIDER_GETRANDOM_DISABLE_LIBC_WRAPPER`: disable `getrandom(2)` on Linux even if it's available.
==== Performance
In most cases `random_generator` will be optimal. A benchmark can be found in the tests (`test_bench_random`) that will determine the cutoff point where `random_generator_mt19937` outperforms `random_generator` in wall time.
On Windows when using the wincrypt entropy provider, a measurable delay may occur the first time a `random_generator` is constructed within a running instance. This has been observed using `test_bench_random` and was so significant that the benchmark was changed to throw out the first loop of measurements.
==== Exceptions
The exception `boost::uuids::entropy_error` is thrown if there is an error getting entropy from the operating system.
==== Examples
```c++
// Depending on the platform there may be a setup cost in
// initializing the generator so plan to reuse it if you can.
boost::uuids::random_generator gen;
boost::uuids::uuid id = gen();
std::cout << id << std::endl;
boost::uuids::uuid id2 = gen();
std::cout << id2 << std::endl;
assert(id != id2);
// You can still use a PseudoRandomNumberGenerator to create
// UUIDs, however this is not the preferred mechanism.
boost::uuids::random_generator_mt19937 bulkgen;
for (size_t i = 0; i < 1000; ++i)
{
boost::uuids::uuid u = bulkgen();
// do something with u
boost::ignore_unused(u);
}
```

11
doc/uuid/reference.adoc Normal file
View File

@@ -0,0 +1,11 @@
[#reference]
= Reference
include::uuid.adoc[]
include::uuid_generators.adoc[]
include::nil_generator.adoc[]
include::string_generator.adoc[]
include::name_generator.adoc[]
include::random_generator.adoc[]
include::uuid_io.adoc[]
include::uuid_serialize.adoc[]

52
doc/uuid/string_generator.adoc Normal file
View File

@@ -0,0 +1,52 @@
[#string_generator]
== boost/uuid/string_generator.hpp
:idprefix: string_generator_
=== Synopsis
[source,c++]
----
// #include <boost/uuid/string_generator.hpp>
namespace boost {
namespace uuids {
struct string_generator {
typedef uuid result_type;
template <typename ch, typename char_traits, typename alloc>
uuid operator()(std::basic_string<ch, char_traits, alloc> const& s) const;
};
}} //namespace boost::uuids
----
=== String Generator
The `boost::uuids::string_generator` class generates a *uuid* from a string. In addition to the standards-defined string format in https://www.ietf.org/rfc/rfc4122.txt[RFC 4122] (p. 3), the string generator accepts a few variants. Valid strings match the following PCRE regular expression:
```txt
^({)?([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}
```
For example:
```c++
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"));
```
Invalid input will generate a `std::runtime_error` exception.

154
doc/uuid/uuid.adoc Normal file
View File

@@ -0,0 +1,154 @@
[#uuid]
== boost/uuid/uuid.hpp
:idprefix: uuid_
=== Synopsis
[source,c++]
----
// #include <boost/uuid/uuid.hpp>
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;
static constexpr size_type static_size() noexcept;
// iteration
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
constexpr size_type size() const noexcept;
bool is_nil() 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;
void swap(uuid& lhs, uuid& rhs) noexcept;
std::size_t hash_value(uuid const& u) 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.
```c++
boost::uuids::uuid u;
assert(16 == u.size());
assert(16 == boost::uuids::uuid::static_size());
```
=== Iteration
Both iterators and constant iterators are provided.
```c++
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
Three bits of a *uuid* determine the variant.
```c++
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*.
```c++
boost::uuids::uuid u;
boost::uuids::uuid::version_type v = u.version();
```
=== Swap
Both `boost::uuids::uuid::swap()` and `boost::uuids::swap()` are provided.
```c++
boost::uuids::uuid u1, u2;
u1.swap(u2);
swap(u1, u2);
```
=== Operators
All of the standard numeric operators are defined for the *uuid* class. These include:
```c++
operator==
operator!=
operator<
operator>
operator<=
operator>=
```
=== Hash Function
This function allows **uuid**s to be used with https://www.boost.org/doc/libs/release/libs/container_hash/doc/html/hash.html#ref_boostcontainer_hashhash_hpp[boost::hash].
```c++
boost::hash<boost::uuids::uuid> uuid_hasher;
std::size_t uuid_hash_value = uuid_hasher(boost::uuids::uuid());
```

19
doc/uuid/uuid_generators.adoc Normal file
View File

@@ -0,0 +1,19 @@
[#uuid_generators]
== boost/uuid/uuid_generators.hpp
:idprefix: uuid_generators_
=== Synopsis
This file includes all the uuid generators for convenience.
[source,c++]
----
// #include <boost/uuid/uuid_generators.hpp>
#include <boost/uuid/nil_generator.hpp>
#include <boost/uuid/string_generator.hpp>
#include <boost/uuid/name_generator.hpp>
#include <boost/uuid/random_generator.hpp>
----

83
doc/uuid/uuid_io.adoc Normal file
View File

@@ -0,0 +1,83 @@
[#uuid_io]
== boost/uuid/uuid_io.hpp
:idprefix: uuid_io_
=== Synopsis
[source,c++]
----
// #include <boost/uuid/uuid_io.hpp>
namespace boost {
namespace uuids {
template <typename ch, typename char_traits>
std::basic_ostream<ch, char_traits>& operator<<(std::basic_ostream<ch, char_traits> &os, uuid const& u);
template <typename ch, typename char_traits>
std::basic_istream<ch, char_traits>& operator>>(std::basic_istream<ch, char_traits> &is, uuid &u);
template<class OutputIterator>
OutputIterator to_chars(uuid const& u, OutputIterator out);
bool to_chars(uuid const& u, char* first, char* last);
std::string to_string(uuid const& u);
std::wstring to_wstring(uuid const& u);
}} // 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 hexadecimal.
```c++
boost::uuids::uuid u1; // initialize uuid
std::stringstream ss;
ss << u1;
boost::uuids::uuid u2;
ss >> u2;
assert(u1, u2);
```
One can also use https://www.boost.org/doc/libs/release/doc/html/boost_lexical_cast/synopsis.html[boost::lexical_cast].
```c++
boost::uuids::uuid u1; // initialize uuid
std::string s = boost::lexical_cast<std::string>(u);
boost::uuids::uuid u2 = boost::lexical_cast<boost::uuids::uuid>(s);
assert(u1 == u2);
```
=== To Chars
The function `to_chars` is a fast non-allocating (and non-throwing if the iterator does not throw) function to write a *uuid* to a string buffer. It writes exactly 36 characters to the iterator on success (not null-terminated).
```c++
boost::uuids::uuid u; // initialize uuid
char buf[36];
boost::uuids::to_chars(u, buf);
// OR
bool ret = boost::uuids::to_chars(u, std::begin(buf), std::end(buf));
assert(ret);
```
=== 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 https://www.boost.org/doc/libs/release/doc/html/boost_lexical_cast/synopsis.html[boost::lexical_cast].
```c++
boost::uuids::uuid u; // initialize uuid
std::string s1 = to_string(u);
std::wstring s2 = to_wstring(u);
```

24
doc/uuid/uuid_serialize.adoc Normal file
View File

@@ -0,0 +1,24 @@
[#uuid_serialize]
== boost/uuid/uuid_serialize.hpp
:idprefix: uuid_serialize_
=== Synopsis
[source,c++]
----
// #include <boost/uuid/uuid_serialize.hpp>
namespace boost {
namespace uuids {
BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
}} // namespace boost::uuids
----
=== Serialization
Serialization is accomplished with the https://www.boost.org/libs/serialization/doc/index.html[Boost Serialization] library. A *uuid* is serialized as a https://www.boost.org/libs/serialization/doc/serialization.html#primitiveoperators[primitive type], thus only the *uuid* value will be saved to/loaded from an archive.
Include `boost/uuid/uuid_serialize.hpp` to enable serialization for **uuid**s.