]>
Commit | Line | Data |
---|---|---|
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 <<a href="./../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>> | |
143 | #include <<a href="./../../boost/uuid/uuid_generators.hpp"><tt>boost/uuid/uuid_generators.hpp</tt></a>> | |
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& rhs) | |
159 | : tag(rhs.tag) | |
160 | , state(rhs.state) | |
161 | {} | |
162 | ||
163 | bool operator==(object const& rhs) const { | |
164 | return tag == rhs.tag; | |
165 | } | |
166 | ||
167 | object& operator=(object const& 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 <<a href="./../../boost/uuid/uuid.hpp"><tt>boost/uuid/uuid.hpp</tt></a>> | |
211 | #include <<a href="./../../boost/uuid/uuid_generators.hpp"><tt>boost/uuid/uuid_generators.hpp</tt></a>> | |
212 | ||
213 | { // example using memcpy | |
214 | unsigned char uuid_data[16]; | |
215 | // fill uuid_data | |
216 | ||
217 | boost::uuids::uuid u; | |
218 | ||
219 | memcpy(&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& u) | |
244 | : boost::uuids::uuid(u) | |
245 | {} | |
246 | ||
247 | operator boost::uuids::uuid() { | |
248 | return static_cast<boost::uuids::uuid&>(*this); | |
249 | } | |
250 | ||
251 | operator boost::uuids::uuid() const { | |
252 | return static_cast<boost::uuids::uuid const&>(*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<char> 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& reference; | |
285 | typedef uint8_t const& 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& rhs) noexcept; | |
323 | ||
324 | uint8_t data[static_size()]; | |
325 | }; | |
326 | ||
327 | // standard operators | |
328 | bool operator==(uuid const& lhs, uuid const& rhs) noexcept; | |
329 | bool operator!=(uuid const& lhs, uuid const& rhs) noexcept; | |
330 | bool operator<(uuid const& lhs, uuid const& rhs) noexcept; | |
331 | bool operator>(uuid const& lhs, uuid const& rhs) noexcept; | |
332 | bool operator<=(uuid const& lhs, uuid const& rhs) noexcept; | |
333 | bool operator>=(uuid const& lhs, uuid const& rhs) noexcept; | |
334 | ||
335 | void swap(uuid& lhs, uuid& rhs) noexcept; | |
336 | ||
337 | std::size_t hash_value(uuid const& 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< | |
406 | operator> | |
407 | operator<= | |
408 | operator>= | |
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<boost::uuids::uuid> 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 <<a href="./../../boost/uuid/nil_generator.hpp"><tt>boost/uuid/nil_generator.hpp</tt></a>> | |
426 | #include <<a href="./../../boost/uuid/string_generator.hpp"><tt>boost/uuid/string_generator.hpp</tt></a>> | |
427 | #include <<a href="./../../boost/uuid/name_generator.hpp"><tt>boost/uuid/name_generator.hpp</tt></a>> | |
428 | #include <<a href="./../../boost/uuid/random_generator.hpp"><tt>boost/uuid/random_generator.hpp</tt></a>> | |
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 <typename ch, typename char_traits, typename alloc> | |
470 | uuid operator()(std::basic_string<ch, char_traits, alloc> const& 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& namespace_uuid); | |
498 | ||
499 | uuid operator()(const char* name) const; | |
500 | uuid operator()(const wchar_t* name) const; | |
501 | tempate <typename ch, typename char_traits, typename alloc> | |
502 | uuid operator()(std::basic_string<ch, char_traits, alloc> const& 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 <typename UniformRandomNumberGenerator> | |
528 | class basic_random_generator { | |
529 | public: | |
530 | typedef uuid result_type; | |
531 | ||
532 | basic_random_generator(); | |
533 | explicit basic_random_generator(UniformRandomNumberGenerator& gen); | |
534 | explicit basic_random_generator(UniformRandomNumberGenerator* pGen); | |
535 | ||
536 | uuid operator()(); | |
537 | }; | |
538 | typedef basic_random_generator<mt19937> 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<boost::mt19937> gen; | |
552 | boost::uuids::uuid u = gen(); | |
553 | ||
554 | //for convenience boost::uuids::random_generator | |
555 | //is equivalent to boost::uuids::basic_random_generator<boost::mt19937> | |
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<boost::mt19937> gen(&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 <typename ch, typename char_traits> | |
573 | std::basic_ostream<ch, char_traits>& operator<<(std::basic_ostream<ch, char_traits> &os, uuid const& u); | |
574 | ||
575 | template <typename ch, typename char_traits> | |
576 | std::basic_istream<ch, char_traits>& operator>>(std::basic_istream<ch, char_traits> &is, uuid &u); | |
577 | ||
578 | std::string to_string(uuid const& u); | |
579 | std::wstring to_wstring(uuid const& 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><<</tt> and <tt>>></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 << u1; | |
595 | ||
596 | boost::uuids::uuid u2; | |
597 | ss >> 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<std::string>(u); | |
608 | boost::uuids::uuid u2 = boost::lexical_cast<boost::uuids::uuid>(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<boost::mt19937> 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 February 6, 2010</p> | |
682 | ||
683 | <hr> | |
684 |