]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <HTML> |
2 | <!-- | |
3 | Copyright (c) Jeremy Siek, Lie-Quan Lee, and Andrew Lumsdaine 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>Vector Property Map</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 | ||
19 | <H2><A NAME="sec:vector-property-map"></A> | |
20 | </h2> | |
21 | <PRE> | |
22 | template<typename T, typename IndexMap = identity_property_map> | |
23 | class vector_property_map; | |
24 | </PRE> | |
25 | ||
26 | <P> | |
27 | This property map is used to efficiently store properties for a variable | |
28 | number of elements. It's somewhere between <a | |
29 | href="associative_property_map.html">associative_property_map</a> and | |
30 | <a href="iterator_property_map.html">iterator_property_map</a>. The latter | |
31 | is very fast, but requires that the number of stored elements is known | |
32 | when creating property map. The former does not have this requirement, but | |
33 | is slower, and requires stored elements to be comparable. | |
34 | ||
35 | <p> | |
36 | The <tt>vector_property_map</tt> uses mapping from key to indices, | |
37 | and allows to add new elements. It accoplishes this by storing values | |
38 | in a vector, which is resized on demand. | |
39 | ||
40 | <p> | |
41 | Note that <tt>vector_property_map</tt> does not provide reference/pointer | |
42 | stability for stored values. | |
43 | ||
44 | <h3>Example</h3> | |
45 | ||
46 | <a href="../example/example3.cpp">example3.cpp</a>: | |
47 | ||
48 | <p> | |
49 | <pre> | |
50 | #include <boost/property_map/vector_property_map.hpp> | |
51 | #include <string> | |
52 | #include <iostream> | |
53 | ||
54 | int main() | |
55 | { | |
56 | boost::vector_property_map<std::string> m; | |
57 | ||
58 | // Assign string to '4'. | |
59 | m[4] = "e"; | |
60 | std::cout << "'" << m[4] << "'\n"; | |
61 | ||
62 | // Grab string from '10'. Since none is associated, | |
63 | // "" will be returned. | |
64 | std::cout << "'" << m[10] << "'\n"; | |
65 | } | |
66 | </pre> | |
67 | ||
68 | <H3>Where Defined</H3> | |
69 | ||
70 | <P> | |
71 | <a href="../../../boost/property_map/vector_property_map.hpp"><TT>boost/property_map/vector_property_map.hpp</TT></a> | |
72 | ||
73 | <p> | |
74 | <H3>Model Of</H3> | |
75 | ||
76 | <a href="./LvaluePropertyMap.html">Lvalue Property Map</a> | |
77 | ||
78 | <P> | |
79 | ||
80 | <H3>Template Parameters</H3> | |
81 | ||
82 | <P> | |
83 | ||
84 | <TABLE border> | |
85 | <TR> | |
86 | <th>Parameter</th><th>Description</th><th>Default</th> | |
87 | </tr> | |
88 | ||
89 | ||
90 | <TR> | |
91 | <TD><TT>T</TT></TD> | |
92 | <TD>The type of property value. Must be both <a | |
93 | href="http://www.sgi.com/tech/stl/Assignable.html">Assignable</a> | |
94 | and <a | |
95 | href="http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible</a>. | |
96 | </TD> | |
97 | <TD> </td> | |
98 | </tr> | |
99 | ||
100 | <TR> | |
101 | <TD><TT>IndexMap</TT></TD> <TD>Must be a model of <a | |
102 | href="./ReadablePropertyMap.html">Readable Property Map</a> | |
103 | and the value type must be convertible to | |
104 | <tt>std::vector<T>::size_type</tt>.</TD> | |
105 | <TD><a href="identity_property_map.html">identity_property_map</a></TD> | |
106 | </TR> | |
107 | ||
108 | </TABLE> | |
109 | <P> | |
110 | ||
111 | <H3>Members</H3> | |
112 | ||
113 | <P> | |
114 | In addition to the methods and functions required by <a | |
115 | href="./LvaluePropertyMap.html">Lvalue Property Map</a>, this | |
116 | class has the following members. | |
117 | ||
118 | <hr> | |
119 | ||
120 | <pre> | |
121 | vector_property_map(const IndexMap& index = IndexMap()) | |
122 | </pre> | |
123 | Constructor which takes an index map. | |
124 | ||
125 | <hr> | |
126 | ||
127 | <pre> | |
128 | vector_property_map(unsigned initial_size, const IndexMap& index = IndexMap()) | |
129 | </pre> | |
130 | This constructor version allows to specify maximum index of element | |
131 | that will be stored. Correct number will improve performance, but semantic | |
132 | is always the same. | |
133 | ||
134 | <hr> | |
135 | ||
136 | <pre> | |
137 | vector_property_map(const vector_property_map&) | |
138 | </pre> | |
139 | Copy constructor. The copy will share the same data and changes | |
140 | made to it will affect original property map. | |
141 | ||
142 | <hr> | |
143 | ||
144 | <pre> | |
145 | vector_property_map& operator=(const vector_property_map&) | |
146 | </pre> | |
147 | Assignment operator. The semantic is the same as for copy constructor. | |
148 | ||
149 | <hr> | |
150 | ||
151 | <pre> | |
152 | reference operator[](const key_type& v) const | |
153 | </pre> | |
154 | The operator bracket for property access. | |
155 | ||
156 | <hr> | |
157 | ||
158 | <pre> | |
159 | std::vector<T>::iterator storage_begin() | |
160 | std::vector<T>::iterator storage_end() | |
161 | std::vector<T>::const_iterator storage_begin() | |
162 | std::vector<T>::const_iterator storage_end() | |
163 | </pre> | |
164 | ||
165 | <p>This group of methods gives access to begin and end iterators of the | |
166 | underlying vector.</p> | |
167 | ||
168 | <p><b>Rationale:</b> The methods are handy, for example, when it's needed to | |
169 | specify a single value for all elements in a freshly created property map. The | |
170 | methods are not called simply "begin" and "end" since | |
171 | conceptually, <tt>vector_property_map</tt> is unbounded map, and has no end | |
172 | iterator. The direct access to the underlying method is not provided, since | |
173 | it would decrease encapsulation and make future performance tuning dangerous. | |
174 | ||
175 | <p><b>Acknolegements:</b> Matthias Troyer suggested adding those functions. | |
176 | ||
177 | <hr> | |
178 | ||
179 | <pre> | |
180 | void reserve(unsigned size) | |
181 | </pre> | |
182 | Reserve the space for storing elements with maximum index of 'size'. Unless | |
183 | element with greater index is accesses, all accesses will be take O(1) time. | |
184 | ||
185 | ||
186 | <hr> | |
187 | ||
188 | <h3>Non-Member functions</h3> | |
189 | ||
190 | <hr> | |
191 | ||
192 | <pre> | |
193 | template<typename T, typename IndexMap> | |
194 | vector_property_map<T, IndexMap> | |
195 | make_vector_property_map(IndexMap index) | |
196 | { | |
197 | return vector_property_map<T, IndexMap>(index); | |
198 | } | |
199 | </pre> | |
200 | A function for conveniently creating a vector property map. | |
201 | ||
202 | <br> | |
203 | <HR> | |
204 | <TABLE> | |
205 | <TR valign=top> | |
206 | <TD nowrap>Copyright © 2002</TD><TD> | |
207 | <a HREF="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>, | |
208 | Indiana University (<A | |
209 | HREF="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</A>)<br> | |
210 | <A HREF="http://www.boost.org/people/liequan_lee.htm">Lie-Quan Lee</A>, Indiana University (<A HREF="mailto:llee1@osl.iu.edu">llee1@osl.iu.edu</A>)<br> | |
211 | <A HREF="http://www.osl.iu.edu/~lums">Andrew Lumsdaine</A>, | |
212 | Indiana University (<A | |
213 | HREF="mailto:lums@osl.iu.edu">lums@osl.iu.edu</A>) | |
214 | </TD></TR> | |
215 | <tr> | |
216 | <td nowrap>Copyright © 2003</td><td>Vladimir Prus</td> | |
217 | </tr> | |
218 | </TABLE> | |
219 | ||
220 | </BODY> | |
221 | </HTML> |