mirror of
https://github.com/boostorg/utility.git
synced 2025-08-01 05:44:37 +02:00
This commit was manufactured by cvs2svn to create branch
'unlabeled-1.5.2'. [SVN r9288]
This commit is contained in:
nobody
96
.gitattributes
vendored
Normal file
96
.gitattributes
vendored
Normal file
@@ -0,0 +1,96 @@
|
||||
* text=auto !eol svneol=native#text/plain
|
||||
*.gitattributes text svneol=native#text/plain
|
||||
|
||||
# Scriptish formats
|
||||
*.bat text svneol=native#text/plain
|
||||
*.bsh text svneol=native#text/x-beanshell
|
||||
*.cgi text svneol=native#text/plain
|
||||
*.cmd text svneol=native#text/plain
|
||||
*.js text svneol=native#text/javascript
|
||||
*.php text svneol=native#text/x-php
|
||||
*.pl text svneol=native#text/x-perl
|
||||
*.pm text svneol=native#text/x-perl
|
||||
*.py text svneol=native#text/x-python
|
||||
*.sh eol=lf svneol=LF#text/x-sh
|
||||
configure eol=lf svneol=LF#text/x-sh
|
||||
|
||||
# Image formats
|
||||
*.bmp binary svneol=unset#image/bmp
|
||||
*.gif binary svneol=unset#image/gif
|
||||
*.ico binary svneol=unset#image/ico
|
||||
*.jpeg binary svneol=unset#image/jpeg
|
||||
*.jpg binary svneol=unset#image/jpeg
|
||||
*.png binary svneol=unset#image/png
|
||||
*.tif binary svneol=unset#image/tiff
|
||||
*.tiff binary svneol=unset#image/tiff
|
||||
*.svg text svneol=native#image/svg%2Bxml
|
||||
|
||||
# Data formats
|
||||
*.pdf binary svneol=unset#application/pdf
|
||||
*.avi binary svneol=unset#video/avi
|
||||
*.doc binary svneol=unset#application/msword
|
||||
*.dsp text svneol=crlf#text/plain
|
||||
*.dsw text svneol=crlf#text/plain
|
||||
*.eps binary svneol=unset#application/postscript
|
||||
*.gz binary svneol=unset#application/gzip
|
||||
*.mov binary svneol=unset#video/quicktime
|
||||
*.mp3 binary svneol=unset#audio/mpeg
|
||||
*.ppt binary svneol=unset#application/vnd.ms-powerpoint
|
||||
*.ps binary svneol=unset#application/postscript
|
||||
*.psd binary svneol=unset#application/photoshop
|
||||
*.rdf binary svneol=unset#text/rdf
|
||||
*.rss text svneol=unset#text/xml
|
||||
*.rtf binary svneol=unset#text/rtf
|
||||
*.sln text svneol=native#text/plain
|
||||
*.swf binary svneol=unset#application/x-shockwave-flash
|
||||
*.tgz binary svneol=unset#application/gzip
|
||||
*.vcproj text svneol=native#text/xml
|
||||
*.vcxproj text svneol=native#text/xml
|
||||
*.vsprops text svneol=native#text/xml
|
||||
*.wav binary svneol=unset#audio/wav
|
||||
*.xls binary svneol=unset#application/vnd.ms-excel
|
||||
*.zip binary svneol=unset#application/zip
|
||||
|
||||
# Text formats
|
||||
.htaccess text svneol=native#text/plain
|
||||
*.bbk text svneol=native#text/xml
|
||||
*.cmake text svneol=native#text/plain
|
||||
*.css text svneol=native#text/css
|
||||
*.dtd text svneol=native#text/xml
|
||||
*.htm text svneol=native#text/html
|
||||
*.html text svneol=native#text/html
|
||||
*.ini text svneol=native#text/plain
|
||||
*.log text svneol=native#text/plain
|
||||
*.mak text svneol=native#text/plain
|
||||
*.qbk text svneol=native#text/plain
|
||||
*.rst text svneol=native#text/plain
|
||||
*.sql text svneol=native#text/x-sql
|
||||
*.txt text svneol=native#text/plain
|
||||
*.xhtml text svneol=native#text/xhtml%2Bxml
|
||||
*.xml text svneol=native#text/xml
|
||||
*.xsd text svneol=native#text/xml
|
||||
*.xsl text svneol=native#text/xml
|
||||
*.xslt text svneol=native#text/xml
|
||||
*.xul text svneol=native#text/xul
|
||||
*.yml text svneol=native#text/plain
|
||||
boost-no-inspect text svneol=native#text/plain
|
||||
CHANGES text svneol=native#text/plain
|
||||
COPYING text svneol=native#text/plain
|
||||
INSTALL text svneol=native#text/plain
|
||||
Jamfile text svneol=native#text/plain
|
||||
Jamroot text svneol=native#text/plain
|
||||
Jamfile.v2 text svneol=native#text/plain
|
||||
Jamrules text svneol=native#text/plain
|
||||
Makefile* text svneol=native#text/plain
|
||||
README text svneol=native#text/plain
|
||||
TODO text svneol=native#text/plain
|
||||
|
||||
# Code formats
|
||||
*.c text svneol=native#text/plain
|
||||
*.cpp text svneol=native#text/plain
|
||||
*.h text svneol=native#text/plain
|
||||
*.hpp text svneol=native#text/plain
|
||||
*.ipp text svneol=native#text/plain
|
||||
*.tpp text svneol=native#text/plain
|
||||
*.jam text svneol=native#text/plain
|
||||
*.java text svneol=native#text/plain
|
||||
597
operators.htm
Normal file
597
operators.htm
Normal file
@@ -0,0 +1,597 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<title>Header boost/operators.hpp Documentation</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Header
|
||||
<a href="../../boost/operators.hpp">boost/operators.hpp</a></h1>
|
||||
<p>Header <a href="../../boost/operators.hpp">boost/operators.hpp</a> supplies
|
||||
(in namespace boost) several sets of templates:</p>
|
||||
<ul>
|
||||
<li><a href="#Arithmetic">Arithmetic operators</a>.
|
||||
<li><a href="#deref and helpers">Dereference operators and iterator helpers.</a></li>
|
||||
</ul>
|
||||
<p>These templates define many global operators in terms of a minimal number of
|
||||
fundamental operators.</p>
|
||||
<h1><a name="Arithmetic">Arithmetic</a> Operators</h1>
|
||||
<p>If, for example, you declare a class like this:</p>
|
||||
<blockquote>
|
||||
<pre>class MyInt : boost::operators<MyInt>
|
||||
{
|
||||
bool operator<(const MyInt& x) const;
|
||||
bool operator==(const MyInt& x) const;
|
||||
MyInt& operator+=(const MyInt& x);
|
||||
MyInt& operator-=(const MyInt& x);
|
||||
MyInt& operator*=(const MyInt& x);
|
||||
MyInt& operator/=(const MyInt& x);
|
||||
MyInt& operator%=(const MyInt& x);
|
||||
MyInt& operator|=(const MyInt& x);
|
||||
MyInt& operator&=(const MyInt& x);
|
||||
MyInt& operator^=(const MyInt& x);
|
||||
MyInt& operator++();
|
||||
MyInt& operator--();
|
||||
};</pre>
|
||||
</blockquote>
|
||||
<p>then the <code>operators<></code> template adds more than a dozen
|
||||
additional operators, such as operator>, <=, >=, and +. <a href="#two_arg">Two-argument
|
||||
forms</a> of the templates are also provided to allow interaction with other
|
||||
types.</p>
|
||||
<p><a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a>
|
||||
started the library and contributed the arithmetic operators in <a href="../../boost/operators.hpp">boost/operators.hpp</a>.<br>
|
||||
<a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>
|
||||
contributed the <a href="#deref and helpers">dereference operators and iterator
|
||||
helpers</a> in <a href="../../boost/operators.hpp">boost/operators.hpp</a>.<br>
|
||||
<a href="http://www.boost.org/people/aleksey_gurtovoy.htm">Aleksey Gurtovoy</a>
|
||||
contributed the code to support <a href="#chaining">base class chaining</a>
|
||||
while remaining backward-compatible with old versions of the library.<br>
|
||||
<a href="http://www.boost.org/people/beman_dawes.html">Beman Dawes</a>
|
||||
contributed <a href="http://www.boost.org/libs/utility/operators_test.cpp">test_operators.cpp</a>.</p>
|
||||
<h2>Rationale</h2>
|
||||
<p>Overloaded operators for class types typically occur in groups. If you can
|
||||
write <code>x + y</code>, you probably also want to be able to write <code>x +=
|
||||
y</code>. If you can write <code>x < y,</code> you also want <code>x > y,
|
||||
x >= y,</code> and <code>x <= y</code>. Moreover, unless your class has
|
||||
really surprising behavior, some of these related operators can be defined in
|
||||
terms of others (e.g. <code>x >= y <b><=></b> !(x < y)</code>).
|
||||
Replicating this boilerplate for multiple classes is both tedious and
|
||||
error-prone. The <a href="../../boost/operators.hpp">boost/operators.hpp</a>
|
||||
templates help by generating operators for you at namespace scope based on other
|
||||
operators you've defined in your class.</p>
|
||||
<a name="two_arg">
|
||||
<h2>Two-Argument Template Forms</h2>
|
||||
</a>
|
||||
<p>The arguments to a binary operator commonly have identical types, but it is
|
||||
not unusual to want to define operators which combine different types. For <a href="#usage">example</a>,
|
||||
one might want to multiply a mathematical vector by a scalar. The two-argument
|
||||
template forms of the arithmetic operator templates are supplied for this
|
||||
purpose. When applying the two-argument form of a template, the desired return
|
||||
type of the operators typically determines which of the two types in question
|
||||
should be derived from the operator template. For example, if the result of <code>T + U</code>
|
||||
is of type <code>T</code>, then <code>T</code> (not <code>U</code>) should be
|
||||
derived from <code>addable<T,U></code>. The comparison templates <code><a href="#less_than_comparable">less_than_comparable<></a></code>
|
||||
and <code><a href="#equality_comparable">equality_comparable<></a></code>
|
||||
are exceptions to this guideline, since the return type of the operators they
|
||||
define is <code>bool</code>.</p>
|
||||
<p>On compilers which do not support partial specialization, the two-argument
|
||||
forms must be specified by using the names shown below with the trailing <code>'2'</code>.
|
||||
The single-argument forms with the trailing <code>'1'</code> are provided for
|
||||
symmetry and to enable certain applications of the <a href="#chaining">base
|
||||
class chaining</a> technique.</p>
|
||||
<h2>Arithmetic operators table</h2>
|
||||
<p>The requirements for the types used to instantiate operator templates are
|
||||
specified in terms of expressions which must be valid and by the return type of
|
||||
the expression. In the following table <code>t</code> and <code>t1</code> are
|
||||
values of type <code>T</code>, and <code>u</code> is a value of type <code>U</code>.
|
||||
Every template in the library other than <a href="#operators"><code>operators<></code></a>
|
||||
and <a href="#operators"><code>operators2<></code></a> has an additional
|
||||
optional template parameter <code>B</code> which is not shown in the table, but
|
||||
is explained <a href="#chaining">below</a></p>
|
||||
<table cellpadding="5" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><b>template</b></td>
|
||||
<td><b>template will supply</b></td>
|
||||
<td><b>Requirements</b></td>
|
||||
</tr>
|
||||
<a name="operators">
|
||||
<tr>
|
||||
<td><code>operators<T></code></td>
|
||||
<td>All the other <T> templates in this table.</td>
|
||||
<td>All the <T> requirements in this table.</td>
|
||||
<tr>
|
||||
<td><code>operators<T,U><br>
|
||||
operators2<T,U></code></td>
|
||||
<td>All the other <T,U> templates in this table, plus incrementable<T>
|
||||
and decrementable<T>.</td>
|
||||
<td><b>All</b> the <T,U> requirements in this table</a><a href="#portability">*</a>,
|
||||
plus incrementable<T> and decrementable<T>.</td>
|
||||
</tr>
|
||||
<a name="less_than_comparable">
|
||||
<tr>
|
||||
<td><code>less_than_comparable<T><br>
|
||||
less_than_comparable1<T></code></td>
|
||||
<td><code>bool operator>(const T&, const T&) <br>
|
||||
bool operator<=(const T&, const T&)<br>
|
||||
bool operator>=(const T&, const T&)</code></td>
|
||||
<td><code>t<t1</code>. Return convertible to bool</td>
|
||||
<tr>
|
||||
<td><code>less_than_comparable<T,U><br>
|
||||
less_than_comparable2<T,U></code></td>
|
||||
<td><code>bool operator<=(const T&, const U&)<br>
|
||||
bool operator>=(const T&, const U&)<br>
|
||||
bool operator>(const U&, const T&) <br>
|
||||
bool operator<(const U&, const T&) <br>
|
||||
bool operator<=(const U&, const T&)<br>
|
||||
bool operator>=(const U&, const T&)</code></td>
|
||||
<td><code>t<u</code>. Return convertible to bool<br>
|
||||
<code>t>u</code>. Return convertible to bool</td>
|
||||
</tr>
|
||||
</a><a name="equality_comparable">
|
||||
<tr>
|
||||
<td><code>equality_comparable<T><br>
|
||||
equality_comparable1<T></code></td>
|
||||
<td><code>bool operator!=(const T&, const T&)</code></td>
|
||||
<td><code>t==t1</code>. Return convertible to bool</td>
|
||||
<tr>
|
||||
<td><code>equality_comparable<T,U><br>
|
||||
equality_comparable2<T,U></code></td>
|
||||
<td><code>friend bool operator==(const U&, const T&)<br>
|
||||
friend bool operator!=(const U&, const T&)<br>
|
||||
friend bool operator!=( const T&, const U&)</code></td>
|
||||
<td><code>t==u</code>. Return convertible to bool</td>
|
||||
</tr>
|
||||
</a>
|
||||
<tr>
|
||||
<td><code>addable<T><br>
|
||||
addable1<T></code></td>
|
||||
<td><code>T operator+(T, const T&)</code></td>
|
||||
<td><code>t+=t1</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>addable<T,U><br>
|
||||
addable2<T,U></code></td>
|
||||
<td><code>T operator+(T, const U&)<br>
|
||||
T operator+(const U&, T )</code></td>
|
||||
<td><code>t+=u</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>subtractable<T><br>
|
||||
subtractable1<T></code></td>
|
||||
<td><code>T operator-(T, const T&)</code></td>
|
||||
<td><code>t-=t1</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>subtractable<T,U><br>
|
||||
subtractable2<T,U></code></td>
|
||||
<td><code>T operator-(T, const U&)</code></td>
|
||||
<td><code>t-=u</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>multipliable<T><br>
|
||||
multipliable1<T></code></td>
|
||||
<td><code>T operator*(T, const T&)</code></td>
|
||||
<td><code>t*=t1</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>multipliable<T,U><br>
|
||||
multipliable2<T,U></code></td>
|
||||
<td><code>T operator*(T, const U&)<br>
|
||||
T operator*(const U&, T )</code></td>
|
||||
<td><code>t*=u</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>dividable<T><br>
|
||||
dividable1<T></code></td>
|
||||
<td><code>T operator/(T, const T&)</code></td>
|
||||
<td><code>t/=t1</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>dividable<T,U><br>
|
||||
dividable2<T,U></code></td>
|
||||
<td><code>T operator/(T, const U&)</code></td>
|
||||
<td><code>t/=u</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>modable<T><br>
|
||||
modable1<T></code></td>
|
||||
<td><code>T operator%(T, const T&)</code></td>
|
||||
<td><code>t%=t1</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>modable<T,U><br>
|
||||
modable2<T,U></code></td>
|
||||
<td><code>T operator%(T, const U&)</code></td>
|
||||
<td><code>t%=u</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>orable<T><br>
|
||||
orable1<T></code></td>
|
||||
<td><code>T operator|(T, const T&)</code></td>
|
||||
<td><code>t|=t1</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>orable<T,U><br>
|
||||
orable2<T,U></code></td>
|
||||
<td><code>T operator|(T, const U&)<br>
|
||||
T operator|(const U&, T )</code></td>
|
||||
<td><code>t|=u</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>andable<T><br>
|
||||
andable1<T></code></td>
|
||||
<td><code>T operator&(T, const T&)</code></td>
|
||||
<td><code>t&=t1</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>andable<T,U><br>
|
||||
andable2<T,U></code></td>
|
||||
<td><code>T operator&(T, const U&)<br>
|
||||
T operator&(const U&, T)</code></td>
|
||||
<td><code>t&=u</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>xorable<T><br>
|
||||
xorable1<T></code></td>
|
||||
<td><code>T operator^(T, const T&)</code></td>
|
||||
<td><code>t^=t1</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>xorable<T,U><br>
|
||||
xorable2<T,U></code></td>
|
||||
<td><code>T operator^(T, const U&)<br>
|
||||
T operator^(const U&, T )</code></td>
|
||||
<td><code>t^=u</code>. Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>incrementable<T><br>
|
||||
incrementable1<T></code></td>
|
||||
<td><code>T operator++(T& x, int)</code></td>
|
||||
<td><code>T temp(x); ++x; return temp;</code><br>
|
||||
Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>decrementable<T><br>
|
||||
decrementable1<T></code></td>
|
||||
<td><code>T operator--(T& x, int)</code></td>
|
||||
<td><code>T temp(x); --x; return temp;</code><br>
|
||||
Return convertible to <code>T</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<br>
|
||||
<b><a name="portability">Portability Note:</a></b> many compilers (e.g. MSVC6.3,
|
||||
GCC 2.95.2) will not enforce the requirements in this table unless the
|
||||
operations which depend on them are actually used. This is not
|
||||
standard-conforming behavior. If you are trying to write portable code it is
|
||||
important not to rely on this bug. In particular, it would be convenient to
|
||||
derive all your classes which need binary operators from the <a href="#operators"><code>operators<></code></a>
|
||||
and <a href="#operators"><code>operators2<></code></a> templates,
|
||||
regardless of whether they implement all the requirements in the table. Even if
|
||||
this works with your compiler today, it may not work tomorrow.
|
||||
<h2><a name="chaining">Base Class Chaining</a> and Object Size</h2>
|
||||
<p>Every template listed in the table except <a href="#operators"><code>operators<></code></a>
|
||||
and <a href="#operators"><code>operators2<></code></a> has an additional
|
||||
optional template parameter <code>B</code>. If supplied, <code>B</code>
|
||||
must be a class type; the resulting class will be publicly derived from B. This
|
||||
can be used to avoid the object size bloat commonly associated with multiple
|
||||
empty base classes (see the <a href="#old_lib_note">note for users of older
|
||||
versions</a> below for more details). To provide support for several groups of
|
||||
operators, use the additional parameter to chain operator templates into a
|
||||
single-base class hierarchy, as in the following <a href="#usage">example</a>.</p>
|
||||
<p><b>Caveat:</b> to chain to a base class which is <i>not</i> a boost operator
|
||||
template when using the <a href="#two_arg">single-argument form</a><a> of a
|
||||
boost operator template, you must specify the operator template with the
|
||||
trailing <code>'1'</code> in its name. Otherwise the library will assume you
|
||||
mean to define a binary operation combining the class you intend to use as a
|
||||
base class and the class you're deriving.</p>
|
||||
<p><b>Borland users</b>: even single-inheritance seems to cause an increase in
|
||||
object size in some cases. If you are not defining a template, you may get
|
||||
better object-size performance by avoiding derivation altogether, and instead
|
||||
explicitly instantiating the operator template as follows:
|
||||
<pre>
|
||||
class myclass // lose the inheritance...
|
||||
{
|
||||
//...
|
||||
};
|
||||
// explicitly instantiate the operators I need.
|
||||
template class less_than_comparable<myclass>;
|
||||
template class equality_comparable<myclass>;
|
||||
template class incrementable<myclass>;
|
||||
template class decrementable<myclass>;
|
||||
template class addable<myclass,long>;
|
||||
template class subtractable<myclass,long>;
|
||||
</pre>
|
||||
</a><a name="usage">
|
||||
<h2>Usage example</h2>
|
||||
</a>
|
||||
<pre>template <class T>
|
||||
class point // note: private inheritance is OK here!
|
||||
: boost::addable< point<T> // point + point
|
||||
, boost::subtractable< point<T> // point - point
|
||||
, boost::dividable2< point<T>, T // point / T
|
||||
, boost::multipliable2< point<T>, T // point * T, T * point
|
||||
> > > >
|
||||
{
|
||||
public:
|
||||
point(T, T);
|
||||
T x() const;
|
||||
T y() const;
|
||||
|
||||
point operator+=(const point&);
|
||||
// point operator+(point, const point&) automatically
|
||||
// generated by addable.
|
||||
|
||||
point operator-=(const point&);
|
||||
// point operator-(point, const point&) automatically
|
||||
// generated by subtractable.
|
||||
|
||||
point operator*=(T);
|
||||
// point operator*(point, const T&) and
|
||||
// point operator*(const T&, point) auto-generated
|
||||
// by multipliable.
|
||||
|
||||
point operator/=(T);
|
||||
// point operator/(point, const T&) auto-generated
|
||||
// by dividable.
|
||||
private:
|
||||
T x_;
|
||||
T y_;
|
||||
};
|
||||
|
||||
// now use the point<> class:
|
||||
|
||||
template <class T>
|
||||
T length(const point<T> p)
|
||||
{
|
||||
return sqrt(p.x()*p.x() + p.y()*p.y());
|
||||
}
|
||||
|
||||
const point<float> right(0, 1);
|
||||
const point<float> up(1, 0);
|
||||
const point<float> pi_over_4 = up + right;
|
||||
const point<float> pi_over_4_normalized = pi_over_4 / length(pi_over_4);</pre>
|
||||
<h2>Arithmetic operators demonstration and test program</h2>
|
||||
<p>The <a href="http://www.boost.org/libs/utility/operators_test.cpp">operators_test.cpp</a>
|
||||
program demonstrates the use of the arithmetic operator templates, and can also
|
||||
be used to verify correct operation.</p>
|
||||
<p>The test program has been compiled and run successfully with: </p>
|
||||
<ul>
|
||||
<li>GCC 2.95.2
|
||||
<li>GCC 2.95.2 / STLport 4.0b8.
|
||||
<li>Metrowerks Codewarrior 5.3
|
||||
<li>KAI C++ 3.3
|
||||
<li>Microsoft Visual C++ 6.0 SP3.
|
||||
<li>Microsoft Visual C++ 6.0 SP3 / STLport 4.0b8.</li>
|
||||
</ul>
|
||||
<h1><a name="deref and helpers">Dereference</a> operators and iterator helpers</h1>
|
||||
<p>The <a href="#Iterator helpers">iterator helper</a> templates ease the task
|
||||
of creating a custom iterator. Similar to arithmetic types, a complete iterator
|
||||
has many operators that are "redundant" and can be implemented in
|
||||
terms of the core set of operators.</p>
|
||||
<p>The <a href="#dereference">dereference operators</a> were motivated by the <a href="#Iterator helpers">iterator
|
||||
helpers</a>, but are often useful in non-iterator contexts as well. Many of the
|
||||
redundant iterator operators are also arithmetic operators, so the iterator
|
||||
helper classes borrow many of the operators defined above. In fact, only two new
|
||||
operators need to be defined! (the pointer-to-member <code>operator-></code>
|
||||
and the subscript <code>operator[]</code>). </PP>
|
||||
<h3>Notation</h3>
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td valign="top"><code>T</code></td>
|
||||
<td valign="top">is the user-defined type for which the operations are
|
||||
being supplied.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>V</code></td>
|
||||
<td valign="top">is the type which the resulting <code>dereferenceable</code>
|
||||
type "points to", or the <code>value_type</code> of the custom
|
||||
iterator.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>D</code></td>
|
||||
<td valign="top">is the type used to index the resulting <code>indexable</code>
|
||||
type or the <code>difference_type</code> of the custom iterator.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>P</code></td>
|
||||
<td valign="top">is a type which can be dereferenced to access <code>V</code>,
|
||||
or the <code>pointer</code> type of the custom iterator.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>R</code></td>
|
||||
<td valign="top">is the type returned by indexing the <code>indexable</code>
|
||||
type or the <code>reference</code> type of the custom iterator.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>i</code></td>
|
||||
<td valign="top">is short for <code>static_cast<const T&>(*this)</code>,
|
||||
where <code>this</code> is a pointer to the helper class.<br>
|
||||
Another words, <code>i</code> should be an object of the custom iterator
|
||||
type.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>x,x1,x2</code></td>
|
||||
<td valign="top">are objects of type <code>T</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code>n</code></td>
|
||||
<td valign="top">is an object of type <code>D</code>.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The requirements for the types used to instantiate the dereference operators
|
||||
and iterator helpers are specified in terms of expressions which must be valid
|
||||
and their return type. </p>
|
||||
<h2><a name="dereference">Dereference operators</a></h2>
|
||||
<p>The dereference operator templates in this table all accept an optional
|
||||
template parameter (not shown) to be used for <a href="#chaining">base class
|
||||
chaining</a>.
|
||||
<table cellpadding="5" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><b>template</b></td>
|
||||
<td><b>template will supply</b></td>
|
||||
<td><b>Requirements</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>dereferenceable<T,P></code></td>
|
||||
<td><code>P operator->() const</code></td>
|
||||
<td><code>(&*i.)</code>. Return convertible to <code>P</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>indexable<T,D,R></code></td>
|
||||
<td><code>R operator[](D n) const</code></td>
|
||||
<td><code>*(i + n)</code>. Return of type <code>R</code>.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h2><a name="Iterator helpers">Iterator</a> helpers</h2>
|
||||
<p>There are three separate iterator helper classes, each for a different
|
||||
category of iterator. Here is a summary of the core set of operators that the
|
||||
custom iterator must define, and the extra operators that are created by the
|
||||
helper classes. For convenience, the helper classes also fill in all of the
|
||||
typedef's required of iterators by the C++ standard (<code>iterator_category</code>,
|
||||
<code>value_type</code>, etc.).</p>
|
||||
<table cellpadding="5" border="1" valign="top">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><b>template</b></td>
|
||||
<td><b>template will supply</b></td>
|
||||
<td><b>Requirements</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>forward_iterator_helper</code><br>
|
||||
<code><T,V,D,P,R></code></td>
|
||||
<td><code>bool operator!=(const T& x1, const T& x2)</code><br>
|
||||
<code>T operator++(T& x, int)</code><br>
|
||||
<code>V* operator->() const</code><br>
|
||||
</td>
|
||||
<td><code>x1==x2</code>. Return convertible to bool<br>
|
||||
<code>T temp(x); ++x; return temp;</code><br>
|
||||
<code>(&*i.)</code>. Return convertible to <code>V*</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>bidirectional_iterator_helper</code><br>
|
||||
<code><T,V,D,P,R></code></td>
|
||||
<td>Same as above, plus<br>
|
||||
<code>T operator--(T& x, int)</code></td>
|
||||
<td>Same as above, plus<br>
|
||||
<code>T temp(x); --x; return temp;</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>random_access_iterator_helper</code><br>
|
||||
<code><T,V,D,P,R></code></td>
|
||||
<td>Same as above, plus<br>
|
||||
<code>T operator+(T x, const D&)<br>
|
||||
T operator+(const D& n, T x)<br>
|
||||
T operator-(T x, const D& n)<br>
|
||||
R operator[](D n) const<br>
|
||||
bool operator>(const T& x1, const T& x2) <br>
|
||||
bool operator<=(const T& x1, const T& x2)<br>
|
||||
bool operator>=(const T& x1, const T& x2)</code></td>
|
||||
<td>Same as above, plus<br>
|
||||
<code>x+=n</code>. Return convertible to <code>T</code><br>
|
||||
<code>x-=n</code>. Return convertible to <code>T</code><br>
|
||||
<code>x1<x2</code>. Return convertible to bool<br>
|
||||
And to satisfy <a href="http://www.sgi.com/Technology/STL/RandomAccessIterator.html">RandomAccessIterator</a>:<br>
|
||||
<code>x1-x2</code>. Return convertible to <code>D</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h2>Iterator demonstration and test program</h2>
|
||||
<p>The <a href="http://www.boost.org/libs/utility/iterators_test.cpp">iterators_test.cpp</a>
|
||||
program demonstrates the use of the iterator templates, and can also be used to
|
||||
verify correct operation. The following is the custom iterator defined in the
|
||||
test program. It demonstrates a correct (though trivial) implementation of the
|
||||
core operations that must be defined in order for the iterator helpers to
|
||||
"fill in" the rest of the iterator operations.</p>
|
||||
<blockquote>
|
||||
<pre>template <class T, class R, class P>
|
||||
struct test_iter
|
||||
: public boost::random_access_iterator_helper<
|
||||
test_iter<T,R,P>, T, std::ptrdiff_t, P, R>
|
||||
{
|
||||
typedef test_iter self;
|
||||
typedef R Reference;
|
||||
typedef std::ptrdiff_t Distance;
|
||||
|
||||
public:
|
||||
test_iter(T* i) : _i(i) { }
|
||||
test_iter(const self& x) : _i(x._i) { }
|
||||
self& operator=(const self& x) { _i = x._i; return *this; }
|
||||
Reference operator*() const { return *_i; }
|
||||
self& operator++() { ++_i; return *this; }
|
||||
self& operator--() { --_i; return *this; }
|
||||
self& operator+=(Distance n) { _i += n; return *this; }
|
||||
self& operator-=(Distance n) { _i -= n; return *this; }
|
||||
bool operator==(const self& x) const { return _i == x._i; }
|
||||
bool operator<(const self& x) const { return _i < x._i; }
|
||||
friend Distance operator-(const self& x, const self& y) {
|
||||
return x._i - y._i;
|
||||
}
|
||||
protected:
|
||||
T* _i;
|
||||
};</pre>
|
||||
</blockquote>
|
||||
<p>It has been compiled and run successfully with:</p>
|
||||
<ul>
|
||||
<li>GCC 2.95.2
|
||||
<li>Metrowerks Codewarrior 5.2
|
||||
<li>Microsoft Visual C++ 6.0 SP3</li>
|
||||
</ul>
|
||||
<p><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>
|
||||
contributed the iterator operators and helpers. He also contributed <a href="http://www.boost.org/libs/utility/iterators_test.cpp">iterators_test.cpp</a>. </p>
|
||||
<hr>
|
||||
<h2><a name="old_lib_note">Note for users of older versions</a></h2>
|
||||
<p>The <a href="#chaining">changes in the library interface and recommended
|
||||
usage</a> were motivated by some practical issues described below. The new
|
||||
version of the library is still backward-compatible with the former one (so
|
||||
you're not <i>forced</i> change any existing code), but the old usage is
|
||||
deprecated. Though it was arguably simpler and more intuitive than using <a href="#chaining">base
|
||||
class chaining</a>, it has been discovered that the old practice of deriving
|
||||
from multiple operator templates can cause the resulting classes to be much
|
||||
larger than they should be. Most modern C++ compilers significantly bloat the
|
||||
size of classes derived from multiple empty base classes, even though the base
|
||||
classes themselves have no state. For instance, the size of <code>point<int></code>
|
||||
from the <a href="#usage">example</a> above was 12-24 bytes on various compilers
|
||||
for the Win32 platform, instead of the expected 8 bytes.
|
||||
<p>Strictly speaking, it was not the library's fault - the language rules allow
|
||||
the compiler to apply the empty base class optimization in that situation. In
|
||||
principle an arbitrary number of empty base classes can be allocated at the same
|
||||
offset, provided that none of them have a common ancestor (see section 10.5 [class.derived],
|
||||
par. 5 of the standard). But the language definition also doesn't <i>require</i>
|
||||
implementations to do the optimization, and few if any of today's compilers
|
||||
implement it when multiple inheritance is involved. What's worse, it is very
|
||||
unlikely that implementors will adopt it as a future enhancement to existing
|
||||
compilers, because it would break binary compatibility between code generated by
|
||||
two different versions of the same compiler. As Matt Austern said, "One of
|
||||
the few times when you have the freedom to do this sort of thing is when you're
|
||||
targeting a new architecture...". On the other hand, many common compilers
|
||||
will use the empty base optimization for single inheritance hierarchies.</p>
|
||||
<p>Given the importance of the issue for the users of the library (which aims to
|
||||
be useful for writing light-weight classes like <code>MyInt</code> or <code>point<></code>),
|
||||
and the forces described above, we decided to change the library interface so
|
||||
that the object size bloat could be eliminated even on compilers that support
|
||||
only the simplest form of the empty base class optimization. The current library
|
||||
interface is the result of those changes. Though the new usage is a bit more
|
||||
complicated than the old one, we think it's worth it to make the library more
|
||||
useful in real world. Alexy Gurtovoy contributed the code which supports the new
|
||||
usage idiom while allowing the library remain backward-compatible.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->27 Sep 2000<!--webbot bot="Timestamp" endspan i-checksum="14936" --></p>
|
||||
<p><EFBFBD> Copyright David Abrahams and Beman Dawes 1999-2000. Permission to copy,
|
||||
use, modify, sell and distribute this document is granted provided this
|
||||
copyright notice appears in all copies. This document is provided "as
|
||||
is" without express or implied warranty, and with no claim as to its
|
||||
suitability for any purpose.</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
114
type_traits_test.hpp
Normal file
114
type_traits_test.hpp
Normal file
@@ -0,0 +1,114 @@
|
||||
// boost::compressed_pair test program
|
||||
|
||||
// (C) Copyright John Maddock 2000. Permission to copy, use, modify, sell and
|
||||
// distribute this software is granted provided this copyright notice appears
|
||||
// in all copies. This software is provided "as is" without express or implied
|
||||
// warranty, and with no claim as to its suitability for any purpose.
|
||||
|
||||
// common test code for type_traits_test.cpp/call_traits_test.cpp/compressed_pair_test.cpp
|
||||
|
||||
|
||||
#ifndef BOOST_TYPE_TRAITS_TEST_HPP
|
||||
#define BOOST_TYPE_TRAITS_TEST_HPP
|
||||
|
||||
// Variable declarations must come before test_align due to two-phase lookup
|
||||
unsigned failures = 0;
|
||||
unsigned test_count = 0;
|
||||
|
||||
//
|
||||
// this one is here just to suppress warnings:
|
||||
//
|
||||
template <class T>
|
||||
bool do_compare(T i, T j)
|
||||
{
|
||||
return i == j;
|
||||
}
|
||||
|
||||
//
|
||||
// this one is to verify that a constant is indeed a
|
||||
// constant-integral-expression:
|
||||
//
|
||||
template <int>
|
||||
struct ct_checker
|
||||
{
|
||||
};
|
||||
|
||||
#define BOOST_DO_JOIN( X, Y ) BOOST_DO_JOIN2(X,Y)
|
||||
#define BOOST_DO_JOIN2(X, Y) X##Y
|
||||
#define BOOST_JOIN( X, Y ) BOOST_DO_JOIN( X, Y )
|
||||
|
||||
#ifdef BOOST_MSVC
|
||||
#define value_test(v, x) ++test_count;\
|
||||
{typedef ct_checker<(x)> this_is_a_compile_time_check_;}\
|
||||
if(!do_compare((int)v,(int)x)){++failures; std::cout << "checking value of " << #x << "...failed" << std::endl;}
|
||||
#else
|
||||
#define value_test(v, x) ++test_count;\
|
||||
typedef ct_checker<(x)> BOOST_JOIN(this_is_a_compile_time_check_, __LINE__);\
|
||||
if(!do_compare((int)v,(int)x)){++failures; std::cout << "checking value of " << #x << "...failed" << std::endl;}
|
||||
#endif
|
||||
#define value_fail(v, x) ++test_count; ++failures; std::cout << "checking value of " << #x << "...failed" << std::endl;
|
||||
|
||||
#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
|
||||
#define type_test(v, x) ++test_count;\
|
||||
if(do_compare(boost::is_same<v, x>::value, false)){\
|
||||
++failures; \
|
||||
std::cout << "checking type of " << #x << "...failed" << std::endl; \
|
||||
std::cout << " expected type was " << #v << std::endl; \
|
||||
std::cout << " " << typeid(boost::is_same<v, x>).name() << "::value is false" << std::endl; }
|
||||
#else
|
||||
#define type_test(v, x) ++test_count;\
|
||||
if(typeid(v) != typeid(x)){\
|
||||
++failures; \
|
||||
std::cout << "checking type of " << #x << "...failed" << std::endl; \
|
||||
std::cout << " expected type was " << #v << std::endl; \
|
||||
std::cout << " " << "typeid(" #v ") != typeid(" #x ")" << std::endl; }
|
||||
#endif
|
||||
|
||||
template <class T>
|
||||
struct test_align
|
||||
{
|
||||
struct padded
|
||||
{
|
||||
char c;
|
||||
T t;
|
||||
};
|
||||
static void do_it()
|
||||
{
|
||||
padded p;
|
||||
unsigned a = reinterpret_cast<char*>(&(p.t)) - reinterpret_cast<char*>(&p);
|
||||
value_test(a, boost::alignment_of<T>::value);
|
||||
}
|
||||
};
|
||||
#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
|
||||
template <class T>
|
||||
struct test_align<T&>
|
||||
{
|
||||
static void do_it()
|
||||
{
|
||||
//
|
||||
// we can't do the usual test because we can't take the address
|
||||
// of a reference, so check that the result is the same as for a
|
||||
// pointer type instead:
|
||||
value_test(boost::alignment_of<T*>::value, boost::alignment_of<T&>::value);
|
||||
}
|
||||
};
|
||||
#endif
|
||||
|
||||
#define align_test(T) test_align<T>::do_it()
|
||||
|
||||
//
|
||||
// define tests here
|
||||
|
||||
//
|
||||
// turn off some warnings:
|
||||
#ifdef __BORLANDC__
|
||||
#pragma option -w-8004
|
||||
#endif
|
||||
|
||||
#ifdef BOOST_MSVC
|
||||
#pragma warning (disable: 4018)
|
||||
#endif
|
||||
|
||||
|
||||
#endif // BOOST_TYPE_TRAITS_TEST_HPP
|
||||
|
||||
Reference in New Issue
Block a user