1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml">
5 <meta name=
"generator" content=
6 "HTML Tidy for Linux/x86 (vers 1st March 2004), see www.w3.org" />
7 <meta http-equiv=
"Content-Type" content=
8 "text/html; charset=us-ascii" />
9 <link rel=
"stylesheet" href=
"../../../../boost.css" type=
"text/css"/>
10 <link rel=
"stylesheet" href=
"ublas.css" type=
"text/css" />
11 <script type=
"text/javascript" src=
"js/jquery-1.3.2.min.js" async=
"async" ></script>
12 <script type=
"text/javascript" src=
"js/jquery.toc-gw.js" async=
"async" ></script>
13 <title>Container Concepts
</title>
16 <h1><img src=
"../../../../boost.png" align=
"middle" />Container Concepts
</h1>
17 <div class=
"toc" id=
"toc"></div>
18 <h2><a name=
"vector"></a>Vector
</h2>
20 <p>A Vector describes common aspects of dense, packed and sparse
22 <h4>Refinement of
</h4>
23 <p><a href=
"http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible
</a>,
24 <a href=
"expression_concept.html#vector_expression">Vector Expression
</a>
25 <a href=
"#vector_expression_note">[
1]
</a>.
</p>
26 <h4>Associated types
</h4>
27 <p>In addition to the types defined by
<a href=
"expression_concept.html#vector_expression">Vector Expression
</a></p>
28 <table border=
"1" summary=
"types">
32 <td>vector_container
<V
></td>
33 <td>V must be derived from this public base type.
</td>
36 <td>Storage array
</td>
37 <td>V::array_type
</td>
39 Dense Vector ONLY. The type of underlying storage array used to store the elements. The array_type must model the
40 <a href=
"storage_concept.html"><b>Storage
</b></a> concept.
</td>
45 <table border=
"0" summary=
"notation">
48 <td><code>V
</code></td>
49 <td>A type that is a model of Vector
</td>
52 <td><code>v
</code></td>
53 <td>Objects of type
<code>V
</code></td>
56 <td><code>n, i
</code></td>
57 <td>Objects of a type convertible to
<code>size_type
</code></td>
60 <td><code>t
</code></td>
61 <td>Object of a type convertible to
<code>value_type
</code></td>
64 <td><code>p
</code></td>
65 <td>Object of a type convertible to
<code>bool
</code></td>
70 <h4>Valid expressions
</h4>
71 <p>In addition to the expressions defined in
<a href=
"http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible
</a>,
72 <a href=
"expression_concept.html#vector_expression">Vector Expression
</a> the following expressions must be valid.
</p>
73 <table border=
"1" summary=
"expressions">
78 <th>Type requirements
</th>
82 <td>Sizing constructor
</td>
83 <td><code>V v (n)
</code></td>
85 <td><code>V
</code></td>
89 <td><code>v.insert_element (i, t)
</code></td>
90 <td><code>v
</code> is mutable.
</td>
91 <td><code>void
</code></td>
95 <td><code>v.erase_element (i)
</code></td>
96 <td><code>v
</code> is mutable.
</td>
97 <td><code>void
</code></td>
101 <td><code>v.clear ()
</code></td>
102 <td><code>v
</code> is mutable.
</td>
103 <td><code>void
</code></td>
107 <td><code>v.resize (n)
</code><br />
108 <code>v.resize (n, p)
</code></td>
109 <td><code>v
</code> is mutable.
</td>
110 <td><code>void
</code></td>
114 <td><code>v.data()
</code></td>
115 <td><code>v
</code> is mutable and Dense.
</td>
116 <td><code>array_type
&</code> if
<code>v
</code> is mutable,
<code>const array_type
&</code> otherwise
</td>
120 <h4>Expression semantics
</h4>
121 <p>Semantics of an expression is defined only where it differs
122 from, or is not defined in
<a href=
123 "expression_concept.html#vector_expression">Vector Expression
</a> .
</p>
124 <table border=
"1" summary=
"semantics">
128 <th>Precondition
</th>
130 <th>Postcondition
</th>
133 <td>Sizing constructor
</td>
134 <td><code>V v (n)
</code></td>
135 <td><code>n
>=
0</code></td>
136 <td>Allocates a vector of
<code>n
</code> elements.
</td>
137 <td><code>v.size () == n
</code>.
</td>
140 <td>Element access
<a href=
"#element_access_note">[
2]
</a></td>
141 <td><code>v[n]
</code></td>
142 <td><code>0<n
>v.size()
</code></td>
143 <td>returns the n-th element in v
</td>
148 <td><code>v.insert_element (i, t)
</code></td>
149 <td><code>0 <= i
< v.size ()
</code>.
</td>
150 <td>Inserts an element at
<code>v (i)
</code> with value
<code>t
</code>.
151 The storage requirement of the Vector may be increased.
</td>
152 <td><code>v (i)
</code> is equal to
<code>t
</code>.
</td>
156 <td><code>v.erase_element (i)
</code></td>
157 <td><code>0 <= i
< v.size ()
</code></td>
158 <td>Destroys the element as
<code>v (i)
</code> and replaces it with the default
159 <code>value_type ()
</code>.
160 The storage requirement of the Vector may be decreased.
</td>
161 <td><code>v (i)
</code> is equal to
<code>value_type ()
</code>.
</td>
165 <td><code>v.clear ()
</code></td>
167 <td>Equivalent to
<br />
168 <code>for (i =
0; i
< v.size (); ++ i)
</code><br />
169 <code>v.erase_element (i);
</code></td>
174 <td><code>v.resize (n)
175 <br />v.resize (n, p)
</code></td>
177 <td>Reallocates the vector so that it can hold
<code>n
</code>
179 Erases or appends elements in order to bring the vector to the prescribed size. Appended elements copies of
<code>value_type()
</code>.
181 When
<code>p == false
</code> then existing elements are not preserved and elements will not appended as normal. Instead the vector is in the same state as that after an equivalent sizing constructor.
</td>
182 <td><code>v.size () == n
</code>.
</td>
186 <td><code>v.data()
</code></td>
188 <td>Returns a reference to the underlying dense storage.
</td>
192 <h4>Complexity guarantees
</h4>
193 <p>The run-time complexity of the sizing constructor is linear in
194 the vector's size.
</p>
195 <p>The run-time complexity of insert_element and erase_element is specific for the
196 Vector model and it depends on increases/decreases in storage requirements.
</p>
197 <p>The run-time complexity of resize is linear in the vector's
202 <li><code>vector
</code>,
<code>bounded_vector
</code>,
<code>c_vector
</code></li>
203 <li><code>unit_vector
</code>,
<code>zero_vector
</code>,
<code>scalar_vector
</code></li>
204 <li><code>mapped_vector;
</code>,
<code>compressed_vector
</code>,
<code>coordinate_vector
</code></li>
207 <p><a name=
"vector_expression_note">[
1]
</a>
208 As a user you need not care about
<tt>Vector
</tt> being a refinement of the VectorExpression. Being a refinement of the VectorExpression is only important for the template-expression engine but not the user.
</p>
209 <p><a name=
"element_access_note">[
2]
</a>
210 The
<code>operator[]
</code> is added purely for convenience
211 and compatibility with the
<code>std::vector
</code>. In uBLAS however,
212 generally
<code>operator()
</code> is used for indexing because this can be
213 used for both vectors and matrices.
</p>
214 <h2><a name=
"matrix"></a>Matrix
</h2>
216 <p>A Matrix describes common aspects of dense, packed and sparse
218 <h4>Refinement of
</h4>
219 <p><a href=
"http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible
</a>,
220 <a href=
"expression_concept.html#matrix_expression">Matrix Expression
</a>
221 <a href=
"#matrix_expression_note">[
1]
</a>
223 <h4>Associated types
</h4>
224 <p>In addition to the types defined by
<a href=
"expression_concept.html#matrix_expression">Matrix Expression
</a></p>
225 <table border=
"1" summary=
"types">
229 <td>matrix_container
<M
></td>
230 <td>M must be derived from this public base type.
</td>
233 <td>Storage array
</td>
234 <td>M::array_type
</td>
235 <td>Dense Matrix ONLY. The type of underlying storage array used to store the elements. The array_type must model
236 the
<a href=
"storage_concept.html"><b>Storage
</b></a> concept.
</td>
241 <table border=
"0" summary=
"notation">
244 <td><code>M
</code></td>
245 <td>A type that is a model of Matrix
</td>
248 <td><code>m
</code></td>
249 <td>Objects of type
<code>M
</code></td>
252 <td><code>n1, n2, i, j
</code></td>
253 <td>Objects of a type convertible to
<code>size_type
</code></td>
256 <td><code>t
</code></td>
257 <td>Object of a type convertible to
<code>value_type
</code></td>
260 <td><code>p
</code></td>
261 <td>Object of a type convertible to
<code>bool
</code></td>
266 <h4>Valid expressions
</h4>
267 <p>In addition to the expressions defined in
<a href=
268 "expression_concept.html#matrix_expression">Matrix Expression
</a> the
269 following expressions must be valid.
</p>
270 <table border=
"1" summary=
"expressions">
275 <th>Type requirements
</th>
279 <td>Sizing constructor
</td>
280 <td><code>M m (n1, n2)
</code></td>
282 <td><code>M
</code></td>
286 <td><code>m.insert_element (i, j, t)
</code></td>
287 <td><code>m
</code> is mutable.
</td>
288 <td><code>void
</code></td>
292 <td><code>m.erase_element (i, j)
</code></td>
293 <td><code>m
</code> is mutable.
</td>
294 <td><code>void
</code></td>
298 <td><code>m.clear ()
</code></td>
299 <td><code>m
</code> is mutable.
</td>
300 <td><code>void
</code></td>
304 <td><code>m.resize (n1, n2)
</code><br />
305 <code>m.resize (n1, n2, p)
</code></td>
306 <td><code>m
</code> is mutable.
</td>
307 <td><code>void
</code></td>
311 <td><code>m.data()
</code></td>
312 <td><code>m
</code> is mutable and Dense.
</td>
313 <td><code>array_type
&</code> if
<code>m
</code> is mutable,
<code>const array_type
&</code> otherwise
</td>
317 <h4>Expression semantics
</h4>
318 <p>Semantics of an expression is defined only where it differs
319 from, or is not defined in
<a href=
320 "expression_concept.html#matrix_expression">Matrix Expression
</a> .
</p>
321 <table border=
"1" summary=
"semantics">
326 <th>Precondition
</th>
328 <th>Postcondition
</th>
331 <td>Sizing constructor
</td>
332 <td><code>M m (n1, n2)
</code></td>
333 <td><code>n1
>=
0</code> and
<code>n2
>=
0</code></td>
334 <td>Allocates a matrix of
<code>n1
</code> rows and
<code>n2
</code>
336 <td><code>m.size1 () == n1
</code> and
<code>m.size2 () ==
341 <td><code>m.insert_element (i, j, t)
</code></td>
342 <td><code>0 <= i
< m.size1 ()
</code>,
<br />
343 <code>0 <= j
< m.size2 ()
</code>.
</td>
344 <td>Inserts an element at
<code>m (i, j)
</code> with value
<code>t
</code>.
345 The storage requirement of the Matrix may be increased.
</td>
346 <td><code>m (i, j)
</code> is equal to
<code>t
</code>.
</td>
350 <td><code>m.erase_element (i, j)
</code></td>
351 <td><code>0 <= i
< m.size1 ()
</code>and
<code><br />
352 0 <= j
< m.size2
</code></td>
353 <td>Destroys the element as
<code>m (i, j)
</code> and replaces it with the default
354 <code>value_type ()
</code>.
355 The storage requirement of the Matrix may be decreased.
</td>
356 <td><code>m (i, j)
</code> is equal to
<code>value_type ()
</code>.
</td>
360 <td><code>m.clear ()
</code></td>
362 <td>Equivalent to
<br />
363 <code>for (i =
0; i
< m.size1 (); ++ i)
</code><br />
364 <code>for (j =
0; j
< m.size2 (); ++ j)
</code><br />
365 <code>m.erase_element (i, j);
</code></td>
370 <td><code>m.resize (n1, n2)
375 <td>Reallocate the matrix so that it can hold
<code>n1
</code> rows
376 and
<code>n2
</code> columns.
<br />
377 Erases or appends elements in order to bring the matrix to the
378 prescribed size. Appended elements are
<code>value_type()
</code>
380 When
<code>p == false
</code> then existing elements are not preserved and elements will not appended as normal. Instead the matrix is in the same state as that after an equivalent sizing constructor.
</td>
381 <td><code>m.size1 () == n1
</code> and
<code>m.size2 () == n2
</code>.
</td>
385 <td><code>m.data()
</code></td>
387 <td>Returns a reference to the underlying dense storage.
</td>
391 <h4>Complexity guarantees
</h4>
392 <p>The run-time complexity of the sizing constructor is quadratic
393 in the matrix's size.
</p>
394 <p>The run-time complexity of insert_element and erase_element is specific for the
395 Matrix model and it depends on increases/decreases in storage requirements.
</p>
396 <p>The run-time complexity of resize is quadratic in the matrix's
401 <li><code>matrix
</code>,
<code>bounded_matrix
</code>,
<code>c_matrix
</code></li>
402 <li><code>identity_matrix
</code> ,
<code>zero_matrix
</code> ,
<code>scalar_matrix
</code></li>
403 <li><code>triangular_matrix
</code> ,
<code>symmetric_matrix
</code> ,
<code>banded_matrix
</code></li>
404 <li><code>mapped_matrix
</code> ,
<code>compressed_matrix
</code> ,
<code>coordinate_matrix
</code></li>
407 <p><a name=
"matrix_expression_note">[
1]
</a>
408 As a user you need not care about
<tt>Matrix
</tt> being a refinement of the MatrixExpression. Being a refinement of the MatrixExpression is only important for the template-expression engine but not the user.
</p>
410 <p>Copyright (
©)
2000-
2002 Joerg Walter, Mathias Koch
<br />
411 Use, modification and distribution are subject to the
412 Boost Software License, Version
1.0.
413 (See accompanying file LICENSE_1_0.txt
414 or copy at
<a href=
"http://www.boost.org/LICENSE_1_0.txt">
415 http://www.boost.org/LICENSE_1_0.txt
418 <script type=
"text/javascript">