Update of /cvsroot/boost/boost/libs/property_map/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv11072
Modified Files:
dynamic_property_map.html
Log Message:
updated documentation.
Index: dynamic_property_map.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/property_map/doc/dynamic_property_map.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- dynamic_property_map.html 2 May 2005 15:56:52 -0000 1.2
+++ dynamic_property_map.html 2 May 2007 20:49:24 -0000 1.3
@@ -1,24 +1,25 @@
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.3.3:
http://docutils.sourceforge.net/"; />
+<meta name="generator" content="Docutils 0.5:
http://docutils.sourceforge.net/"; />
<title>Boost Dynamic Property Maps</title>
<link rel="stylesheet" href="../../../boost.css" type="text/css" />
</head>
<body>
-<h1 class="title"><a class="reference" href="../../../index.htm"><img
align="middle" alt="Boost" src="../../../boost.png" /></a> Dynamic Property
Maps</h1>
<div class="document" id="logo-dynamic-property-maps">
-<div class="section" id="summary">
-<h1><a class="toc-backref" href="#id2" name="summary">Summary</a></h1>
+<h1 class="title"><a class="reference" href="../../../index.htm"><img
align="middle" alt="Boost" class="align-middle" src="../../../boost.png" /></a>
Dynamic Property Maps</h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id2" id="summary"
name="summary">Summary</a></h1>
<p>The dynamic property map interfaces provides access to a collection of
property maps through a dynamically-typed interface. An algorithm can
use it to manipulate property maps without knowing their key or
value types at compile-time. Type-safe codes can use dynamic property
maps to interface more easily and completely with scripting languages
and other text-based representations of key-value data.</p>
-<div class="contents topic" id="contents">
-<p class="topic-title first"><a name="contents">Contents</a></p>
+<div class="contents topic">
+<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#summary" id="id2" name="id2">Summary</a></li>
<li><a class="reference" href="#introduction" id="id3"
name="id3">Introduction</a><ul>
@@ -34,10 +35,10 @@
</ul>
</div>
</div>
-<div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id3"
name="introduction">Introduction</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id3" id="introduction"
name="introduction">Introduction</a></h1>
<p>The Boost Property Map library specifies statically type-safe
-interfaces through which key-value pairs can be manipulated by
+interfaces through which key-value pairs can be manipulated by
generic algorithms. Typically, an algorithm that uses property maps is
parameterized on the types of the property maps it uses, and it
manipulates them using the interfaces specified by the
@@ -45,7 +46,7 @@
<p>The following generic function illustrates property map basics.</p>
<pre class="literal-block">
template <typename AgeMap, typename GPAMap>
-void
+void
manipulate_freds_info(AgeMap ages, GPAMap gpas) {
typedef typename boost::property_traits<AgeMap>::key_type name_type;
@@ -66,19 +67,19 @@
put(gpas, fred, new_gpa);
}
</pre>
-<p>The function is parameterized on two property map types, <tt
class="literal"><span class="pre">AgeMap</span></tt> and
-<tt class="literal"><span class="pre">GPAMap</span></tt>, and takes a value
parameter for each of those types. The
-function uses the <tt class="literal"><span
class="pre">property_traits</span></tt> interface to ascertain, at
+<p>The function is parameterized on two property map types, <tt
class="docutils literal"><span class="pre">AgeMap</span></tt> and
+<tt class="docutils literal"><span class="pre">GPAMap</span></tt>, and takes a
value parameter for each of those types. The
+function uses the <tt class="docutils literal"><span
class="pre">property_traits</span></tt> interface to ascertain, at
compile-time, the value and key types of the property maps. The code
-then retrieves Fred's old information, using the <tt class="literal"><span
class="pre">get</span></tt> function, and
-updates it using the <tt class="literal"><span class="pre">put</span></tt>
function. The <tt class="literal"><span class="pre">get</span></tt> function is
required by the
-Readable Property Map concept and both <tt class="literal"><span
class="pre">get</span></tt> and <tt class="literal"><span
class="pre">put</span></tt> are required by the
+then retrieves Fred's old information, using the <tt class="docutils
literal"><span class="pre">get</span></tt> function, and
+updates it using the <tt class="docutils literal"><span
class="pre">put</span></tt> function. The <tt class="docutils literal"><span
class="pre">get</span></tt> function is required by the
+Readable Property Map concept and both <tt class="docutils literal"><span
class="pre">get</span></tt> and <tt class="docutils literal"><span
class="pre">put</span></tt> are required by the
Read/Write Property Map concept.</p>
<p>The above function not only requires the two type parameters to model
property map concepts, but also makes some extra assumptions.
-<tt class="literal"><span class="pre">AgeMap</span></tt> and <tt
class="literal"><span class="pre">GPAMap</span></tt> must have the same key
type, and that type must be
-constructable from a string. Furthermore, <tt class="literal"><span
class="pre">AgeMap</span></tt>'s value type must be
-constructable from an <tt class="literal"><span class="pre">int</span></tt>.
Although these requirements are not
+<tt class="docutils literal"><span class="pre">AgeMap</span></tt> and <tt
class="docutils literal"><span class="pre">GPAMap</span></tt> must have the
same key type, and that type must be
+constructable from a string. Furthermore, <tt class="docutils literal"><span
class="pre">AgeMap</span></tt>'s value type must be
+constructable from an <tt class="docutils literal"><span
class="pre">int</span></tt>. Although these requirements are not
explicitly stated, they are statically checked during compilation and
failure to meet them yields compile-time errors.</p>
<p>Although the static typing of property map interfaces usually provides
@@ -95,21 +96,21 @@
<p>Dynamic property maps specifically address the need for an interface
to property maps whose checking is delayed to runtime. Several
components combine to provide support for dynamic property maps. The
-<tt class="literal"><span class="pre">dynamic_properties</span></tt> class
collects a
+<tt class="docutils literal"><span class="pre">dynamic_properties</span></tt>
class collects a
group of heterogenous objects that model concepts from
the Boost Property Map library. Each property map is assigned a
string-based key when it is added to the collection, and it can be
-addressed using that key. Internally, <tt class="literal"><span
class="pre">dynamic_properties</span></tt> adapts
+addressed using that key. Internally, <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> adapts
each contained property map with the dynamic property map interface,
-which provides <tt class="literal"><span class="pre">get</span></tt> and <tt
class="literal"><span class="pre">put</span></tt> functions that
+which provides <tt class="docutils literal"><span class="pre">get</span></tt>
and <tt class="docutils literal"><span class="pre">put</span></tt> functions
that
can be called using values of any type that meets a few requirements.
Internally, the dynamic property map converts key and value pairs to
meet the requirements of the underlying property map or signals a
runtime exception if it cannot.</p>
-<div class="section" id="fred-s-info-revisited">
-<h2><a class="toc-backref" href="#id4"
name="fred-s-info-revisited">"Fred's Info" Revisited</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id4" id="fred-s-info-revisited"
name="fred-s-info-revisited">"Fred's Info" Revisited</a></h2>
<p>Here's what the example above looks like using the
-<tt class="literal"><span class="pre">dynamic_properties</span></tt>
interface:</p>
+<tt class="docutils literal"><span class="pre">dynamic_properties</span></tt>
interface:</p>
<pre class="literal-block">
void manipulate_freds_info(boost::dynamic_properties& properties)
{
@@ -129,14 +130,14 @@
}
</pre>
<p>The new function is not a template parameterized on the property map
-types but instead a concrete function that takes a <tt class="literal"><span
class="pre">dynamic_properties</span></tt>
+types but instead a concrete function that takes a <tt class="docutils
literal"><span class="pre">dynamic_properties</span></tt>
object. Furthermore, the code no longer makes reference to key or
value types: keys and values are represented with strings.
Nonetheless the function still uses non-string types where they are
-useful. For instance, Fred's old age is represented using an <tt
class="literal"><span class="pre">int</span></tt>.
-It's value is retreived by calling <tt class="literal"><span
class="pre">get</span></tt> with a
+useful. For instance, Fred's old age is represented using an <tt
class="docutils literal"><span class="pre">int</span></tt>.
+It's value is retreived by calling <tt class="docutils literal"><span
class="pre">get</span></tt> with a
type parameter, which determines its return type. Finally, the
-<tt class="literal"><span class="pre">get</span></tt> and <tt
class="literal"><span class="pre">put</span></tt> functions are each supplied a
string-based key that
+<tt class="docutils literal"><span class="pre">get</span></tt> and <tt
class="docutils literal"><span class="pre">put</span></tt> functions are each
supplied a string-based key that
differs depending on the property of concern.</p>
<p>Here's an example of how the above function might be called.</p>
<pre class="literal-block">
@@ -165,32 +166,32 @@
manipulate_freds_info(properties);
std::cout << "Fred's age: " << get(age_map,fred)
<< "\n"
- << "Fred's gpa: " << get(gpa_map,fred)
<< "\n";
+ << "Fred's gpa: " << get(gpa_map,fred)
<< "\n";
}
</pre>
-<p>The code first creates two property maps using <tt class="literal"><span
class="pre">std::map</span></tt> and the
-<tt class="literal"><span class="pre">associative_property_map</span></tt>
adaptor. After initializing the
+<p>The code first creates two property maps using <tt class="docutils
literal"><span class="pre">std::map</span></tt> and the
+<tt class="docutils literal"><span
class="pre">associative_property_map</span></tt> adaptor. After initializing
the
property maps with key-value data, it constructs a
-<tt class="literal"><span class="pre">dynamic_properties</span></tt> object
and adds to it both property maps,
-keyed on the strings "age" and "gpa". Finally <tt
class="literal"><span class="pre">manipulate_freds_info</span></tt>
-is passed the <tt class="literal"><span
class="pre">dynamic_properties</span></tt> object and the results of its
changes are
+<tt class="docutils literal"><span class="pre">dynamic_properties</span></tt>
object and adds to it both property maps,
+keyed on the strings "age" and "gpa". Finally <tt
class="docutils literal"><span class="pre">manipulate_freds_info</span></tt>
+is passed the <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> object and the results of its
changes are
displayed.</p>
-<p>As shown above, the <tt class="literal"><span
class="pre">dynamic_properties</span></tt> object provides, where needed, a
+<p>As shown above, the <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> object provides, where needed, a
dynamically-typed interface to property maps yet preserves the static
typing of property map uses elsewhere in an application.</p>
</div>
</div>
-<div class="section" id="reference">
-<h1><a class="toc-backref" href="#id5" name="reference">Reference</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id5" id="reference"
name="reference">Reference</a></h1>
<pre class="literal-block">
class dynamic_properties
</pre>
-<p>The <tt class="literal"><span class="pre">dynamic_properties</span></tt>
class provides a dynamically-typed interface to
+<p>The <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> class provides a dynamically-typed
interface to
a set of property maps. To use it, one must populate
-an object of this class with property maps using the <tt class="literal"><span
class="pre">property</span></tt> member
+an object of this class with property maps using the <tt class="docutils
literal"><span class="pre">property</span></tt> member
function.</p>
-<div class="section" id="member-functions">
-<h2><a class="toc-backref" href="#id6" name="member-functions">Member
Functions</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id6" id="member-functions"
name="member-functions">Member Functions</a></h2>
<pre class="literal-block">
dynamic_properties()
dynamic_properties(
@@ -199,80 +200,85 @@
const std::string&, const boost::any&, const boost::any&)
>& fn)
</pre>
-<p>A <tt class="literal"><span class="pre">dynamic_properties</span></tt>
object can be constructed with a function object
+<p>A <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> object can be constructed with a
function object
that, when called, creates a new property map. If an attempt is made
-to <tt class="literal"><span class="pre">put</span></tt> a key-value pair to a
nonexistent <tt class="literal"><span
class="pre">dynamic_properties</span></tt> key,
-then this function is called with the <tt class="literal"><span
class="pre">dynamic_properties</span></tt> key and the
-intended property key and value . If <tt class="literal"><span
class="pre">dynamic_properties</span></tt> is
-default-constructed, such a <tt class="literal"><span
class="pre">put</span></tt> attempt throws
-<tt class="literal"><span class="pre">property_not_found</span></tt>.</p>
+to <tt class="docutils literal"><span class="pre">put</span></tt> a key-value
pair to a nonexistent <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> key,
+then this function is called with the <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> key and the
+intended property key and value . If <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> is
+default-constructed, such a <tt class="docutils literal"><span
class="pre">put</span></tt> attempt throws
+<tt class="docutils literal"><span
class="pre">property_not_found</span></tt>.</p>
<pre class="literal-block">
template<typename PropertyMap>
-dynamic_properties&
+dynamic_properties&
property(const std::string& name, PropertyMap property_map)
</pre>
<p>This member function adds a property map to the set of maps contained,
-using <tt class="literal"><span class="pre">name</span></tt> as its key.</p>
-<p>Requirements: <tt class="literal"><span class="pre">PropertyMap</span></tt>
must model Readable Property Map or
+using <tt class="docutils literal"><span class="pre">name</span></tt> as its
key.</p>
+<p>Requirements: <tt class="docutils literal"><span
class="pre">PropertyMap</span></tt> must model Readable Property Map or
Read/Write Property Map.</p>
<pre class="literal-block">
void insert(const std::string& name,
std::auto_ptr<dynamic_property_map> pm)
</pre>
-<p>This member function directly adds a <tt class="literal"><span
class="pre">dynamic_property_map</span></tt>
-to the collection, using <tt class="literal"><span
class="pre">name</span></tt> as its key.</p>
+<p>This member function directly adds a <tt class="docutils literal"><span
class="pre">dynamic_property_map</span></tt>
+to the collection, using <tt class="docutils literal"><span
class="pre">name</span></tt> as its key.</p>
<pre class="literal-block">
iterator begin()
const_iterator begin() const
</pre>
<p>This member function returns an iterator over the set of property maps
-held by the <tt class="literal"><span
class="pre">dynamic_properties</span></tt> object.</p>
+held by the <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> object.</p>
<pre class="literal-block">
iterator end()
const_iterator end() const
</pre>
<p>This member function returns a terminal iterator over the set of
-dynamic property maps held by the <tt class="literal"><span
class="pre">dynamic_properties</span></tt> object. It is used to
+dynamic property maps held by the <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> object. It is used to
terminate traversals over the set of dynamic property maps</p>
<pre class="literal-block">
-iterator lower_bound(const std::string& name)
+iterator lower_bound(const std::string& name)
</pre>
<p>This member function returns an iterator that points to the first
-property map whose <tt class="literal"><span
class="pre">dynamic_properties</span></tt> key is <tt class="literal"><span
class="pre">name</span></tt>.
+property map whose <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> key is <tt class="docutils
literal"><span class="pre">name</span></tt>.
Bear in mind that multiple property maps may have the same
-<tt class="literal"><span class="pre">dynamic_properties</span></tt> key, so
long as their property map key types differ.</p>
+<tt class="docutils literal"><span class="pre">dynamic_properties</span></tt>
key, so long as their property map key types differ.</p>
<p>Invariant: The range [ lower_bound(name), end() ) contains every
-property map that has name for its <tt class="literal"><span
class="pre">dynamic_properties</span></tt> key.</p>
+property map that has name for its <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> key.</p>
</div>
-<div class="section" id="free-functions">
-<h2><a class="toc-backref" href="#id7" name="free-functions">Free
functions</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id7" id="free-functions"
name="free-functions">Free functions</a></h2>
<pre class="literal-block">
template<typename Key, typename Value>
-bool put(const std::string& name, dynamic_properties& dp, const
Key& key,
+bool put(const std::string& name, dynamic_properties& dp, const
Key& key,
const Value& value)
</pre>
-<p>This function adds a key-value pair to the property map with the matching
name
-and key type. If no matching property map is found and a generator function was
-supplied at construction, then that function is used to create a new
-property map; if the <tt class="literal"><span
class="pre">dynamic_properties</span></tt> object was
-default-constructed, then <tt class="literal"><span
class="pre">property_not_found</span></tt> is
-thrown. Furthermore, if the property map found does not support put,
-<tt class="literal"><span class="pre">dynamic_const_put_error</span></tt> is
thrown.</p>
+<p>This function adds a key-value pair to the property map with the
+matching name and key type. If no matching property map is found,
+behavior depends on the availability of a property map generator. If
+a property map generator was supplied when the <tt class="docutils
literal"><span class="pre">dynamic_properties</span></tt>
+object was constructed, then that function is used to create a new
+property map. If the generator fails to generate a property map
+(returns a null <tt class="docutils literal"><span
class="pre">auto_ptr</span></tt>), then the <tt class="docutils literal"><span
class="pre">put</span></tt> function returns
+<tt class="docutils literal"><span class="pre">false</span></tt>. If, on the
other hand, the <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> object
+has no property map generator (meaning it was default-constructed),
+then <tt class="docutils literal"><span
class="pre">property_not_found</span></tt> is thrown. If a candidate property
map is
+found but it does not support <tt class="docutils literal"><span
class="pre">put</span></tt>, <tt class="docutils literal"><span
class="pre">dynamic_const_put_error</span></tt> is
+thrown.</p>
<pre class="literal-block">
template<typename Value, typename Key>
-Value get(const std::string& name, const dynamic_properties& dp,
+Value get(const std::string& name, const dynamic_properties& dp,
const Key& key)
</pre>
<p>This function gets the value from the property-map whose namee is
-given and whose key type matches. If <tt class="literal"><span
class="pre">Value</span></tt> is <tt class="literal"><span
class="pre">std::string</span></tt>, then the
-property map's value type must either be <tt class="literal"><span
class="pre">std::string</span></tt> or model
-OutputStreamable. In the latter case, the <tt class="literal"><span
class="pre">get</span></tt> function converts the
+given and whose key type matches. If <tt class="docutils literal"><span
class="pre">Value</span></tt> is <tt class="docutils literal"><span
class="pre">std::string</span></tt>, then the
+property map's value type must either be <tt class="docutils literal"><span
class="pre">std::string</span></tt> or model
+OutputStreamable. In the latter case, the <tt class="docutils literal"><span
class="pre">get</span></tt> function converts the
value to a string. If no matching property map is found,
-<tt class="literal"><span class="pre">dynamic_get_failure</span></tt> is
thrown.</p>
-<hr />
+<tt class="docutils literal"><span class="pre">dynamic_get_failure</span></tt>
is thrown.</p>
+<hr class="docutils" />
<pre class="literal-block">
class dynamic_property_map
</pre>
-<p>This class describes the interface used by <tt class="literal"><span
class="pre">dynamic_properties</span></tt> to
+<p>This class describes the interface used by <tt class="docutils
literal"><span class="pre">dynamic_properties</span></tt> to
interact with a user's property maps polymorphically.</p>
<pre class="literal-block">
boost::any get(const any& key)
@@ -284,7 +290,7 @@
2) For this expression to be valid, the key must be
associated with some value, otherwise the result is undefined.</p>
<pre class="literal-block">
-std::string get_string(const any& key)
+std::string get_string(const any& key)
</pre>
<p>Given a representation of a key, return the string representation
of the value associated with that key.</p>
@@ -295,7 +301,7 @@
associated with some value, otherwise the result is undefined.
3) The value type of the property map must model Output Streamable.</p>
<pre class="literal-block">
-void put(const any& key, const any& value)
+void put(const any& key, const any& value)
</pre>
<p>Given a representation of a key and a representation of a value, the
key and value are associated in the property map.</p>
@@ -308,16 +314,16 @@
case an error will be signaled. This is the runtime analogue of the
Readable Property Map concept.</p>
<pre class="literal-block">
-const std::type_info& key() const
+const std::type_info& key() const
</pre>
-<p>Returns a <tt class="literal"><span class="pre">type_info</span></tt>
object that represents the property map's key type.</p>
+<p>Returns a <tt class="docutils literal"><span
class="pre">type_info</span></tt> object that represents the property map's key
type.</p>
<pre class="literal-block">
-const std::type_info& value() const
+const std::type_info& value() const
</pre>
-<p>Returns a <tt class="literal"><span class="pre">type_info</span></tt>
object that represents the property map's value type.</p>
+<p>Returns a <tt class="docutils literal"><span
class="pre">type_info</span></tt> object that represents the property map's
value type.</p>
</div>
-<div class="section" id="exceptions">
-<h2><a class="toc-backref" href="#id8" name="exceptions">Exceptions</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id8" id="exceptions"
name="exceptions">Exceptions</a></h2>
<pre class="literal-block">
struct dynamic_property_exception : public std::exception {
virtual ~dynamic_property_exception() throw() {}
@@ -345,20 +351,21 @@
const char* what() const throw();
};
</pre>
-<p>Under certain circumstances, calls to <tt class="literal"><span
class="pre">dynamic_properties</span></tt> member
+<p>Under certain circumstances, calls to <tt class="docutils literal"><span
class="pre">dynamic_properties</span></tt> member
functions will throw one of the above exceptions. The three concrete
exceptions can all be caught using the general
-<tt class="literal"><span class="pre">dynamic_property_exception</span></tt>
moniker when greater precision is not
+<tt class="docutils literal"><span
class="pre">dynamic_property_exception</span></tt> moniker when greater
precision is not
needed. In addition, all of the above exceptions derive from the
-standard <tt class="literal"><span class="pre">std::exception</span></tt> for
even more generalized error handling.
+standard <tt class="docutils literal"><span
class="pre">std::exception</span></tt> for even more generalized error handling.
The specific circumstances that result in these exceptions are
described above.</p>
</div>
</div>
</div>
-<hr class="footer" />
<div class="footer">
-Generated on: 2005-02-08 16:39 UTC.
+<hr class="footer" />
+Generated on: 2007-05-02 20:47 UTC.
+
</div>
</body>
</html>
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
