|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r58614 - in trunk: libs/uuid status
From: atompkins_at_[hidden]
Date: 2010-01-01 03:00:50
Author: atompkins
Date: 2010-01-01 03:00:50 EST (Fri, 01 Jan 2010)
New Revision: 58614
URL: http://svn.boost.org/trac/boost/changeset/58614
Log:
updated and reorganized documentation
marked explicit failures
Text files modified:
trunk/libs/uuid/uuid.html | 405 ++++++++++++++++++++++++---------------
trunk/status/explicit-failures-markup.xml | 19 +
2 files changed, 267 insertions(+), 157 deletions(-)
Modified: trunk/libs/uuid/uuid.html
==============================================================================
--- trunk/libs/uuid/uuid.html (original)
+++ trunk/libs/uuid/uuid.html 2010-01-01 03:00:50 EST (Fri, 01 Jan 2010)
@@ -2,40 +2,92 @@
<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.png (6897 bytes)"
- align="center" WIDTH="277" HEIGHT="86">
-Uuid</h1>
+<h1><img src="../../boost.png" alt="Boost" WIDTH="277" HEIGHT="86">Uuid</h1>
-<h2><a name="Contents">Contents</h2>
+<h2><a name="Contents"></a>Contents</h2>
<ol>
<li>Introduction</li>
- <li>Class uuid synopsis</li>
- <li>Rationale</li>
- <li>Interface</li>
+ <li>Examples</li>
<ul>
- <li>Operators</li>
- <li>Input and Output</li>
- <li>Nil uuid</li>
- <li>Byte Extraction</li>
- <li>Hash Function</li>
- <li>Generation</li>
+ <li>Tagging</li>
+ <li>POD Efficiencies</li>
+ <li>Byte Extraction</li>
+ </ul
+ <li>Reference</li>
+ <ul>
+ <li>boost/uuid/uuid.hpp</li>
+ <ul>
+ <li>Synopsis</li>
+ <li>Size</li>
+ <li>Iteration</li>
+ <li>Nil uuid</li>
+ <li>Variant</li>
+ <li>Version</li>
+ <li>Swap</li>
+ <li>Operators</li>
+ <li>Hash</li>
+ </ul>
+ <li>boost/uuid/uuid_generators.hpp</li>
+ <ul>
+ <li>Synopsis</li>
+ <li>Nil Generator</li>
+ <li>String Generator</li>
+ <li>Name Generator</li>
+ <li>Random Generator</li>
+ </ul>
+ <li>boost/uuid/uuid_io.hpp</li>
+ <ul>
+ <li>Synopsis</li>
+ <li>Input and Output</li>
+ </ul>
+ <li>boost/uuid/uuid_serialize.hpp</li>
+ <ul>
+ <li>Synopsis</li>
+ <li>Serialization</li>
+ </ul>
</ul>
- <li>Serialization</li>
<li>Design notes</li>
- <li>References</li>
<li>History and Acknowledgements</li>
</ol>
-<h2><a name="Introduction">Introduction</h2>
-UUIDs are a 128 bit or 16 byte value. They are often
-used to tag objects. If a UUID is generated by one of the defined
-mechanisms, it is 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
+<h2><a name="Introduction"></a>Introduction</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>
+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="Examples"></a>Examples</h2>
+<h3><a name="Tagging"></a>Tagging</h3>
<pre>
// example of tagging an object with a uuid
// see boost/libs/uuid/test/test_tagging.cpp
@@ -56,16 +108,16 @@
, state(state)
{}
- object(object const& rhs)
+ object(object const& rhs)
: tag(rhs.tag)
, state(rhs.state)
{}
- bool operator==(object const& rhs) const {
+ bool operator==(object const& rhs) const {
return tag == rhs.tag;
}
- object& operator=(object const& rhs) {
+ object& operator=(object const& rhs) {
tag = rhs.tag;
state = rhs.state;
}
@@ -88,6 +140,8 @@
assert(o1 != o3);
assert(o2 != o3);
</pre>
+
+<h3><a name="POD Efficiencies"></a>POD Efficiencies</h3>
<p>
This library implements a UUID as a POD allowing a UUID
to be used in the most efficient ways, including using memcpy,
@@ -110,7 +164,7 @@
boost::uuids::uuid u;
- memcpy(&u, uuid_data, 16);
+ memcpy(&u, uuid_data, 16);
}
{ // example using aggregate initializers
@@ -134,16 +188,16 @@
: boost::uuids::uuid(boost::uuids::random_generator()())
{}
- explicit uuid_class(boost::uuids::uuid const& u)
+ explicit uuid_class(boost::uuids::uuid const& u)
: boost::uuids::uuid(u)
{}
operator boost::uuids::uuid() {
- return static_cast<boost::uuids::uuid&>(*this);
+ return static_cast<boost::uuids::uuid&>(*this);
}
operator boost::uuids::uuid() const {
- return static_cast<boost::uuids::uuid const&>(*this);
+ return static_cast<boost::uuids::uuid const&>(*this);
}
};
@@ -153,7 +207,21 @@
assert(u1 != u2);
</pre>
-<h2><a name="Class uuid synopsis">Class uuid synopsis</h2>
+<h3><a name="Byte Extraction"></a>Byte Extraction</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<char> 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"></a>Reference</h2>
+<h3><a name="boost/uuid/uuid.hpp"</a>boost/uuid/uuid.hpp</h3>
+<h4><a name="Synopsis"</a>Synopsis</h4>
<pre>
#include <boost/uuid/uuid.hpp>
@@ -163,8 +231,8 @@
class uuid {
public:
typedef uint8_t value_type;
- typedef uint8_t& reference;
- typedef uint8_t const& const_reference;
+ 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;
@@ -201,49 +269,107 @@
version_type version() const;
// Swap function
- void swap(uuid& rhs);
+ void swap(uuid& rhs);
uint8_t data[static_size()];
};
// standard operators
-bool operator==(uuid const& lhs, uuid const& rhs);
-bool operator!=(uuid const& lhs, uuid const& rhs);
-bool operator<(uuid const& lhs, uuid const& rhs);
-bool operator>(uuid const& lhs, uuid const& rhs);
-bool operator<=(uuid const& lhs, uuid const& rhs);
-bool operator>=(uuid const& lhs, uuid const& rhs);
+bool operator==(uuid const& lhs, uuid const& rhs);
+bool operator!=(uuid const& lhs, uuid const& rhs);
+bool operator<(uuid const& lhs, uuid const& rhs);
+bool operator>(uuid const& lhs, uuid const& rhs);
+bool operator<=(uuid const& lhs, uuid const& rhs);
+bool operator>=(uuid const& lhs, uuid const& rhs);
-void swap(uuid& lhs, uuid& rhs);
+void swap(uuid& lhs, uuid& rhs);
-std::size_t hash_value(uuid const& u);
+std::size_t hash_value(uuid const& u);
}} // namespace boost::uuids
</pre>
+
+<h4><a name="Size"</a>Size</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>
-#include <boost/uuid/uuid_io.hpp>
+ boost::uuids::uuid u;
+ assert(16 == u.size());
+ assert(16 == boost::uuids::uuid::static_size());
+</pre>
-namespace boost {
-namespace uuids {
+<h4><a name="Iteration"</a>Iteration</h4>
-template <typename ch, typename char_traits>
- std::basic_ostream<ch, char_traits>& operator<<(std::basic_ostream<ch, char_traits> &os, uuid const& u);
+<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>
-template <typename ch, typename char_traits>
- std::basic_istream<ch, char_traits>& operator>>(std::basic_istream<ch, char_traits> &is, uuid &u);
+<h4><a name="Nil"></a>Nil uuid</h4>
+<p>The function, <tt>boost::uuids::uuid::is_null()</tt> returns true if and
+only if the <b>uuid</b> is equal to {00000000-0000-0000-0000-000000000000}.
+</p>
-}} // namespace boost::uuids
+<h4><a name="Variant"></a>Variant</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"></a>Version</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>
-#include <boost/uuid/uuid_serialize.hpp>
+ boost::uuids::uuid u;
+ boost::uuids::uuid::version_type v = u.version();
+</pre>
-namespace boost {
-namespace uuids {
+<h4><a name="Swap"></a>Swap</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>
-BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
+<h4><a name="Operators"></a>Operators</h4>
+<p>
+All of the standard numeric operators are defined for the <b>uuid</b>
+class. These include:
+<pre>
+ operator==
+ operator!=
+ operator<
+ operator>
+ operator<=
+ operator>=
+</pre>
-}} // namespace boost::uuids
+<h4><a name="Hash"></a>Hash Function</h4>
+<p>
+This function allows <b>uuid</b>s to be used with
+boost::hash
+
+<pre>
+boost::hash<boost::uuids::uuid> uuid_hasher;
+std::size_t uuid_hash_value = uuid_hasher(boost::uuids::uuid());
</pre>
+
+<h3><a name="boost/uuid/uuid_generators.hpp"</a>boost/uuid/uuid_generators.hpp</h3>
+<h4><a name="Synopsis_generators"</a>Synopsis</h4>
<pre>
#include <boost/uuid/uuid_generators.hpp>
@@ -261,19 +387,19 @@
typedef uuid result_type;
template <typename ch, typename char_traits, typename alloc>
- uuid operator()(std::basic_string<ch, char_traits, alloc> const& s) const;
+ uuid operator()(std::basic_string<ch, char_traits, alloc> const& s) const;
};
class name_generator {
public:
typedef uuid result_type;
- explicit name_generator(uuid const& namespace_uuid);
+ explicit 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()(std::basic_string<ch, char_traits, alloc> const& name) const;
uuid operator()(void const* buffer, std::size_t byte_count) const;
};
@@ -283,7 +409,7 @@
typedef uuid result_type;
basic_random_generator();
- explicit basic_random_generator(UniformRandomNumberGenerator& gen);
+ explicit basic_random_generator(UniformRandomNumberGenerator& gen);
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
uuid operator()();
@@ -292,87 +418,9 @@
}} // namespace boost::uuids
</pre>
-<h2><a name="Rationale">Rationale</h2>
-
-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>
-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.
-
-<h2><a name="Interface">Interface</h2>
-
-<h3><a name="Operators">Operators</h3>
-All of the standard numeric operators are defined for the <b>uuid</b>
-class. These include:
-<br>
-
-<pre>
- operator==
- operator!=
- operator<
- operator>
- operator<=
- operator>=
-</pre>
-
-<h3><a name="Input and Output">Input and Output</h3>
-Input and output stream operators <tt><<</tt> and <tt>>></tt>
-are provided by including boost/uuid/uuid_io.hpp.
-The external representation of a <b>uuid</b> is a string of
-hexidecimal digits of the following form:
-<br>
-hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh
-
-<h3><a name="NilUuid">Nil uuid</h3>
-The function, <tt>boost::uuids::uuid::is_null()</tt> returns true if and
-only if the <b>uuid</b> is equal to {00000000-0000-0000-0000-000000000000}
-and returns false otherwise.
-Note that <tt>boost::uuids::uuid().is_null() == true</tt>.
-
-<h3><a name="ByteExtraction">Byte Extraction</h3>
-These functions are useful to get at the 16 bytes of a <b>uuid</b>. Typical use is as follows:
-
-<pre>
-boost::uuids::uuid u;
-std::vector<char> v(u.size());
-std::copy(u.begin(), u.end(), v.begin());
-</pre>
-
-<p>Note: <tt>boost::uuids::uuid::size()</tt> always returnes 16.
-
-<h3><a name="Hash">Hash Function</h3>
-This function allows <b>uuid</b>s to be used with
-boost::hash
-
-<pre>
-boost::hash<boost::uuids::uuid> uuid_hasher;
-std::size_t uuid_hash_value = uuid_hasher(boost::uuids::uuid());
-</pre>
-
-<h3><a name="Generation">Generation</h3>
-There are a number of classes provided that generate <b>uuid</b>s.
-<p>
-Include boost/uuid/uuid_generators.hpp.
-<p>
-The <tt>boost::uuids::nil_generator</tt> class always generates a nil <b>uuid</b>.
+<h4><a name="Nil Generator"</a>Nil Generator</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();
@@ -383,7 +431,8 @@
assert(u.is_nil() == true);
</pre>
-The <tt>boost::uuids::string_generator</tt> class generates a uuid from a string.
+<h4><a name="String Generator"</a>String Generator</h4>
+<p>The <tt>boost::uuids::string_generator</tt> class generates a <b>uuid</b> from a string.
<pre>
boost::uuids::string_generator gen;
boost::uuids::uuid u1 = gen("{01234567-89ab-cdef-0123456789abcdef}");
@@ -392,7 +441,9 @@
boost::uuids::uuid u4 = gen(std::wstring(L"01234567-89ab-cdef-0123456789abcdef"));
</pre>
-The <tt>boost::uuids::name_generator</tt> class generates a name based uuid from a
+<h4><a name="Name Generator"</a>Name Generator</h4>
+<p>
+The <tt>boost::uuids::name_generator</tt> class generates a name based <b>uuid</b> from a
namespace uuid and a name.
<pre>
boost::uuids::uuid dns_namespace_uuid; // initialize to {6ba7b810-9dad-11d1-80b4-00c04fd430c8}
@@ -401,6 +452,8 @@
boost::uuids::uuid u = gen("boost.org");
</pre>
+<h4><a name="Random Generator"</a>Random Generator</h4>
+<p>
The <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>
@@ -418,11 +471,56 @@
//use an existing random number generator
//pass either a reference or a pointer to the random number generator
boost::mt19937 ran;
-boost::uuids::basic_random_generator<boost::mt19937> gen(&ran);
+boost::uuids::basic_random_generator<boost::mt19937> gen(&ran);
boost::uuids::uuid u = gen();
</pre>
-<h2><a name="Serialization">Serialization</h2>
+<h3><a name="boost/uuid/uuid_io.hpp"</a>boost/uuid/uuid_io.hpp</h3>
+<h4><a name="Synopsis_io"</a>Synopsis</h4>
+<pre>
+#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);
+
+}} // namespace boost::uuids
+</pre>
+
+<h4><a name="Input and Output"></a>Input and Output</h4>
+<p>
+Input and output stream operators <tt><<</tt> and <tt>>></tt>
+are provided by including boost/uuid/uuid_io.hpp.
+The external representation of a <b>uuid</b> is a string of
+hexidecimal digits of the following form: <tt>hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh</tt>
+<pre>
+boost::uuids::uuid u;
+
+std::stringstream ss;
+ss << u;
+ss >> u;
+</pre>
+
+<h3><a name="boost/uuid/uuid_serialize.hpp"</a>boost/uuid/uuid_serialize.hpp</h3>
+<h4><a name="Synopsis_serialize"</a>Synopsis</h4>
+<pre>
+#include <boost/uuid/uuid_serialize.hpp>
+
+namespace boost {
+namespace uuids {
+
+BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
+
+}} // namespace boost::uuids
+</pre>
+
+<h4><a name="Serialization"></a>Serialization</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">
@@ -430,14 +528,15 @@
<p>
Include boost/uuid/uuid_serialize.hpp to enable serialization for <b>uuid</b>s.
-<h2><a name="Design notes">Design notes</h2>
-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>, was used to design
+<h2><a name="Design notes"></a>Design notes</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>, was used to design
and implement the <b>boost::uuids::uuid</b> struct.
<p>The <tt>boost::uuids::basic_random_generator</tt> class' default constructor
-seeds the random number generator with a SHA-1 hash of a number of different
-values including <tt>std::time(0)</tt>, <tt>std::clock()</tt>, uninitialized
+seeds the random number generator with a SHA-1 hash of a number of different
+values including <tt>std::time(0)</tt>, <tt>std::clock()</tt>, uninitialized
data, value return from <tt>new unsigned int</tt>, etc..
<p>The <tt>boost::uuids::name_generator</tt> class uses the SHA-1 hash function to
@@ -446,20 +545,12 @@
<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="References">References</h2>
-<ul>
-<li>The uuid header: uuid.hpp
-<li>The test code: test_uuid.cpp,
-test_serialization.cpp,
-test_sha1.cpp
-</ul>
-
-<h2><a name="History and Acknowledgements">History and Acknowledgements</h2>
-
+<h2><a name="History and Acknowledgements"></a>History and Acknowledgements</h2>
+<p>
A number of people on the boost.org
mailing list provided useful comments and greatly helped to shape the library.
-<p>Revised November 25, 2009</p>
+<p>Revised January 1, 2010</p>
<hr>
<p>© Copyright Andy Tompkins, 2006</p>
Modified: trunk/status/explicit-failures-markup.xml
==============================================================================
--- trunk/status/explicit-failures-markup.xml (original)
+++ trunk/status/explicit-failures-markup.xml 2010-01-01 03:00:50 EST (Fri, 01 Jan 2010)
@@ -5856,6 +5856,25 @@
</mark-expected-failures>
</library>
+ <!-- uuid -->
+ <library name="uuid">
+ <mark-expected-failures>
+ <test name="compile*"/>
+ <test name="test*"/>
+ <toolset name="borland-cb2009"/>
+ <toolset name="borland-cb2010"/>
+ <toolset name="borland-5.9*"/>
+ <toolset name="borland-6.1*"/>
+ <toolset name="borland-6.2*"/>
+ <toolset name="intel-vc9-win-11.1"/>
+ <note author="Andy Tompkins" refid="6">
+ Boost.Test does not work on these platforms, thus the
+ tests fail since they use it. I plan to use
+ boost/detail/lightweight_test.hpp instead at a later
+ time.
+ </note>
+ </mark-expected-failures>
+ </library>
<!-- variant -->
<library name="variant">
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk