boostorg/array
1
0
Fork 1
mirror of https://github.com/boostorg/array.git synced 2025-07-14 13:16:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

initial checkin of Nico's array library

Browse Source 
[SVN r7678]
This commit is contained in:
Jeremy Siek
2000-08-02 18:15:32 +00:00
parent 7eb947be47
commit 51cd7d0ca5
13 changed files with 1078 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
array.htm Normal file
View File

@ -0,0 +1,314 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Keywords" content="array, block, carray, c_array, array wrapper, adapter, adaptor, STL, C++ Standard Library, array.hpp">
<title>array.hpp, an STL Array Wrapper</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#186ABF">
<font face="Arial, Helvetica, sans-serif">&nbsp; </font>
<table width="100%" height="40">
<tr>
<td BGCOLOR="#DDDDDD"><b><font face="Arial,helvetica" color="#000000" size="+1">Class
<font face="Courier New, Courier, mono">array</font>, an STL Container (as
Wrapper) for Arrays of Constant Size</font></b></td>
</tr>
</table>
<p><font face="Arial, Helvetica, sans-serif" size="-1">The C++ Standard Template
Library STL as part of the C++ Standard Library provides a framework for processing
algorithms on different kind of containers. However, ordinary arrays don't provide
the interface of STL containers (although, they provide the iterator interface
of STL containers).</font>
<p><font face="Arial, Helvetica, sans-serif" size="-1">As replacement for ordinary
arrays, the STL provides class <font face="Courier New, Courier, mono">vector&lt;&gt;</font>.
However, <font face="Courier New, Courier, mono">vector&lt;&gt;</font> provides
the semantics of dynamic arrays. Thus, it manages data to be able to change
the number of elements. This results in some overhead in case only arrays with
static size are needed.</font>
<p><font face="Arial, Helvetica, sans-serif" size="-1">In his book, <i>Generic
Programming and the STL</i>, Matthew H. Austern introduces a useful wrapper
class for ordinary arrays with static size, called <font face="Courier New, Courier, mono"><b>block</b></font>.
It is safer and has no worse performance than ordinary arrays. In <i>The C++
Programming Language</i>, 3rd edition, Bjarne Stroustrup introduces a similar
class, called <font face="Courier New, Courier, mono"><b>c_array</b></font>,
which I (<a href="http://www.josuttis.com">Nicolai Josuttis</a>) present slightly
modified in my book <i>The C++ Standard Library - A Tutorial and Reference</i>,
called <font face="Courier New, Courier, mono"><b>carray</b></font>. This is
the essence of these approaches spiced with many feedback from <a href="http://www.boost.org">boost</a>.</font>
<p><font face="Arial, Helvetica, sans-serif" size="-1">After considering different
names, we decided to name this class simply <font face="Courier New, Courier, mono"><b>array</b></font>.</font>
<p><font face="Arial, Helvetica, sans-serif" size="-1">The class provides the
following interface:</font>
<table border="0">
<tr>
<td><font face="Arial, Helvetica, sans-serif" size="-1"><b>Types:</b></font></td>
<td><font size="-1"></font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">value_type</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">type of the elements</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">iterator</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">type of the iterator
(random-access iterator)</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">const_iterator</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">type of iterator that
considers elements as being constant</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">reference</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">type of element reference</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">const_reference</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">type of element reference
that considers elements as being constant</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">size_type</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">type for signed size
values</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">difference_type</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">type for unsigned
difference values</font></td>
</tr>
<tr>
<td><font face="Arial, Helvetica, sans-serif" size="-1"><b>Operations:</b></font></td>
<td><font size="-1"></font></td>
</tr>
<tr>
<td>
<p><font face="Courier New, Courier, mono" size="-1">array&lt;<i>type</i>,<i>num</i>&gt;</font></p>
</td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">default constructor,
creates array of <i><font face="Courier New, Courier, mono">num</font></i>
element of <i><font face="Courier New, Courier, mono">type</font></i>, see
comment below</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">array&lt;<i>type</i>,<i>num</i>&gt;(<i>a</i>)</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">copy constructor,
copies all elements of <i><font face="Courier New, Courier, mono">a</font></i>
(<i><font face="Courier New, Courier, mono">a</font></i> must have same
<i> <font face="Courier New, Courier, mono">type</font></i><font face="Courier New, Courier, mono"><font face="Arial, Helvetica, sans-serif">
and </font></font><i><font face="Courier New, Courier, mono">num</font></i>)</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">operator=</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">assignment, assigns
all elements</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">begin()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns iterator for
the first element</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">end()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns iterator for
position after the last element</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">rbegin()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns reverse iterator
for position of first element of reverse iteration</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">rend()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns reverse iterator
for posistion behind last element of reverese iteration </font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">operator[<i>i</i>]</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns element with
index <i><font face="Courier New, Courier, mono">i</font></i> (no range
checking)</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">at(<i>i</i>)</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns element with
index <font face="Courier New, Courier, mono"><i>i</i></font> (throw std::range_error
if <i><font face="Courier New, Courier, mono">i</font></i> is not valid)</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">front()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns first element
(caller has to ensure that it exists)</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">back()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns last element
(caller has to ensure that it exists)</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">data()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns raw element
array for read-only element access</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">size()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns number of
elements</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">empty()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns whether array
is empty</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">max_size()</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">returns maximum possible
number of elements (same as size())</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">swap(a)</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">swap elements with
array a</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">==<font face="Arial, Helvetica, sans-serif">,
</font>!=</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">checks for equality</font></td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">&lt;<font face="Arial, Helvetica, sans-serif">,
</font>&lt;=<font face="Arial, Helvetica, sans-serif">, </font>&gt;<font face="Arial, Helvetica, sans-serif">,
</font>&gt;=</font></td>
<td><font face="Arial, Helvetica, sans-serif" size="-1">compares array</font></td>
</tr>
<tr>
<td><font face="Arial, Helvetica, sans-serif" size="-1"><b>Values:</b></font></td>
<td>&nbsp;</td>
</tr>
<tr>
<td><font face="Courier New, Courier, mono" size="-1">static_size</font></td>
<td><font size="-1" face="Arial, Helvetica, sans-serif">yields size at compile
time</font></td>
</tr>
</table>
<p><font face="Arial, Helvetica, sans-serif" size="-1">Class array fulfills most
but not all of the requirements of &quot;reversible containers&quot; (see Section
23.1, [lib.container.requirements] of the C++ Standard). The reasons array is
not an reversible STL container is because: </font> <font face="Arial, Helvetica, sans-serif" size="-1"><br>
- No constructors are provided<br>
- Elements may have an indetermined initial value (see below)<br>
- swap() has no constant complexity<br>
- size() is always constant, based on the second template argument of the type<br>
- The container provides no allocator support</font>
<p><font face="Arial, Helvetica, sans-serif" size="-1">It doesn't fulfill the
requirements of a &quot;sequence&quot; (see Section 23.1.1, [lib.sequence.reqmts]
of the C++ Standard), except that</font> <font face="Arial, Helvetica, sans-serif" size="-1"><br>
- front() and back() are provided<br>
- operator[] and at() are provided</font>
<p><font face="Arial, Helvetica, sans-serif" size="-1">Regarding the constructors
there was an important design tradeoff: We could implement array as an &quot;<b>aggregate</b>&quot;
(see Section 8.5.1, [dcl.init.aggr], of the C++ Standard). This would mean:</font></p>
<ul>
<li><font face="Arial, Helvetica, sans-serif" size="-1">An array can be initialized
with a brace-enclosing, comma-separated list of initializers for the elements
of the container, written in increasing subscript order:</font>
<blockquote>
<p><font face="Arial, Helvetica, sans-serif" size="-1">boost::array&lt;int,4&gt;
a = { { 1, 2, 3 } };</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif" size="-1">Note that if there
are fewer elements in the initializer list, then each remaining element
gets default-initialized (thus, it has a defined value).</font></p>
</li>
<li><font face="Arial, Helvetica, sans-serif" size="-1">However, <b>passing
no initializer list means that the elements have an indetermined initial value</b>.</font></li>
<li><font face="Arial, Helvetica, sans-serif" size="-1">It has no user-declared
constructors.</font></li>
<li><font face="Arial, Helvetica, sans-serif" size="-1">It has no private or
protected non-static data members.</font></li>
<li><font face="Arial, Helvetica, sans-serif" size="-1">It has no base classes.</font></li>
<li><font face="Arial, Helvetica, sans-serif" size="-1">It has no virtual functions.</font></li>
</ul>
<p><font face="Arial, Helvetica, sans-serif" size="-1">The current implementation
useus this approach. However, being able to have indetermined initial values
is a big drawback. So, please give me some feedback, how useful you consider
this feature to be. This leads to the list of <b>Open issues:</b></font>
<ul>
<li><font face="Arial, Helvetica, sans-serif">Do we want initializer list support
or would the following be OK?:</font>
<blockquote>
<p><font face="Courier New, Courier, mono">int data[] = { 1, 2, 3, 4 }</font></p>
<p><font face="Courier New, Courier, mono">array&lt;int,5&gt; x(data); <font face="Arial, Helvetica, sans-serif">or
</font>&nbsp;&nbsp;array&lt;int,data&gt; x;</font></p>
</blockquote>
</li>
<li><font face="Arial, Helvetica, sans-serif">Could &quot;<font face="Courier New, Courier, mono">{
</font>...<font face="Courier New, Courier, mono"> }</font>&quot; be used
portably instead of &quot;<font face="Courier New, Courier, mono">{ { </font>...<font face="Courier New, Courier, mono">
} }</font>&quot; to initialize values?</font> </li>
<li><font face="Arial, Helvetica, sans-serif">Any way to have determined initial
values and initializer list support?</font></li>
<li><font face="Arial, Helvetica, sans-serif">Static_casts for reverse iterator
stuff?</font></li>
<li><font face="Arial, Helvetica, sans-serif">Template assignment operator (how
to implement?)</font></li>
<li><font face="Arial, Helvetica, sans-serif">assign() member function?</font></li>
</ul>
<p><font face="Arial, Helvetica, sans-serif">I'd appreciate any constructive <a href="mailto:solutions@josuttis.com">feedback</a>.
<b>Please note: I don't have time to read all boost mails. Thus, to make sure
that feedback arrives me, please send me a copy of each mail regarding this
class.</b></font>
<p><font face="Arial, Helvetica, sans-serif">The code is provided "as is" without
expressed or implied warranty.</font>
<p><font face="Arial, Helvetica, sans-serif"><b>array.hpp</b>, the implementation
of <font face="Courier New, Courier, mono">array&lt;&gt;</font><b>:</b> </font>
<li><font face="Arial, Helvetica, sans-serif">
<a href="array.hpp.html">as HTML file</a></font></li>
<li><font face="Arial, Helvetica, sans-serif">
<a href="array.hpp">as plain file</a></font></li>
<p> <font face="Arial, Helvetica, sans-serif">Simple Example for using <font face="Courier New, Courier, mono">array&lt;&gt;<font face="Arial, Helvetica, sans-serif">:</font></font></font>
<li><font face="Arial, Helvetica, sans-serif">
<a href="array1.cpp.html">as HTML file</a></font> </li>
<li><font face="Arial, Helvetica, sans-serif">
<a href="array1.cpp">as plain file</a></font></li>
<p> <font face="Arial, Helvetica, sans-serif">Another Example for using <font face="Courier New, Courier, mono">array&lt;&gt;<font face="Arial, Helvetica, sans-serif">:</font></font></font>
<li><font face="Arial, Helvetica, sans-serif">
<a href="array2.cpp.html">as HTML file</a></font></li>
<li><font face="Arial, Helvetica, sans-serif">
<a href="array2.cpp">as plain file</a></font></li>
<p> <font face="Arial, Helvetica, sans-serif">A third Example for using <font face="Courier New, Courier, mono">array&lt;&gt;<font face="Arial, Helvetica, sans-serif">:</font></font></font>
<li><font face="Arial, Helvetica, sans-serif">
<a href="array3.cpp.html">as HTML file</a></font></li>
<li><font face="Arial, Helvetica, sans-serif">
<a href="array3.cpp">as plain file</a></font></li>
<p> <font face="Arial, Helvetica, sans-serif">An Example for using <font face="Courier New, Courier, mono">array</font>s
of <font face="Courier New, Courier, mono">array</font>s<font face="Courier New, Courier, mono"><font face="Arial, Helvetica, sans-serif">:</font></font></font>
<li><font face="Arial, Helvetica, sans-serif"> <a href="array4.cpp.html">as HTML
file</a></font></li>
<li><font face="Arial, Helvetica, sans-serif"> <a href="array4.cpp">as plain file</a></font></li>
<p><font face="Arial, Helvetica, sans-serif">An Example for testing other operations
of <font face="Courier New, Courier, mono">array&lt;&gt;</font><font face="Courier New, Courier, mono"><font face="Arial, Helvetica, sans-serif">:</font></font></font>
<li><font face="Arial, Helvetica, sans-serif"> <a href="array5.cpp.html">as HTML
file</a></font></li>
<li><font face="Arial, Helvetica, sans-serif"> <a href="array5.cpp">as plain file</a></font></li>
<p><b><font face="Arial, Helvetica, sans-serif">All files</font></b>
<li><font face="Arial, Helvetica, sans-serif"> <a href="array.zip">as ZIP file
(24KB)</a></font></li>
<li><font face="Arial, Helvetica, sans-serif"> <a href="array.tgz">as TGZ file
(13KB)</a><br>
<br>
To find more details about using ordinary arrays in C++ and the framework of
the STL, see e.g.</font> <font face="Arial, Helvetica, sans-serif"><br>
<i>&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://www.josuttis.com/libbook/">The C++
Standard Library - A Tutorial and Reference</a></i> <br>
&nbsp;&nbsp;&nbsp;&nbsp; by <a href="http://www.josuttis.com" target="_top">Nicolai
M. Josuttis</a></font> <font face="Arial, Helvetica, sans-serif"><br>
&nbsp;&nbsp;&nbsp;&nbsp; Addison Wesley Longman, 1999</font> <font face="Arial, Helvetica, sans-serif"><br>
&nbsp;&nbsp;&nbsp;&nbsp; ISBN 0-201-37926-0</font> <font face="Arial, Helvetica, sans-serif"><br>
</font></li>
<p><font face="Arial, Helvetica, sans-serif"><a href="http://www.josuttis.com/" TARGET="_top">Home
Page of Nicolai Josuttis</a></font> <font face="Arial, Helvetica, sans-serif"><br>
&nbsp; </font>
</body>
</html>