ceph/src/boost/libs/uuid/uuid.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   4 <title>Uuid Library</title>
   5 <style type="text/css">
   6     pre { margin: 1em; padding: 1em; border: 1px solid #ddd; }
   7 </style>
   8 </head>
   9 <body>
  10 <h1><img src="../../boost.png" alt="Boost" WIDTH="277" HEIGHT="86">Uuid</h1>
  11
  12 <h2><a name="Contents">Contents</a></h2>
  13
  14 <ol>
  15     <li><a href="#Introduction">Introduction</a></li>
  16     <li><a href="#Configuration">Configuration</a></li>
  17     <li><a href="#Examples">Examples</a></li>
  18     <ul>
  19         <li><a href="#Tagging">Tagging</a></li>
  20         <li><a href="#POD Efficiencies">POD Efficiencies</a></li>
  21         <li><a href="#Byte Extraction">Byte Extraction</a></li>
  22     </ul
  23     <li><a href="#Reference">Reference</a></li>
  24     <ul>
  25         <li><a href="#boost/uuid/uuid.hpp">boost/uuid/uuid.hpp</a></li>
  26         <ul>
  27             <li><a href="#Synopsis">Synopsis</a></li>
  28             <li><a href="#Size">Size</a></li>
  29             <li><a href="#Iteration">Iteration</a></li>
  30             <li><a href="#Nil">Nil uuid</a></li>
  31             <li><a href="#Variant">Variant</a></li>
  32             <li><a href="#Version">Version</a></li>
  33             <li><a href="#Swap">Swap</a></li>
  34             <li><a href="#Operators">Operators</a></li>
  35             <li><a href="#Hash">Hash</a></li>
  36         </ul>
  37         <li><a href="#boost/uuid/uuid_generators.hpp">boost/uuid/uuid_generators.hpp</a></li>
  38         <ul>
  39             <li><a href="#Synopsis_generators">Synopsis</a></li>
  40         </ul>
  41         <li><a href="#boost/uuid/nil_generator.hpp">boost/uuid/nil_generator.hpp</a></li>
  42         <ul>
  43             <li><a href="#Synopsis_nil_generator">Synopsis</a></li>
  44             <li><a href="#Nil Generator">Nil Generator</a></li>
  45         </ul>
  46         <li><a href="#boost/uuid/string_generator.hpp">boost/uuid/string_generator.hpp</a></li>
  47         <ul>
  48             <li><a href="#Synopsis_string_generator">Synopsis</a></li>
  49             <li><a href="#String Generator">String Generator</a></li>
  50         </ul>
  51         <li><a href="#boost/uuid/name_generator.hpp">boost/uuid/name_generator.hpp</a></li>
  52         <ul>
  53             <li><a href="#Synopsis_name_generator">Synopsis</a></li>
  54             <li><a href="#Name Generator">Name Generator</a></li>
  55         </ul>
  56         <li><a href="#boost/uuid/random_generator.hpp">boost/uuid/random_generator.hpp</a></li>
  57         <ul>
  58             <li><a href="#Synopsis_random_generator">Synopsis</a></li>
  59             <li><a href="#Random Generator">Random Generator</a></li>
  60         </ul>
  61         <li><a href="#boost/uuid/uuid_io.hpp">boost/uuid/uuid_io.hpp</a></li>
  62         <ul>
  63             <li><a href="#Synopsis_io">Synopsis</a></li>
  64             <li><a href="#Stream_operators">Stream Operators</a></li>
  65             <li><a href="#to_string">To String</a></li>
  66         </ul>
  67         <li><a href="#boost/uuid/uuid_serialize.hpp">boost/uuid/uuid_serialize.hpp</a></li>
  68         <ul>
  69             <li><a href="#Synopsis_serialize">Synopsis</a></li>
  70             <li><a href="#Serialization">Serialization</a></li>
  71         </ul>
  72     </ul>
  73     <li><a href="#Design notes">Design notes</a></li>
  74     <li><a href="#History and Acknowledgements">History and Acknowledgements</a></li>
  75 </ol>
  76
  77 <h2><a name="Introduction">Introduction</a></h2>
  78 <p>
  79 A UUID, or Universally unique identifier, is intended to uniquely identify
  80 information in a distributed environment without significant central
  81 coordination.  It can be used to tag objects with very short lifetimes, or
  82 to reliably identify very persistent objects across a network.
  83 <p>
  84 UUIDs have many applications.  Some examples follow:  Databases may use UUIDs
  85 to identify rows or records in order to ensure that they are unique across
  86 different databases, or for publication/subscription services.  Network messages
  87 may be identified with a UUID to ensure that different parts of a message are put
  88 back together again.  Distributed computing may use UUIDs to identify a remote
  89 procedure call.  Transactions and classes involved in serialization may be
  90 identified by UUIDs.  Microsoft's component object model (COM) uses UUIDs to
  91 distinguish different software component interfaces.  UUIDs are inserted into
  92 documents from Microsoft Office programs.  UUIDs identify audio or
  93 video streams in the Advanced Systems Format (ASF).  UUIDs are also a basis
  94 for OIDs (object identifiers), and URNs (uniform resource name).
  95
  96 <p>
  97 An attractive feature of UUIDs when compared to alternatives is their relative
  98 small size, of 128-bits, or 16-bytes.  Another is that the creation of UUIDs
  99 does not require a centralized authority.
 100
 101 <p>When UUIDs are generated by one of the defined
 102 mechanisms, they are either guaranteed to be unique, different from all other
 103 generated UUIDs (that is, it has never been generated before and it will
 104 never be generated again), or it is extremely likely to be unique (depending
 105 on the mechanism).
 106
 107 <h2><a name="Configuration">Configuration</a></h2>
 108
 109 <p>
 110 The library does not require building or any special configuration to be used.
 111 However, there are a few options that can be enabled by defining macros prior to
 112 including library headers. These macros are summarized in the following table.
 113
 114 <p>
 115 <table border="1">
 116 <tr>
 117 <th>Macro</th><th>Description</th>
 118 </tr>
 119 <tr>
 120 <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>
 121 </tr>
 122 <tr>
 123 <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>
 124 </tr>
 125 <tr>
 126 <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>
 127 </tr>
 128 <tr>
 129 <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>
 130 </tr>
 131 </table>
 132
 133 <p>
 134 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.
 135
 136 <h2><a name="Examples">Examples</a></h2>
 137 <h3><a name="Tagging">Tagging</a></h3>
 138 <pre>
 139 // example of tagging an object with a uuid
 140 // see <a href="./test/test_tagging.cpp"><tt>boost/libs/uuid/test/test_tagging.cpp</tt></a>
 141
 142 #include &lt;<a href="./../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>&gt;
 143 #include &lt;<a href="./../../boost/uuid/uuid_generators.hpp"><tt>boost/uuid/uuid_generators.hpp</tt></a>&gt;
 144
 145 class object
 146 {
 147 public:
 148     object()
 149         : tag(boost::uuids::random_generator()())
 150         , state(0)
 151     {}
 152
 153     explicit object(int state)
 154         : tag(boost::uuids::random_generator()())
 155         , state(state)
 156     {}
 157
 158     object(object const&amp; rhs)
 159         : tag(rhs.tag)
 160         , state(rhs.state)
 161     {}
 162
 163     bool operator==(object const&amp; rhs) const {
 164         return tag == rhs.tag;
 165     }
 166
 167     object&amp; operator=(object const&amp; rhs) {
 168         tag = rhs.tag;
 169         state = rhs.state;
 170     }
 171
 172     int get_state() const { return state; }
 173     void set_state(int new_state) { state = new_state; }
 174
 175 private:
 176     boost::uuids::uuid tag;
 177
 178     int state;
 179 };
 180
 181 object o1(1);
 182 object o2 = o1;
 183 o2.set_state(2);
 184 assert(o1 == o2);
 185
 186 object o3(3);
 187 assert(o1 != o3);
 188 assert(o2 != o3);
 189 </pre>
 190
 191 <h3><a name="POD Efficiencies">POD Efficiencies</a></h3>
 192 <p>
 193 This library implements a UUID as a POD allowing a UUID
 194 to be used in the most efficient ways, including using memcpy,
 195 and aggregate initializers.  A drawback is that a POD can
 196 not have any constructors, and thus declaring a UUID will not
 197 initialize it to a value generated by one of the defined
 198 mechanisms.  But a class based on a UUID can be defined
 199 that does initialize itself to a value generated by one of
 200 the defined mechanisms.
 201 <p>
 202 Note that <tt>boost::is_pod</tt> is specialized for <tt>boost::uuids::uuid</tt>
 203 and depends on <a href="http://www.boost.org/libs/type_traits">Boost.TypeTraits</a>.
 204 Define <tt>BOOST_UUID_NO_TYPE_TRAITS</tt> before including <a href="./../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>
 205 to remove the dependency on <a href="http://www.boost.org/libs/type_traits">Boost.TypeTraits</a>.
 206 <pre>
 207 // example using memcpy and aggregate initializers
 208 // example of a class uuid see <a href="./test/test_uuid_class.cpp"><tt>boost/libs/uuid/test/test_uuid_class.cpp</tt></a>
 209
 210 #include &lt;<a href="./../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>&gt;
 211 #include &lt;<a href="./../../boost/uuid/uuid_generators.hpp"><tt>boost/uuid/uuid_generators.hpp</tt></a>&gt;
 212
 213 { // example using memcpy
 214     unsigned char uuid_data[16];
 215     // fill uuid_data
 216
 217     boost::uuids::uuid u;
 218
 219     memcpy(&amp;u, uuid_data, 16);
 220 }
 221
 222 { // example using aggregate initializers
 223     boost::uuids::uuid u =
 224     { 0x12 ,0x34, 0x56, 0x78
 225     , 0x90, 0xab
 226     , 0xcd, 0xef
 227     , 0x12, 0x34
 228     , 0x56, 0x78, 0x90, 0xab, 0xcd, 0xef
 229     };
 230 }
 231
 232 // example of creating a uuid class that
 233 // initializes the uuid in the constructor
 234 // using a defined mechanism
 235
 236 class uuid_class : public boost::uuids::uuid
 237 {
 238 public:
 239     uuid_class()
 240         : boost::uuids::uuid(boost::uuids::random_generator()())
 241     {}
 242
 243     explicit uuid_class(boost::uuids::uuid const&amp; u)
 244         : boost::uuids::uuid(u)
 245     {}
 246
 247     operator boost::uuids::uuid() {
 248         return static_cast&lt;boost::uuids::uuid&amp;&gt;(*this);
 249     }
 250
 251     operator boost::uuids::uuid() const {
 252         return static_cast&lt;boost::uuids::uuid const&amp;&gt;(*this);
 253     }
 254 };
 255
 256 uuid_class u1;
 257 uuid_class u2;
 258
 259 assert(u1 != u2);
 260 </pre>
 261
 262 <h3><a name="Byte Extraction">Byte Extraction</a></h3>
 263 <p>It is sometimes useful to get at the 16 bytes of a <b>uuid</b> directly.
 264 Typical use is as follows:
 265
 266 <pre>
 267 boost::uuids::uuid u;
 268 std::vector&lt;char&gt; v(u.size());
 269 std::copy(u.begin(), u.end(), v.begin());
 270 </pre>
 271
 272 <p>Note: <tt>boost::uuids::uuid::size()</tt> always returns 16.
 273
 274 <h2><a name="Reference">Reference</a></h2>
 275 <h3><a name="boost/uuid/uuid.hpp" href="./../../boost/uuid/uuid.hpp">boost/uuid/uuid.hpp</a></h3>
 276 <h4><a name="Synopsis">Synopsis</a></h4>
 277 <pre>
 278 namespace boost {
 279 namespace uuids {
 280
 281 class uuid {
 282 public:
 283     typedef uint8_t value_type;
 284     typedef uint8_t&amp; reference;
 285     typedef uint8_t const&amp; const_reference;
 286     typedef uint8_t* iterator;
 287     typedef uint8_t const* const_iterator;
 288     typedef std::size_t size_type;
 289     typedef std::ptrdiff_t difference_type;
 290
 291     static constexpr size_type static_size() noexcept;
 292
 293     // iteration
 294     iterator begin() noexcept;
 295     iterator end() noexcept;
 296     const_iterator begin() const noexcept;
 297     const_iterator end() const noexcept;
 298
 299     constexpr size_type size() const noexcept;
 300
 301     bool is_nil() const noexcept;
 302
 303     enum variant_type {
 304         variant_ncs, // NCS backward compatibility
 305         variant_rfc_4122, // defined in RFC 4122 document
 306         variant_microsoft, // Microsoft Corporation backward compatibility
 307         variant_future // future definition
 308     };
 309     variant_type variant() const noexcept;
 310
 311     enum version_type {
 312         version_unknown = -1,
 313         version_time_based = 1,
 314         version_dce_security = 2,
 315         version_name_based_md5 = 3,
 316         version_random_number_based = 4,
 317         version_name_based_sha1 = 5
 318     };
 319     version_type version() const noexcept;
 320
 321     // Swap function
 322     void swap(uuid&amp; rhs) noexcept;
 323
 324     uint8_t data[static_size()];
 325 };
 326
 327 // standard operators
 328 bool operator==(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
 329 bool operator!=(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
 330 bool operator&lt;(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
 331 bool operator&gt;(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
 332 bool operator&lt;=(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
 333 bool operator&gt;=(uuid const&amp; lhs, uuid const&amp; rhs) noexcept;
 334
 335 void swap(uuid&amp; lhs, uuid&amp; rhs) noexcept;
 336
 337 std::size_t hash_value(uuid const&amp; u) noexcept;
 338
 339 }} // namespace boost::uuids
 340 </pre>
 341
 342 <h4><a name="Size">Size</a></h4>
 343
 344 <p>The size of a <b>uuid</b> (in bytes) can be obtained either by
 345 calling the function <tt>boost::uuids::uuid::size()</tt> or by
 346 calling the static function <tt>boost::uuids::uuid::static_size()</tt>,
 347 both always return 16.
 348 <pre>
 349     boost::uuids::uuid u;
 350     assert(16 == u.size());
 351     assert(16 == boost::uuids::uuid::static_size());
 352 </pre>
 353
 354 <h4><a name="Iteration">Iteration</a></h4>
 355
 356 <p>Both iterators and constant iterators are provided.
 357 <pre>
 358     boost::uuids::uuid u;
 359     for (boost::uuids::uuid::const_iterator it=u.begin(); it!=u.end(); ++it) {
 360         boost::uuids::uuid::value_type v = *it;
 361     }
 362     for (boost::uuids::uuid::iterator it=u.begin(); it!=u.end(); ++it) {
 363         *it = 0;
 364     }
 365 </pre>
 366
 367 <h4><a name="Nil">Nil uuid</a></h4>
 368 <p>The function, <tt>boost::uuids::uuid::is_nil()</tt> returns true if and
 369 only if the <b>uuid</b> is equal to {00000000-0000-0000-0000-000000000000}.
 370 </p>
 371
 372 <h4><a name="Variant">Variant</a></h4>
 373 <p>Three bits of a <b>uuid</b> determine the variant.</p>
 374 <pre>
 375     boost::uuids::uuid u;
 376     boost::uuids::uuid::variant_type v = u.variant();
 377 </pre>
 378
 379 <h4><a name="Version">Version</a></h4>
 380 <p>Four bits of a <b>uuid</b> determine the variant, that is the mechanism
 381 used to generate the <b>uuid</b>.
 382 </p>
 383 <pre>
 384     boost::uuids::uuid u;
 385     boost::uuids::uuid::version_type v = u.version();
 386 </pre>
 387
 388 <h4><a name="Swap">Swap</a></h4>
 389 <p>Both <tt>boost::uuids::uuid::swap()</tt> and <tt>boost::uuids::swap()</tt>
 390 are provided.
 391 </p>
 392 <pre>
 393     boost::uuids::uuid u1, u2;
 394     u1.swap(u2);
 395     swap(u1, u2);
 396 </pre>
 397
 398 <h4><a name="Operators">Operators</a></h4>
 399 <p>
 400 All of the standard numeric operators are defined for the <b>uuid</b>
 401 class. These include:
 402 <pre>
 403     operator==
 404     operator!=
 405     operator&lt;
 406     operator&gt;
 407     operator&lt;=
 408     operator&gt;=
 409 </pre>
 410
 411 <h4><a name="Hash">Hash Function</a></h4>
 412 <p>
 413 This function allows <b>uuid</b>s to be used with
 414 <a href="http://www.boost.org/doc/html/hash.html"><b>boost::hash</b></a>
 415
 416 <pre>
 417 boost::hash&lt;boost::uuids::uuid&gt; uuid_hasher;
 418 std::size_t uuid_hash_value = uuid_hasher(boost::uuids::uuid());
 419 </pre>
 420
 421 <h3><a name="boost/uuid/uuid_generators.hpp" href="./../../boost/uuid/uuid_generators.hpp">boost/uuid/uuid_generators.hpp</a></h3>
 422 <h4><a name="Synopsis_generators">Synopsis</a></h4>
 423 This file includes all the <b>uuid</b> generators for convenience.
 424 <pre>
 425 #include &lt;<a href="./../../boost/uuid/nil_generator.hpp"><tt>boost/uuid/nil_generator.hpp</tt></a>&gt;
 426 #include &lt;<a href="./../../boost/uuid/string_generator.hpp"><tt>boost/uuid/string_generator.hpp</tt></a>&gt;
 427 #include &lt;<a href="./../../boost/uuid/name_generator.hpp"><tt>boost/uuid/name_generator.hpp</tt></a>&gt;
 428 #include &lt;<a href="./../../boost/uuid/random_generator.hpp"><tt>boost/uuid/random_generator.hpp</tt></a>&gt;
 429 </pre>
 430
 431 <h3><a name="boost/uuid/nil_generator.hpp" href="./../../boost/uuid/nil_generator.hpp">boost/uuid/nil_generator.hpp</a></h3>
 432 <h4><a name="Synopsis_nil_generator">Synopsis</a></h4>
 433 <pre>
 434 namespace boost {
 435 namespace uuids {
 436
 437 struct nil_generator {
 438     typedef uuid result_type;
 439
 440     uuid operator()() const;
 441 };
 442 uuid nil_uuid();
 443
 444 }} //namespace boost::uuids
 445 </pre>
 446
 447 <h4><a name="Nil Generator">Nil Generator</a></h4>
 448 <p>The <tt>boost::uuids::nil_generator</tt> class always generates a nil <b>uuid</b>.
 449 <pre>
 450 boost::uuids::nil_generator gen;
 451 boost::uuids::uuid u = gen();
 452 assert(u.is_nil() == true);
 453
 454 // or for convenience
 455 boost::uuids::uuid u = boost::uuids::nil_uuid();
 456 assert(u.is_nil() == true);
 457 </pre>
 458
 459 <h3><a name="boost/uuid/string_generator.hpp" href="./../../boost/uuid/string_generator.hpp">boost/uuid/string_generator.hpp</a></h3>
 460 <h4><a name="Synopsis_string_generator">Synopsis</a></h4>
 461
 462 <pre>
 463 namespace boost {
 464 namespace uuids {
 465
 466 struct string_generator {
 467     typedef uuid result_type;
 468
 469     template &lt;typename ch, typename char_traits, typename alloc&gt;
 470         uuid operator()(std::basic_string&lt;ch, char_traits, alloc&gt; const&amp; s) const;
 471 };
 472
 473 }} //namespace boost::uuids
 474 </pre>
 475
 476 <h4><a name="String Generator">String Generator</a></h4>
 477 <p>The <tt>boost::uuids::string_generator</tt> class generates a <b>uuid</b> from a string.
 478 <pre>
 479 boost::uuids::string_generator gen;
 480 boost::uuids::uuid u1 = gen("{01234567-89ab-cdef-0123-456789abcdef}");
 481 boost::uuids::uuid u2 = gen(L"01234567-89ab-cdef-0123-456789abcdef");
 482 boost::uuids::uuid u3 = gen(std::string("0123456789abcdef0123456789abcdef"));
 483 boost::uuids::uuid u4 = gen(std::wstring(L"01234567-89ab-cdef-0123-456789abcdef"));
 484 </pre>
 485
 486 <h3><a name="boost/uuid/name_generator.hpp" href="./../../boost/uuid/name_generator.hpp">boost/uuid/name_generator.hpp</a></h3>
 487 <h4><a name="Synopsis_name_generator">Synopsis</a></h4>
 488
 489 <pre>
 490 namespace boost {
 491 namespace uuids {
 492
 493 class name_generator {
 494 public:
 495     typedef uuid result_type;
 496
 497     explicit name_generator(uuid const&amp; namespace_uuid);
 498
 499     uuid operator()(const char* name) const;
 500     uuid operator()(const wchar_t* name) const;
 501     tempate &lt;typename ch, typename char_traits, typename alloc&gt;
 502         uuid operator()(std::basic_string&lt;ch, char_traits, alloc&gt; const&amp; name) const;
 503     uuid operator()(void const* buffer, std::size_t byte_count) const;
 504 };
 505
 506 }} //namespace boost::uuids
 507 </pre>
 508
 509 <h4><a name="Name Generator">Name Generator</a></h4>
 510 <p>
 511 The <tt>boost::uuids::name_generator</tt> class generates a name based <b>uuid</b> from a
 512 namespace uuid and a name.
 513 <pre>
 514 boost::uuids::uuid dns_namespace_uuid; // initialize to {6ba7b810-9dad-11d1-80b4-00c04fd430c8}
 515
 516 boost::uuids::name_generator gen(dns_namespace_uuid);
 517 boost::uuids::uuid u = gen("boost.org");
 518 </pre>
 519
 520 <h3><a name="boost/uuid/random_generator.hpp" href="./../../boost/uuid/random_generator.hpp">boost/uuid/random_generator.hpp</a></h3>
 521 <h4><a name="Synopsis_random_generator">Synopsis</a></h4>
 522
 523 <pre>
 524 namespace boost {
 525 namespace uuids {
 526
 527 template &lt;typename UniformRandomNumberGenerator&gt;
 528 class basic_random_generator {
 529 public:
 530     typedef uuid result_type;
 531
 532     basic_random_generator();
 533     explicit basic_random_generator(UniformRandomNumberGenerator&amp; gen);
 534     explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
 535
 536     uuid operator()();
 537 };
 538 typedef basic_random_generator&lt;mt19937&gt; random_generator;
 539
 540 }} // namespace boost::uuids
 541 </pre>
 542
 543 <h4><a name="Random Generator">Random Generator</a></h4>
 544 <p>
 545 The <tt>boost::uuids::basic_random_generator</tt> class generates a random number
 546 based uuid from a random number generator (one that conforms to the
 547 <a href="http://www.boost.org/libs/random/random-concepts.html#uniform-rng">UniformRandomNumberGenerator</a>
 548 concept).
 549 <pre>
 550 //default construct the random number generator and seed it
 551 boost::uuids::basic_random_generator&lt;boost::mt19937&gt; gen;
 552 boost::uuids::uuid u = gen();
 553
 554 //for convenience boost::uuids::random_generator
 555 //is equivalent to boost::uuids::basic_random_generator&lt;boost::mt19937&gt;
 556 boost::uuids::random_generator gen;
 557 boost::uuids::uuid u = gen();
 558
 559 //use an existing random number generator
 560 //pass either a reference or a pointer to the random number generator
 561 boost::mt19937 ran;
 562 boost::uuids::basic_random_generator&lt;boost::mt19937&gt; gen(&amp;ran);
 563 boost::uuids::uuid u = gen();
 564 </pre>
 565
 566 <h3><a name="boost/uuid/uuid_io.hpp" href="./../../boost/uuid/uuid_io.hpp">boost/uuid/uuid_io.hpp</a></h3>
 567 <h4><a name="Synopsis_io">Synopsis</a></h4>
 568 <pre>
 569 namespace boost {
 570 namespace uuids {
 571
 572 template &lt;typename ch, typename char_traits&gt;
 573     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);
 574
 575 template &lt;typename ch, typename char_traits&gt;
 576     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);
 577
 578 std::string to_string(uuid const&amp; u);
 579 std::wstring to_wstring(uuid const&amp; u);
 580
 581 }} // namespace boost::uuids
 582 </pre>
 583
 584 <h4><a name="Stream_operators">Stream Operators</a></h4>
 585 <p>
 586 The standard input and output stream operators <tt>&lt;&lt;</tt> and <tt>&gt;&gt;</tt>
 587 are provided by including <a href="../../boost/uuid/uuid_io.hpp"><tt>boost/uuid/uuid_io.hpp</tt></a>.
 588 The string representation of a <b>uuid</b> is <tt>hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh</tt>
 589 where <tt>h</tt> is a hexidecimal digit.
 590 <pre>
 591 boost::uuids::uuid u1; // initialize uuid
 592
 593 std::stringstream ss;
 594 ss &lt;&lt; u1;
 595
 596 boost::uuids::uuid u2;
 597 ss &gt;&gt; u2;
 598
 599 assert(u1, u2);
 600 </pre>
 601
 602 <p>
 603 One can also use <a href="http://www.boost.org/libs/conversion/lexical_cast.htm"><tt>boost::lexical_cast</tt></a>.
 604 <pre>
 605 boost::uuids::uuid u1; // initialize uuid
 606
 607 std::string s = boost::lexical_cast&lt;std::string&gt;(u);
 608 boost::uuids::uuid u2 = boost::lexical_cast&lt;boost::uuids::uuid&gt;(s);
 609
 610 assert(u1 == u2);
 611 </pre>
 612
 613 <h4><a name="to_string">To String</a></h4>
 614 <p>
 615 The functions <tt>to_string</tt> and <tt>to_wstring</tt> are provided as a
 616 convenience to convert a <b>uuid</b> to a string.  They are also likely faster than
 617 the stream operators or using <a href="http://www.boost.org/libs/conversion/lexical_cast.htm"><tt>boost::lexical_cast</tt></a>.
 618 <pre>
 619 boost::uuids::uuid u; // initialize uuid
 620
 621 std::string s1 = to_string(u);
 622
 623 std::wstring s2 = to_wstring(u);
 624 </pre>
 625
 626 <h3><a name="boost/uuid/uuid_serialize.hpp" href="./../../boost/uuid/uuid_serialize.hpp">boost/uuid/uuid_serialize.hpp</a></h3>
 627 <h4><a name="Synopsis_serialize">Synopsis</a></h4>
 628 <pre>
 629 namespace boost {
 630 namespace uuids {
 631
 632 BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
 633
 634 }} // namespace boost::uuids
 635 </pre>
 636
 637 <h4><a name="Serialization">Serialization</a></h4>
 638 <p>
 639 Serialization is accomplished with the <a href="http://www.boost.org/libs/serialization/doc/index.html">
 640 Boost Serialization</a> library.  A <b>uuid</b> is serialized as a
 641 <a href="http://www.boost.org/libs/serialization/doc/serialization.html#primitiveoperators">
 642 primitive type</a>, thus only the <b>uuid</b> value will be saved to/loaded from an archive.
 643 <p>
 644 Include <a href="../../boost/uuid/uuid_serialize.hpp"><tt>boost/uuid/uuid_serialize.hpp</tt></a> to enable serialization for <b>uuid</b>s.
 645
 646 <h2><a name="Design notes">Design notes</a></h2>
 647 <p>
 648 The document, <a href="http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf">
 649 http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf</a>, was used to design
 650 and implement the <b>boost::uuids::uuid</b> struct.
 651
 652 <p>The <tt>boost::uuids::basic_random_generator</tt> class' default constructor
 653 seeds the random number generator with a SHA-1 hash of a number of different
 654 values including <tt>std::time(0)</tt>, <tt>std::clock()</tt>, uninitialized
 655 data, value return from <tt>new unsigned int</tt>, etc..
 656
 657 <p>Using <a href="http://valgrind.org/">Valgrind</a> produces a number of false
 658 positives with the default constructor of <tt>boost::uuids::basic_random_generator</tt>.
 659 One solution is to suppress the errors as described in
 660 <a href="http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress">Valgrind's documentation</a>.
 661 Another solution is to use a different constructor of <tt>boost::uuids::basic_random_generator</tt>
 662 and explicitly pass in a random number generator.
 663 <pre>
 664 boost::mt19937 ran;
 665 ran.seed(time(NULL)); // one should likely seed in a better way
 666 boost::uuids::basic_random_generator&lt;boost::mt19937&gt; gen(&ran);
 667 boost::uuids::uuid u = gen();
 668 </pre>
 669
 670 <p>The <tt>boost::uuids::name_generator</tt> class uses the SHA-1 hash function to
 671 compute the <b>uuid</b>.
 672
 673 <p>All functions are re-entrant.  Classes are as thread-safe as an int.  That is an
 674 instance can not be shared between threads without proper synchronization.
 675
 676 <h2><a name="History and Acknowledgements">History and Acknowledgements</a></h2>
 677 <p>
 678 A number of people on the <a href="http://www.boost.org/">boost.org</a>
 679 mailing list provided useful comments and greatly helped to shape the library.
 680
 681 <p>Revised&nbsp; February 6, 2010</p>
 682
 683 <hr>
 684 <p>© Copyright Andy Tompkins, 2006</p>
 685 <p> Distributed under the Boost Software
 686 License, Version 1.0. (See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
 687 www.boost.org/LICENSE_1_0.txt</a>)</p>
 688 </body>
 689 </html>