Ticket #6538: property_map.html

File property_map.html, 10.2 KB (added by anonymous, 11 years ago)

rewrite of property_map.html

Line 
1<HTML>
2<!--
3 Copyright (c) Jeremy Siek 2000
4
5 Distributed under the Boost Software License, Version 1.0.
6 (See accompanying file LICENSE_1_0.txt or copy at
7 http://www.boost.org/LICENSE_1_0.txt)
8 -->
9<Head>
10<Title>Property Map Library</Title>
11<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
12 ALINK="#ff0000">
13<IMG SRC="../../../boost.png"
14 ALT="C++ Boost" width="277" height="86">
15
16<BR Clear>
17
18<H1><A NAME="sec:property-maps"></A>
19Boost Property Map Library
20</H1>
21
22<p>
23The Boost Property Map Library specifies concepts that define an
24interface for mapping key objects to value objects. Algorithms can
25take property maps as arguments relying on the concept definition
26and be ignorant of the underlying data structures. The algorithms can
27therefore be more generic.
28</p>
29
30<p>
31Besides concepts, the Boost Property Map Library also contains <a
32href="#sec:property-map-types">adaptors</a> that provide property map
33interfaces for commonly used data structures that implement a mapping
34operation, such as build-in arrays (pointers), iterators, and <code>std::map</code>.
35</p>
36
37<p>Property maps are statically-typed; you can use the <a
38href="dynamic_property_map.html"><code>dynamic_properties</code></a> class
39to access a set of property maps through a dynamically-typed interface (e.g.,
40when you read an unknown set of attributes from a file).</p>
41
42
43<h2><A NAME="sec:property-map-concepts"></A>
44Property Map Concepts
45</h2>
46<p>
47The property map concepts prescribe that <code>get()</code> and <code>put()</code>
48functions are provided that are used as if they are global functions; i.e,
49without a namespace qualifier. Furthermore, they prescribe <code>operator[]</code>
50to access value objects.
51</p>
52
53<p>
54The following example from shows the property map functions in use. The templated
55<code>fix_squares</code> function has a property map as parameter.</p>
56
57<pre>
58#include &lt;iostream&gt;
59#include &lt;boost/property_map/property_map.hpp&gt;
60
61template &lt;typename T&gt; void fix_squares(T squares) // assuming that T is a property map
62{
63 typedef typename boost::property_traits&lt;T&gt;::value_type value_type;
64
65 value_type answer1 = get(squares, 1); // &lt;- use get() to get a value
66 value_type&amp; answer2 = squares[2]; // &lt;- use operator[] to get a reference
67 value_type&amp; answer4 = get(squares, 4); // &lt;- use get() to get a reference
68
69 if(answer1 == 1) {
70 std::cout &lt;&lt; &quot;right: 1 X 1 == &quot; &lt;&lt; answer1 &lt;&lt; std::endl;<br> } else {
71 std::cout &lt;&lt; &quot;wrong: 1 X 1 != &quot; &lt;&lt; answer1 &lt;&lt; std::endl;
72 put(squares, 1, 1); // &lt;- use put() to set a value
73 }
74
75  if( answer2 == 4) {
76 std::cout &lt;&lt; &quot;right: 2 X 2 == &quot; &lt;&lt; answer2 &lt;&lt; std::endl &lt;&lt; std::endl;
77 } else {
78 std::cout &lt;&lt; &quot;wrong: 2 X 2 != &quot; &lt;&lt; answer2 &lt;&lt; std::endl&lt;&lt; std::endl;
79 answer2 = 4; // &lt;- answer2 is a reference, hence this works
80 }
81
82 if( answer4 == 16) {
83 std::cout &lt;&lt; &quot;right: 4 X 4 == &quot; &lt;&lt; answer4 &lt;&lt; std::endl &lt;&lt; std::endl;
84 } else {
85 std::cout &lt;&lt; &quot;wrong: 4 X 4 != &quot; &lt;&lt; answer4 &lt;&lt; std::endl&lt;&lt; std::endl;
86 squares[4] = 16;// &lt;- use operator[] to get a reference
87 // get(squares, 4) = 16; // &lt;- this would work, but using put() looks nicer
88 }
89}</pre>
90
91<p>The following example creates a <a href="./vector_property_map.html"><code>vector_property_map</code></a>, and passes it to the <code>fix_squares</code> function twice:
92</p>
93
94<pre>
95#include &lt;boost/property_map/property_map.hpp&gt;
96
97int main()
98{
99 boost::vector_property_map&lt;int&gt; squares;
100
101 squares[1] = 2;
102 squares[2] = 4;
103 squares[4] = 16;
104
105 fix_squares(squares); // first time to verify and fix mistakes
106 fix_squares(squares); // second time to verify that all mistakes are fixed
107
108 return EXIT_SUCCESS;
109}
110</pre>
111
112<p>Whereas this example creates an <a href="./associative_property_map.html"><code>associative_property_map</code></a> instead, and passes it to the <code>fix_squares</code> function too: </p>
113
114<pre>
115#include &lt;map&gt;
116#include &lt;boost/property_map/property_map.hpp&gt;
117
118int main()
119{
120 std::map&lt;int, int&gt; squares;
121 boost::associative_property_map&lt; std::map&lt;int, int&gt; &gt; squares_adapted(squares);
122
123 squares[1] = 1;
124 squares[2] = 3;
125 squares[4] = 15;
126
127 fix_squares(squares_adapted); // first time to verify and fix mistakes
128 fix_squares(squares_adapted); // second time to verify that all mistakes are fixed
129
130 return EXIT_SUCCESS;
131}
132</pre>
133<p>Each property map object has a set of <em>valid keys</em> for which the mapping to value objects is defined; <em>invalid</em> keys result in undefined behaviour. The property map concepts do not specify the set of valid keys. A function that uses a property map should specify the expected set of valid keys in its preconditions.</p>
134<p>
135There are four property map categories that provide different access capabilities and each has a concept definition:
136</p>
137
138<DL>
139<DT><STRONG>readable</STRONG></DT>
140<DD>
141 <p>The associated property data can only be read, using the <code>get()</code> function. It is not prescribed whether the value is returned by reference or as a copy. See documentation of the concept <a href="./ReadablePropertyMap.html">ReadablePropertyMap</a> for details.
142 </P>
143</DD>
144<DT><STRONG>writeable</STRONG></DT>
145<DD>
146 <p>The associated property can only be written to, using the <code>put()</code> function. See documentation of the concept <a href="./WritablePropertyMap.html">WritablePropertyMap</a> for details.
147</P>
148</DD>
149<DT><STRONG>read/write</STRONG></DT>
150<DD>
151 <p>The associated property can both be written and read, using the <code>get()</code> and <code>put()</code> functions. See documentation of the concept <a href="./ReadWritePropertyMap.html">ReadWritePropertyMap</a> for details.
152</P>
153</DD>
154<DT><STRONG>lvalue</STRONG></DT>
155<DD>
156 <p>The property map gives access to the value object by reference using <code>operator[]</code> or function <code>get()</code>; <code>put()</code> is also available. See documentation of the concept <a href="./LvaluePropertyMap.html">LvaluePropertyMap</a> for details.</P> </DD>
157</DL>
158
159<h2><a name="sec:property-map-tags">Property Map Category Tags</a></h2>
160
161<P>
162There is a tag struct for each of the categories of property
163maps, which is defined in the header
164<code>&lt;boost/property_map/property_map.hpp&gt;</code>.
165
166<PRE>namespace boost {
167
168 struct readable_property_map_tag { };
169
170 struct writable_property_map_tag { };
171
172 struct read_write_property_map_tag :
173 public readable_property_map_tag,
174 public writable_property_map_tag { };
175
176 struct lvalue_property_map_tag :
177 public read_write_property_map_tag { };
178
179}</PRE>
180
181<h2><a name="sec:property-map-traits">Property Map Traits</a></h2>
182
183<P>
184Tthere
185is a <code>boost::property_traits</code> class that can be used to deduce
186the types associated with a property map type: the key and value
187types, and the property map category.
188
189<PRE>namespace boost {
190
191 template &lt;typename PropertyMap&gt;
192 struct property_traits {
193 typedef typename PropertyMap::key_type key_type;
194 typedef typename PropertyMap::value_type value_type;
195 typedef typename PropertyMap::category category;
196 };
197
198}</PRE>
199
200<h2><a name="sec:property-map-types">Property Map Types</a></h2>
201
202<ul>
203 <li>pointers.<br>
204 Tthe functions <code>get()</code> and <code>put()</code> are overloaded for pointers in the header <code>&lt;boost/property_map/property_map.hpp&gt;</code>. Furthermore, there is a specialization
205of <code>boost::property_traits</code> so that pointers can be used as
206property map objects. Hence, it is
207 possible to use build in C++ pointer types as property maps;.more specifically,
208 it means that <code>T*</code> is a model of <a
209 href="./LvaluePropertyMap.html">LvaluePropertyMap</a>, of which the key
210 type is <code>std::ptrdiff_t</code>.
211 </li>
212 <li><a href="./identity_property_map.html">identity_property_map</a> </li>
213 <li><a href="./iterator_property_map.html">iterator_property_map</a></li>
214 <li><a href="./shared_array_property_map.html">shared_array_property_map</a></li>
215 <li><a href="./associative_property_map.html">associative_property_map</a></li>
216 <li><a href="./const_assoc_property_map.html">const_associative_property_map</a></li>
217 <li><a href="./vector_property_map.html">vector_property_map</a></li>
218 <li><a href="./ref_property_map.html">ref_property_map</a> </li>
219</ul>
220
221<h3>History</h3>
222
223The property map interface originated as <i>data accessors</i> in
224Dietmar K&uuml;hl's Masters Thesis on generic graph algorithms. The
225property map idea also appeared under the guise of <i>decorators</i>
226in early versions of the Generic Graph Component Library (GGCL), which
227is now the Boost Graph Library (BGL). The main motivation for the
228property map interface was to support the access of data associated
229with vertices and edges in a graph, though the applicability of
230property maps goes beyond this.
231
232<h3>Acknowledgments</h3>
233
234Thanks go to Dietmar K&uuml;hl for coming up with this mechanism, and
235thanks go to the Boost members who helped refine and improve the
236property map interface. Thanks to Dave Abrahams for managing the
237formal review of the BGL which included the property map library.
238
239<h3>Notes to Implementors</h3>
240
241Copying a property map should be inexpensive, since they are often
242passed by value.
243
244<br>
245<HR>
246<TABLE>
247<TR valign=top>
248<TD nowrap>Copyright &copy 2000-2002</TD><TD>
249<a HREF="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>, Indiana University (<A HREF="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</A>)
250</TD></TR></TABLE>
251
252</BODY>
253</HTML>
254<!-- LocalWords: ALT STL html genericity BGL ColorMap htm cpp iostream hpp hl
255 -->
256<!-- LocalWords: typename AddressMap foo fred joe joes int writeable lvalue
257 -->
258<!-- LocalWords: ReadablePropertyMap WritablePropertyMap ReadWritePropertyMap
259 -->
260<!-- LocalWords: LvaluePropertyMap struct namespace PropertyMap pmap const
261 -->
262<!-- LocalWords: val Dietmar hl's GGCL Abrahams
263 -->