Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_33_1/libs/array/doc/array.xml @ 12

Last change on this file since 12 was 12, checked in by landauf, 17 years ago
added boost
File size: 21.4 KB

Line
1	<?xml version="1.0" encoding="utf-8"?>
2	<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
3	"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
4	<library name="Array" dirname="array" id="array" last-revision="$Date: 2005/12/01 04:52:03 $">
5	<libraryinfo>
6	<author>
7	<firstname>Nicolai</firstname>
8	<surname>Josuttis</surname>
9	</author>
10
11	<copyright>
12	<year>2001</year>
13	<year>2002</year>
14	<year>2003</year>
15	<year>2004</year>
16	<holder>Nicolai M. Josuttis</holder>
17	</copyright>
18
19	<legalnotice>
20	<para>Permission to copy, use, modify, sell and distribute this
21	software is granted provided this copyright notice appears in
22	all copies. This software is provided "as is" without express or
23	implied warranty, and with no claim as to its suitability for
24	any purpose.</para>
25	</legalnotice>
26
27	<librarypurpose>STL compliant container wrapper for arrays of constant size</librarypurpose>
28	<librarycategory name="category:containers"/>
29	</libraryinfo>
30
31	<title>Boost.Array</title>
32
33	<section id="array.intro">
34	<title>Introduction</title>
35
36	<using-namespace name="boost"/>
37	<using-class name="array"/>
38
39	<para>The C++ Standard Template Library STL as part of the C++
40	Standard Library provides a framework for processing algorithms on
41	different kind of containers. However, ordinary arrays don't
42	provide the interface of STL containers (although, they provide
43	the iterator interface of STL containers).</para>
44
45	<para>As replacement for ordinary arrays, the STL provides class
46	<code><classname>std::vector</classname></code>. However,
47	<code><classname>std::vector<></classname></code> provides
48	the semantics of dynamic arrays. Thus, it manages data to be able
49	to change the number of elements. This results in some overhead in
50	case only arrays with static size are needed.</para>
51
52	<para>In his book, <emphasis>Generic Programming and the
53	STL</emphasis>, Matthew H. Austern introduces a useful wrapper
54	class for ordinary arrays with static size, called
55	<code>block</code>. It is safer and has no worse performance than
56	ordinary arrays. In <emphasis>The C++ Programming
57	Language</emphasis>, 3rd edition, Bjarne Stroustrup introduces a
58	similar class, called <code>c_array</code>, which I (<ulink
59	url="http://www.josuttis.com">Nicolai Josuttis</ulink>) present
60	slightly modified in my book <emphasis>The C++ Standard Library -
61	A Tutorial and Reference</emphasis>, called
62	<code>carray</code>. This is the essence of these approaches
63	spiced with many feedback from <ulink
64	url="http://www.boost.org">boost</ulink>.</para>
65
66	<para>After considering different names, we decided to name this
67	class simply <code><classname>array</classname></code>.</para>
68
69	<para>Note that this class is suggested to be part of the next
70	Technical Report, which will extend the C++ Standard (see
71	<ulink url="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1548.htm">http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1548.htm</ulink>).</para>
72
73	<para>Class <code><classname>array</classname></code> fulfills most
74	but not all of the requirements of "reversible containers" (see
75	Section 23.1, [lib.container.requirements] of the C++
76	Standard). The reasons array is not an reversible STL container is
77	because:
78	<itemizedlist spacing="compact">
79	<listitem><simpara>No constructors are provided.</simpara></listitem>
80	<listitem><simpara>Elements may have an undetermined initial value (see <xref linkend="array.rationale"/>).</simpara></listitem>
81	<listitem><simpara><functionname>swap</functionname>() has no constant complexity.</simpara></listitem>
82	<listitem><simpara><methodname>size</methodname>() is always constant, based on the second template argument of the type.</simpara></listitem>
83	<listitem><simpara>The container provides no allocator support.</simpara></listitem>
84	</itemizedlist>
85	</para>
86
87	<para>It doesn't fulfill the requirements of a "sequence" (see Section 23.1.1, [lib.sequence.reqmts] of the C++ Standard), except that:
88	<itemizedlist spacing="compact">
89	<listitem><simpara><methodname>front</methodname>() and <methodname>back</methodname>() are provided.</simpara></listitem>
90	<listitem><simpara><methodname>operator[]</methodname> and <methodname>at</methodname>() are provided.</simpara></listitem>
91	</itemizedlist>
92	</para>
93	</section>
94
95	<library-reference>
96	<header name="boost/array.hpp">
97	<namespace name="boost">
98	<class name="array">
99	<template>
100	<template-type-parameter name="T"/>
101	<template-nontype-parameter name="N">
102	<type>std::size_t</type>
103	</template-nontype-parameter>
104	</template>
105
106	<purpose><para>STL compliant container wrapper for arrays of constant size</para></purpose>
107	<typedef name="value_type">
108	<type>T</type>
109	</typedef>
110	<typedef name="iterator">
111	<type>T*</type>
112	</typedef>
113	<typedef name="const_iterator">
114	<type>const T*</type>
115	</typedef>
116	<typedef name="reverse_iterator">
117	<type><classname>std::reverse_iterator</classname><iterator></type>
118	</typedef>
119	<typedef name="const_reverse_iterator">
120	<type><classname>std::reverse_iterator</classname><const_iterator></type>
121	</typedef>
122	<typedef name="reference">
123	<type>T&</type>
124	</typedef>
125	<typedef name="const_reference">
126	<type>const T&</type>
127	</typedef>
128	<typedef name="size_type">
129	<type>std::size_t</type>
130	</typedef>
131	<typedef name="difference_type">
132	<type>std::ptrdiff_t</type>
133	</typedef>
134
135	<static-constant name="static_size">
136	<type>size_type</type>
137	<default>N</default>
138	</static-constant>
139
140	<copy-assignment>
141	<template>
142	<template-type-parameter name="U"/>
143	</template>
144	<parameter name="other">
145	<paramtype>const <classname>array</classname><U, N>&</paramtype>
146	</parameter>
147	<effects><simpara><code>std::copy(rhs.<methodname>begin</methodname>(),rhs.<methodname>end</methodname>(), <methodname>begin</methodname>())</code></simpara></effects>
148	</copy-assignment>
149
150	<method-group name="iterator support">
151	<overloaded-method name="begin">
152	<signature>
153	<type>iterator</type>
154	</signature>
155	<signature cv="const">
156	<type>const_iterator</type>
157	</signature>
158
159	<returns><simpara>iterator for the first element</simpara></returns>
160	<throws><simpara>will not throw</simpara></throws>
161	</overloaded-method>
162
163	<overloaded-method name="end">
164	<signature>
165	<type>iterator</type>
166	</signature>
167	<signature cv="const">
168	<type>const_iterator</type>
169	</signature>
170
171	<returns><simpara>iterator for position after the last element</simpara></returns>
172	<throws><simpara>will not throw</simpara></throws>
173	</overloaded-method>
174	</method-group>
175
176	<method-group name="reverse iterator support">
177	<overloaded-method name="rbegin">
178	<signature>
179	<type>reverse_iterator</type>
180	</signature>
181	<signature cv="const">
182	<type>const_reverse_iterator</type>
183	</signature>
184
185	<returns><simpara>reverse iterator for the first element of reverse iteration</simpara></returns>
186	</overloaded-method>
187
188	<overloaded-method name="rend">
189	<signature>
190	<type>reverse_iterator</type>
191	</signature>
192	<signature cv="const">
193	<type>const_reverse_iterator</type>
194	</signature>
195
196	<returns><simpara>reverse iterator for position after the last element in reverse iteration</simpara></returns>
197	</overloaded-method>
198	</method-group>
199
200	<method-group name="capacity">
201	<method name="size">
202	<type>size_type</type>
203	<returns><simpara><code>N</code></simpara></returns>
204	</method>
205	<method name="empty">
206	<type>bool</type>
207	<returns><simpara><code>N==0</code></simpara></returns>
208	<throws><simpara>will not throw</simpara></throws>
209	</method>
210	<method name="max_size">
211	<type>size_type</type>
212	<returns><simpara><code>N</code></simpara></returns>
213	<throws><simpara>will not throw</simpara></throws>
214	</method>
215	</method-group>
216
217	<method-group name="element access">
218	<overloaded-method name="operator[]">
219	<signature>
220	<type>reference</type>
221	<parameter name="i">
222	<paramtype>size_type</paramtype>
223	</parameter>
224	</signature>
225
226	<signature cv="const">
227	<type>const_reference</type>
228	<parameter name="i">
229	<paramtype>size_type</paramtype>
230	</parameter>
231	</signature>
232
233	<requires><simpara><code>i < N</code></simpara></requires>
234	<returns><simpara>element with index <code>i</code></simpara></returns>
235	<throws><simpara>will not throw.</simpara></throws>
236	</overloaded-method>
237
238	<overloaded-method name="at">
239	<signature>
240	<type>reference</type>
241	<parameter name="i">
242	<paramtype>size_type</paramtype>
243	</parameter>
244	</signature>
245
246	<signature cv="const">
247	<type>const_reference</type>
248	<parameter name="i">
249	<paramtype>size_type</paramtype>
250	</parameter>
251	</signature>
252
253	<returns><simpara>element with index <code>i</code></simpara></returns>
254	<throws><simpara><code><classname>std::range_error</classname></code> if <code>i >= N</code></simpara></throws>
255	</overloaded-method>
256
257	<overloaded-method name="front">
258	<signature>
259	<type>reference</type>
260	</signature>
261	<signature cv="const">
262	<type>const_reference</type>
263	</signature>
264	<requires><simpara><code>N > 0</code></simpara></requires>
265	<returns><simpara>the first element</simpara></returns>
266	<throws><simpara>will not throw</simpara></throws>
267	</overloaded-method>
268
269	<overloaded-method name="back">
270	<signature>
271	<type>reference</type>
272	</signature>
273	<signature cv="const">
274	<type>const_reference</type>
275	</signature>
276	<requires><simpara><code>N > 0</code></simpara></requires>
277	<returns><simpara>the last element</simpara></returns>
278	<throws><simpara>will not throw</simpara></throws>
279	</overloaded-method>
280
281	<method name="data" cv="const">
282	<type>const T*</type>
283	<returns><simpara><code>elems</code></simpara></returns>
284	<throws><simpara>will not throw</simpara></throws>
285	</method>
286
287	<method name="c_array">
288	<type>T*</type>
289	<returns><simpara><code>elems</code></simpara></returns>
290	<throws><simpara>will not throw</simpara></throws>
291	</method>
292	</method-group>
293
294	<method-group name="modifiers">
295	<method name="swap">
296	<type>void</type>
297	<parameter name="other">
298	<paramtype><classname>array</classname><T, N>&</paramtype>
299	</parameter>
300	<effects><simpara><code>std::swap_ranges(<methodname>begin</methodname>(), <methodname>end</methodname>(), other.<methodname>begin</methodname>())</code></simpara></effects>
301	<complexity><simpara>linear in <code>N</code></simpara></complexity>
302	</method>
303	<method name="assign">
304	<type>void</type>
305	<parameter name="value">
306	<paramtype>const T&</paramtype>
307	</parameter>
308	<effects><simpara><code>std::fill_n(<methodname>begin</methodname>(), N, value)</code></simpara></effects>
309	</method>
310	</method-group>
311
312	<data-member name="elems[N]"> <!-- HACK -->
313	<type>T</type>
314	</data-member>
315
316	<free-function-group name="specialized algorithms">
317	<function name="swap">
318	<template>
319	<template-type-parameter name="T"/>
320	<template-nontype-parameter name="N">
321	<type>std::size_t</type>
322	</template-nontype-parameter>
323	</template>
324
325	<type>void</type>
326
327	<parameter name="x">
328	<paramtype><classname>array</classname><T, N>&</paramtype>
329	</parameter>
330	<parameter name="y">
331	<paramtype><classname>array</classname><T, N>&</paramtype>
332	</parameter>
333
334	<effects><simpara><code>x.<methodname>swap</methodname>(y)</code></simpara></effects>
335	<throws><simpara>will not throw.</simpara></throws>
336	</function>
337	</free-function-group>
338
339	<free-function-group name="comparisons">
340	<function name="operator==">
341	<template>
342	<template-type-parameter name="T"/>
343	<template-nontype-parameter name="N">
344	<type>std::size_t</type>
345	</template-nontype-parameter>
346	</template>
347
348	<type>bool</type>
349
350	<parameter name="x">
351	<paramtype>const <classname>array</classname><T, N>&</paramtype>
352	</parameter>
353	<parameter name="y">
354	<paramtype>const <classname>array</classname><T, N>&</paramtype>
355	</parameter>
356
357	<returns><simpara><code>std::equal(x.<methodname>begin</methodname>(), x.<methodname>end</methodname>(), y.<methodname>begin</methodname>())</code></simpara>
358	</returns>
359	</function>
360
361	<function name="operator!=">
362	<template>
363	<template-type-parameter name="T"/>
364	<template-nontype-parameter name="N">
365	<type>std::size_t</type>
366	</template-nontype-parameter>
367	</template>
368
369	<type>bool</type>
370
371	<parameter name="x">
372	<paramtype>const <classname>array</classname><T, N>&</paramtype>
373	</parameter>
374	<parameter name="y">
375	<paramtype>const <classname>array</classname><T, N>&</paramtype>
376	</parameter>
377
378	<returns><simpara><code>!(x == y)</code></simpara>
379	</returns>
380	</function>
381
382	<function name="operator<">
383	<template>
384	<template-type-parameter name="T"/>
385	<template-nontype-parameter name="N">
386	<type>std::size_t</type>
387	</template-nontype-parameter>
388	</template>
389
390	<type>bool</type>
391
392	<parameter name="x">
393	<paramtype>const <classname>array</classname><T, N>&</paramtype>
394	</parameter>
395	<parameter name="y">
396	<paramtype>const <classname>array</classname><T, N>&</paramtype>
397	</parameter>
398
399	<returns><simpara><code>std::lexicographical_compare(x.<methodname>begin</methodname>(), x.<methodname>end</methodname>(), y.<methodname>begin</methodname>(), y.<methodname>end</methodname>())</code></simpara>
400	</returns>
401	</function>
402
403	<function name="operator>">
404	<template>
405	<template-type-parameter name="T"/>
406	<template-nontype-parameter name="N">
407	<type>std::size_t</type>
408	</template-nontype-parameter>
409	</template>
410
411	<type>bool</type>
412
413	<parameter name="x">
414	<paramtype>const <classname>array</classname><T, N>&</paramtype>
415	</parameter>
416	<parameter name="y">
417	<paramtype>const <classname>array</classname><T, N>&</paramtype>
418	</parameter>
419
420	<returns><simpara><code>y < x</code></simpara></returns>
421	</function>
422
423	<function name="operator<=">
424	<template>
425	<template-type-parameter name="T"/>
426	<template-nontype-parameter name="N">
427	<type>std::size_t</type>
428	</template-nontype-parameter>
429	</template>
430
431	<type>bool</type>
432
433	<parameter name="x">
434	<paramtype>const <classname>array</classname><T, N>&</paramtype>
435	</parameter>
436	<parameter name="y">
437	<paramtype>const <classname>array</classname><T, N>&</paramtype>
438	</parameter>
439
440	<returns><simpara><code>!(y < x)</code></simpara></returns>
441	</function>
442
443	<function name="operator>=">
444	<template>
445	<template-type-parameter name="T"/>
446	<template-nontype-parameter name="N">
447	<type>std::size_t</type>
448	</template-nontype-parameter>
449	</template>
450
451	<type>bool</type>
452
453	<parameter name="x">
454	<paramtype>const <classname>array</classname><T, N>&</paramtype>
455	</parameter>
456	<parameter name="y">
457	<paramtype>const <classname>array</classname><T, N>&</paramtype>
458	</parameter>
459
460	<returns><simpara><code>!(x < y)</code></simpara></returns>
461	</function>
462	</free-function-group>
463	</class>
464	</namespace>
465	</header>
466	</library-reference>
467
468	<section id="array.rationale">
469	<title>Design Rationale</title>
470
471	<para>There was an important design tradeoff regarding the
472	constructors: We could implement array as an "aggregate" (see
473	Section 8.5.1, [dcl.init.aggr], of the C++ Standard). This would
474	mean:
475	<itemizedlist>
476	<listitem><simpara>An array can be initialized with a
477	brace-enclosing, comma-separated list of initializers for the
478	elements of the container, written in increasing subscript
479	order:</simpara>
480
481	<programlisting><classname>boost::array</classname><int,4> a = { { 1, 2, 3 } };</programlisting>
482
483	<simpara>Note that if there are fewer elements in the
484	initializer list, then each remaining element gets
485	default-initialized (thus, it has a defined value).</simpara>
486	</listitem></itemizedlist></para>
487
488	<para>However, this approach has its drawbacks: <emphasis
489	role="bold"> passing no initializer list means that the elements
490	have an indetermined initial value</emphasis>, because the rule says
491	that aggregates may have:
492	<itemizedlist>
493	<listitem><simpara>No user-declared constructors.</simpara></listitem>
494	<listitem><simpara>No private or protected non-static data members.</simpara></listitem>
495	<listitem><simpara>No base classes.</simpara></listitem>
496	<listitem><simpara>No virtual functions.</simpara></listitem>
497	</itemizedlist>
498	</para>
499
500	<para>Nevertheless, The current implementation uses this approach.</para>
501
502	<para>Note that for standard conforming compilers it is possible to
503	use fewer braces (according to 8.5.1 (11) of the Standard). That is,
504	you can initialize an array as follows:</para>
505
506	<programlisting>
507	<classname>boost::array</classname><int,4> a = { 1, 2, 3 };
508	</programlisting>
509
510	<para>I'd appreciate any constructive feedback. <emphasis
511	role="bold">Please note: I don't have time to read all boost
512	mails. Thus, to make sure that feedback arrives to me, please send
513	me a copy of each mail regarding this class.</emphasis></para>
514
515	<para>The code is provided "as is" without expressed or implied
516	warranty.</para>
517
518	</section>
519
520	<section id="array.more.info">
521	<title>For more information...</title>
522	<para>To find more details about using ordinary arrays in C++ and
523	the framework of the STL, see e.g.
524
525	<literallayout>The C++ Standard Library - A Tutorial and Reference
526	by Nicolai M. Josuttis
527	Addison Wesley Longman, 1999
528	ISBN 0-201-37926-0</literallayout>
529	</para>
530
531	<para><ulink url="http://www.josuttis.com/">Home Page of Nicolai
532	Josuttis</ulink></para>
533	</section>
534
535	<section id="array.ack">
536	<title>Acknowledgements</title>
537
538	<para>Doug Gregor ported the documentation to the BoostBook format.</para>
539	</section>
540
541	<!-- Notes:
542	empty() should return N != 0
543	size(), empty(), max_size() should be const
544	-->
545
546	</library>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: