Squashed 'third_party/boostorg/utility/' content from commit ebe4429
Change-Id: I8e6ee78273db31df18f99d29034f855ccc064551
git-subtree-dir: third_party/boostorg/utility
git-subtree-split: ebe44296ca698e333a09e8268ea8ccedb3886c4d
diff --git a/operators.htm b/operators.htm
new file mode 100644
index 0000000..993436c
--- /dev/null
+++ b/operators.htm
@@ -0,0 +1,2144 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+
+<html>
+ <head>
+ <meta name="generator" content=
+ "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+
+ <title>Header <boost/operators.hpp> Documentation</title>
+ </head>
+
+ <body text="black" bgcolor="white" link="blue" vlink="purple" alink="red">
+ <h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align=
+ "middle" width="277" height="86">Header <cite><<a href=
+ "../../boost/operators.hpp">boost/operators.hpp</a>></cite></h1>
+
+ <p>The header <cite><<a href=
+ "../../boost/operators.hpp">boost/operators.hpp</a>></cite> supplies
+ several sets of class templates (in namespace <code>boost</code>). These
+ templates define operators at namespace scope in terms of a minimal
+ number of fundamental operators provided by the class.</p>
+
+ <h2><a name="contents">Contents</a></h2>
+
+ <ul>
+ <li><a href="#contents">Contents</a></li>
+
+ <li>
+ <a href="#rationale">Rationale</a>
+
+ <ul>
+ <li><a href="#semantics">Summary of Template Semantics</a></li>
+
+ <li><a href="#concepts_note">Use of <i>concepts</i></a></li>
+ </ul>
+ </li>
+
+ <li>
+ <a href="#usage">Usage</a>
+
+ <ul>
+ <li>
+ <a href="#two_arg">Two-Argument Template Forms</a>
+
+ <ul>
+ <li><a href="#two_arg_gen">General Considerations</a></li>
+
+ <li><a href="#mixed_arithmetics">Mixed arithmetics</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#chaining">Base Class Chaining and Object
+ Size</a></li>
+
+ <li><a href="#explicit_instantiation">Separate, Explicit
+ Instantiation</a></li>
+
+ <li><a href="#portability">Requirement Portability</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#example">Example</a></li>
+
+ <li>
+ <a href="#arithmetic">Arithmetic operators</a>
+
+ <ul>
+ <li>
+ <a href="#smpl_oprs">Simple Arithmetic Operators</a>
+
+ <ul>
+ <li><a href="#ordering">Ordering Note</a></li>
+
+ <li><a href="#symmetry">Symmetry Note</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#grpd_oprs">Grouped Arithmetic Operators</a></li>
+
+ <li><a href="#ex_oprs">Example Templates</a></li>
+
+ <li><a href="#a_demo">Arithmetic Operators Demonstration and Test
+ Program</a></li>
+ </ul>
+ </li>
+
+ <li>
+ <a href="#deref">Dereference Operators and Iterator Helpers</a>
+
+ <ul>
+ <li><a href="#dereference">Dereference operators</a></li>
+
+ <li><a href="#grpd_iter_oprs">Grouped Iterator Operators</a></li>
+
+ <li>
+ <a href="#iterator">Iterator Helpers</a>
+
+ <ul>
+ <li><a href="#iterator_helpers_notes">Iterator Helper
+ Notes</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#i_demo">Iterator Demonstration and Test
+ Program</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#contributors">Contributors</a></li>
+
+ <li><a href="#old_lib_note">Note for Users of Older Versions</a></li>
+ </ul>
+
+ <h2><a name="rationale">Rationale</a></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
+ <=> !(x < y)</code>). Replicating this boilerplate for multiple
+ classes is both tedious and error-prone. The <cite><a href=
+ "../../boost/operators.hpp">boost/operators.hpp</a></cite> templates help
+ by generating operators for you at namespace scope based on other
+ operators you've defined in your class.</p>
+
+ <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><a href="#operators1">operators<></a></code>
+ template adds more than a dozen additional operators, such as
+ <code>operator></code>, <code><=</code>, <code>>=</code>, and
+ (binary) <code>+</code>. <a href="#two_arg">Two-argument forms</a> of the
+ templates are also provided to allow interaction with other types.</p>
+
+ <h3>Summary of Template <a name="semantics">Semantics</a></h3>
+
+ <ol>
+ <li>Each operator template completes the concept(s) it describes by
+ defining overloaded operators for its target class.</li>
+
+ <li>The name of an operator class template indicates the <a href=
+ "#concepts_note">concept</a> that its target class will model.</li>
+
+ <li>Usually, the target class uses an instantation of the operator
+ class template as a base class. Some operator templates support an <a
+ href="#explicit_instantiation">alternate method</a>.</li>
+
+ <li>The concept can be compound, <i>i.e.</i> it may represent a common
+ combination of other, simpler concepts.</li>
+
+ <li>Most operator templates require their target class to support
+ operations related to the operators supplied by the template. In
+ accordance with widely accepted <a href=
+ "http://www.gotw.ca/gotw/004.htm">coding style recommendations</a>, the
+ target class is often required to supply the assignment counterpart
+ operator of the concept's "main operator." For example, the
+ <code>addable</code> template requires <code>operator+=(T
+ const&)</code> and in turn supplies <code>operator+(T const&, T
+ const&)</code>.</li>
+ </ol>
+
+ <h3>Use of <i><a name="concepts_note">concepts</a></i></h3>
+
+ <p>The discussed concepts are not necessarily the standard library's
+ concepts (CopyConstructible, <i>etc.</i>), although some of them could
+ be; they are what we call <i>concepts with a small 'c'</i>. In
+ particular, they are different from the former ones in that they <em>do
+ not</em> describe precise semantics of the operators they require to be
+ defined, except the requirements that (a) the semantics of the operators
+ grouped in one concept should be consistent (<i>e.g.</i> effects of
+ evaluating of <code>a += b</code> and
+ <code>a = a + b</code> expressions should be the
+ same), and (b) that the return types of the operators should follow
+ semantics of return types of corresponding operators for built-in types
+ (<i>e.g.</i> <code>operator<</code> should return a type convertible
+ to <code>bool</code>, and <code>T::operator-=</code> should return type
+ convertible to <code>T</code>). Such "loose" requirements make operators
+ library applicable to broader set of target classes from different
+ domains, <i>i.e.</i> eventually more useful.</p>
+
+ <h2><a name="usage">Usage</a></h2>
+
+ <h3><a name="two_arg">Two-Argument</a> Template Forms</h3>
+
+ <h4><a name="two_arg_gen">General Considerations</a></h4>
+
+ <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="#example">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><a href=
+ "#addable2">addable<T, U></a></code>. The comparison templates
+ (<code><a href="#less_than_comparable2">less_than_comparable<T,
+ U></a></code>, <code><a href=
+ "#equality_comparable2">equality_comparable<T, U></a></code>,
+ <code><a href="#equivalent2">equivalent<T, U></a></code>, and
+ <code><a href="#partially_ordered2">partially_ordered<T,
+ U></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>
+
+ <h4><a name="mixed_arithmetics">Mixed Arithmetics</a></h4>
+
+ <p>Another application of the two-argument template forms is for mixed
+ arithmetics between a type <code>T</code> and a type <code>U</code> that
+ is convertible to <code>T</code>. In this case there are two ways where
+ the two-argument template forms are helpful: one is to provide the
+ respective signatures for operator overloading, the second is
+ performance.</p>
+
+ <p>With respect to the operator overloading assume <i>e.g.</i> that
+ <code>U</code> is <code>int</code>, that <code>T</code> is an
+ user-defined unlimited integer type, and that <code>double
+ operator-(double, const T&)</code> exists. If one wants to compute
+ <code>int - T</code> and does not provide <code>T operator-(int, const
+ T&)</code>, the compiler will consider <code>double operator-(double,
+ const T&)</code> to be a better match than <code>T operator-(const
+ T&, const T&)</code>, which will probably be different from the
+ user's intention. To define a complete set of operator signatures,
+ additional 'left' forms of the two-argument template forms are provided
+ (<code><a href="#subtractable2_left">subtractable2_left<T,
+ U></a></code>, <code><a href="#dividable2_left">dividable2_left<T,
+ U></a></code>, <code><a href="#modable2_left">modable2_left<T,
+ U></a></code>) that define the signatures for non-commutative
+ operators where <code>U</code> appears on the left hand side
+ (<code>operator-(const U&, const T&)</code>,
+ <code>operator/(const U&, const T&)</code>, <code>operator%(const
+ U&, const T&)</code>).</p>
+
+ <p>With respect to the performance observe that when one uses the single
+ type binary operator for mixed type arithmetics, the type <code>U</code>
+ argument has to be converted to type <code>T</code>. In practice,
+ however, there are often more efficient implementations of, say
+ <code>T::operator-=(const U&)</code> that avoid unnecessary
+ conversions from <code>U</code> to <code>T</code>. The two-argument
+ template forms of the arithmetic operator create additional operator
+ interfaces that use these more efficient implementations. There is,
+ however, no performance gain in the 'left' forms: they still need a
+ conversion from <code>U</code> to <code>T</code> and have an
+ implementation equivalent to the code that would be automatically created
+ by the compiler if it considered the single type binary operator to be
+ the best match.</p>
+
+ <h3>Base Class <a name="chaining">Chaining</a> and Object Size</h3>
+
+ <p>Every operator class template, except the <a href=
+ "#ex_oprs">arithmetic examples</a> and the <a href="#iterator">iterator
+ helpers</a>, has an additional, but optional, template type parameter
+ <code>B</code>. This parameter will be a publicly-derived base class of
+ the instantiated template. This means it must be a class type. It can be
+ used to avoid the bloating of object sizes that is commonly associated
+ with multiple-inheritance from several empty base classes (see the <a
+ href="#old_lib_note">note for users of older versions</a> for more
+ details). To provide support for a group of operators, use the
+ <code>B</code> parameter to chain operator templates into a single-base
+ class hierarchy, demostrated in the <a href="#example">usage example</a>.
+ The technique is also used by the composite operator templates to group
+ operator definitions. If a chain becomes too long for the compiler to
+ support, try replacing some of the operator templates with a single
+ grouped operator template that chains the old templates together; the
+ length limit only applies to the number of templates directly in the
+ chain, not those hidden in group templates.</p>
+
+ <p><strong>Caveat:</strong> to chain to a base class which is
+ <em>not</em> a Boost operator template when using the <a href=
+ "#two_arg">single-argument form</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>
+
+ <h3>Separate, <a name="explicit_instantiation">Explicit
+ Instantiation</a></h3>
+
+ <p>On some compilers (<i>e.g.</i> Borland, GCC) even single-inheritance
+ seems to cause an increase in object size in some cases. If you are not
+ defining a class template, you may get better object-size performance by
+ avoiding derivation altogether, and instead explicitly instantiating the
+ operator template as follows:</p>
+
+ <blockquote>
+<pre>
+ class myclass // lose the inheritance...
+ {
+ //...
+ };
+
+ // explicitly instantiate the operators I need.
+ template struct less_than_comparable<myclass>;
+ template struct equality_comparable<myclass>;
+ template struct incrementable<myclass>;
+ template struct decrementable<myclass>;
+ template struct addable<myclass,long>;
+ template struct subtractable<myclass,long>;
+</pre>
+ </blockquote>
+
+ <p>Note that some operator templates cannot use this workaround and must
+ be a base class of their primary operand type. Those templates define
+ operators which must be member functions, and the workaround needs the
+ operators to be independent friend functions. The relevant templates
+ are:</p>
+
+ <ul>
+ <li><code><a href=
+ "#dereferenceable">dereferenceable<></a></code></li>
+
+ <li><code><a href="#indexable">indexable<></a></code></li>
+
+ <li>Any composite operator template that includes at least one of the
+ above</li>
+ </ul>
+
+ <p>As Daniel Krügler pointed out, this technique violates 14.6.5/2
+ and is thus non-portable. The reasoning is, that the operators injected
+ by the instantiation of e.g.
+ <code>less_than_comparable<myclass></code> can not be found
+ by ADL according to the rules given by 3.4.2/2, since myclass is
+ not an associated class of
+ <code>less_than_comparable<myclass></code>.
+ Thus only use this technique if all else fails.</p>
+
+ <h3>Requirement <a name="portability">Portability</a></h3>
+
+ <p>Many compilers (<i>e.g.</i> MSVC 6.3, GCC 2.95.2) will not enforce the
+ requirements in the operator template tables unless the operations which
+ depend on them are actually used. This is not standard-conforming
+ behavior. In particular, although it would be convenient to derive all
+ your classes which need binary operators from the <code><a href=
+ "#operators1">operators<></a></code> and <code><a href=
+ "#operators2">operators2<></a></code> templates, regardless of
+ whether they implement all the requirements of those templates, this
+ shortcut is not portable. Even if this currently works with your
+ compiler, it may not work later.</p>
+
+ <h2><a name="example">Example</a></h2>
+
+ <p>This example shows how some of the <a href="#arithmetic">arithmetic
+ operator templates</a> can be used with a geometric point class
+ (template).</p>
+<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><a name="arithmetic">Arithmetic</a> Operators</h2>
+
+ <p>The arithmetic operator templates ease the task of creating a custom
+ numeric type. Given a core set of operators, the templates add related
+ operators to the numeric class. These operations are like the ones the
+ standard arithmetic types have, and may include comparisons, adding,
+ incrementing, logical and bitwise manipulations, <i>etc</i>. Further,
+ since most numeric types need more than one of these operators, some
+ templates are provided to combine several of the basic operator templates
+ in one declaration.</p>
+
+ <p>The requirements for the types used to instantiate the simple operator
+ templates are specified in terms of expressions which must be valid and
+ the expression's return type. The composite operator templates only list
+ what other templates they use. The supplied operations and requirements
+ of the composite operator templates can be inferred from the operations
+ and requirements of the listed components.</p>
+
+ <h3><a name="smpl_oprs">Simple Arithmetic Operators</a></h3>
+
+ <p>These templates are "simple" since they provide operators based on a
+ single operation the base type has to provide. They have an additional
+ optional template parameter <code>B</code>, which is not shown, for the
+ <a href="#chaining">base class chaining</a> technique.</p>
+
+ <p>The primary operand type <code>T</code> needs to be of class type,
+ built-in types are not supported.</p>
+
+ <table cellpadding="5" border="1" align="center">
+ <caption>
+ Simple Arithmetic Operator Template Classes
+ </caption>
+
+ <tr>
+ <td colspan="3">
+ <table align="center" border="1">
+ <caption>
+ <em>Key</em>
+ </caption>
+
+ <tr>
+ <td><code>T</code>: primary operand type</td>
+
+ <td><code>U</code>: alternate operand type</td>
+ </tr>
+
+ <tr>
+ <td><code>t</code>, <code>t1</code>: values of type
+ <code>T</code></td>
+
+ <td><code>u</code>: value of type <code>U</code></td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>Template</th>
+
+ <th>Supplied Operations</th>
+
+ <th>Requirements</th>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "less_than_comparable1">less_than_comparable<T></a></code><br>
+ <code>less_than_comparable1<T></code></td>
+
+ <td><code>bool operator>(const T&, const T&)</code><br>
+ <code>bool operator<=(const T&, const T&)</code><br>
+ <code>bool operator>=(const T&, const T&)</code></td>
+
+ <td><code>t < t1</code>.<br>
+ Return convertible to <code>bool</code>. See the <a href=
+ "#ordering">Ordering Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="less_than_comparable2">less_than_comparable<T,
+ U></a></code><br>
+ <code>less_than_comparable2<T, U></code></td>
+
+ <td><code>bool operator<=(const T&, const U&)</code><br>
+ <code>bool operator>=(const T&, const U&)</code><br>
+ <code>bool operator>(const U&, const T&)</code><br>
+ <code>bool operator<(const U&, const T&)</code><br>
+ <code>bool operator<=(const U&, const T&)</code><br>
+ <code>bool operator>=(const U&, const T&)</code></td>
+
+ <td><code>t < u</code>. <code>t > u</code>.<br>
+ Returns convertible to <code>bool</code>. See the <a href=
+ "#ordering">Ordering Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "equality_comparable1">equality_comparable<T></a></code><br>
+ <code>equality_comparable1<T></code></td>
+
+ <td><code>bool operator!=(const T&, const T&)</code></td>
+
+ <td><code>t == t1</code>.<br>
+ Return convertible to <code>bool</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="equality_comparable2">equality_comparable<T,
+ U></a></code><br>
+ <code>equality_comparable2<T, U></code></td>
+
+ <td><code>bool operator==(const U&, const T&)</code><br>
+ <code>bool operator!=(const U&, const T&)</code><br>
+ <code>bool operator!=(const T&, const U&)</code></td>
+
+ <td><code>t == u</code>.<br>
+ Return convertible to <code>bool</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="addable1">addable<T></a></code><br>
+ <code>addable1<T></code></td>
+
+ <td><code>T operator+(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp += t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="addable2">addable<T, U></a></code><br>
+ <code>addable2<T, U></code></td>
+
+ <td><code>T operator+(const T&, const U&)</code><br>
+ <code>T operator+(const U&, const T& )</code></td>
+
+ <td><code>T temp(t); temp += u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "subtractable1">subtractable<T></a></code><br>
+ <code>subtractable1<T></code></td>
+
+ <td><code>T operator-(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp -= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="subtractable2">subtractable<T,
+ U></a></code><br>
+ <code>subtractable2<T, U></code></td>
+
+ <td><code>T operator-(const T&, const U&)</code></td>
+
+ <td><code>T temp(t); temp -= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="subtractable2_left">subtractable2_left<T,
+ U></a></code></td>
+
+ <td><code>T operator-(const U&, const T&)</code></td>
+
+ <td><code>T temp(u); temp -= t</code>.<br>
+ Return convertible to <code>T</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "multipliable1">multipliable<T></a></code><br>
+ <code>multipliable1<T></code></td>
+
+ <td><code>T operator*(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp *= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="multipliable2">multipliable<T,
+ U></a></code><br>
+ <code>multipliable2<T, U></code></td>
+
+ <td><code>T operator*(const T&, const U&)</code><br>
+ <code>T operator*(const U&, const T&)</code></td>
+
+ <td><code>T temp(t); temp *= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="dividable1">dividable<T></a></code><br>
+ <code>dividable1<T></code></td>
+
+ <td><code>T operator/(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp /= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="dividable2">dividable<T, U></a></code><br>
+ <code>dividable2<T, U></code></td>
+
+ <td><code>T operator/(const T&, const U&)</code></td>
+
+ <td><code>T temp(t); temp /= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="dividable2_left">dividable2_left<T,
+ U></a></code></td>
+
+ <td><code>T operator/(const U&, const T&)</code></td>
+
+ <td><code>T temp(u); temp /= t</code>.<br>
+ Return convertible to <code>T</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="modable1">modable<T></a></code><br>
+ <code>modable1<T></code></td>
+
+ <td><code>T operator%(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp %= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="modable2">modable<T, U></a></code><br>
+ <code>modable2<T, U></code></td>
+
+ <td><code>T operator%(const T&, const U&)</code></td>
+
+ <td><code>T temp(t); temp %= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="modable2_left">modable2_left<T,
+ U></a></code></td>
+
+ <td><code>T operator%(const U&, const T&)</code></td>
+
+ <td><code>T temp(u); temp %= t</code>.<br>
+ Return convertible to <code>T</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="orable1">orable<T></a></code><br>
+ <code>orable1<T></code></td>
+
+ <td><code>T operator|(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp |= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="orable2">orable<T, U></a></code><br>
+ <code>orable2<T, U></code></td>
+
+ <td><code>T operator|(const T&, const U&)</code><br>
+ <code>T operator|(const U&, const T&)</code></td>
+
+ <td><code>T temp(t); temp |= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="andable1">andable<T></a></code><br>
+ <code>andable1<T></code></td>
+
+ <td><code>T operator&(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp &= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="andable2">andable<T, U></a></code><br>
+ <code>andable2<T, U></code></td>
+
+ <td><code>T operator&(const T&, const U&)</code><br>
+ <code>T operator&(const U&, const T&)</code></td>
+
+ <td><code>T temp(t); temp &= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="xorable1">xorable<T></a></code><br>
+ <code>xorable1<T></code></td>
+
+ <td><code>T operator^(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp ^= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="xorable2">xorable<T, U></a></code><br>
+ <code>xorable2<T, U></code></td>
+
+ <td><code>T operator^(const T&, const U&)</code><br>
+ <code>T operator^(const U&, const T&)</code></td>
+
+ <td><code>T temp(t); temp ^= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "incrementable">incrementable<T></a></code></td>
+
+ <td><code>T operator++(T&, int)</code></td>
+
+ <td><code>T temp(t); ++t</code><br>
+ Return convertible to <code>T</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "decrementable">decrementable<T></a></code></td>
+
+ <td><code>T operator--(T&, int)</code></td>
+
+ <td><code>T temp(t); --t;</code><br>
+ Return convertible to <code>T</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "left_shiftable1">left_shiftable<T></a></code><br>
+ <code>left_shiftable1<T></code></td>
+
+ <td><code>T operator<<(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp <<= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="left_shiftable2">left_shiftable<T,
+ U></a></code><br>
+ <code>left_shiftable2<T, U></code></td>
+
+ <td><code>T operator<<(const T&, const U&)</code></td>
+
+ <td><code>T temp(t); temp <<= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "right_shiftable1">right_shiftable<T></a></code><br>
+ <code>right_shiftable1<T></code></td>
+
+ <td><code>T operator>>(const T&, const T&)</code></td>
+
+ <td><code>T temp(t); temp >>= t1</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="right_shiftable2">right_shiftable<T,
+ U></a></code><br>
+ <code>right_shiftable2<T, U></code></td>
+
+ <td><code>T operator>>(const T&, const U&)</code></td>
+
+ <td><code>T temp(t); temp >>= u</code>.<br>
+ Return convertible to <code>T</code>. See the <a href=
+ "#symmetry">Symmetry Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="equivalent1">equivalent<T></a></code><br>
+ <code>equivalent1<T></code></td>
+
+ <td><code>bool operator==(const T&, const T&)</code></td>
+
+ <td><code>t < t1</code>.<br>
+ Return convertible to <code>bool</code>. See the <a href=
+ "#ordering">Ordering Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="equivalent2">equivalent<T, U></a></code><br>
+ <code>equivalent2<T, U></code></td>
+
+ <td><code>bool operator==(const T&, const U&)</code></td>
+
+ <td><code>t < u</code>. <code>t > u</code>.<br>
+ Returns convertible to <code>bool</code>. See the <a href=
+ "#ordering">Ordering Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "partially_ordered1">partially_ordered<T></a></code><br>
+ <code>partially_ordered1<T></code></td>
+
+ <td><code>bool operator>(const T&, const T&)</code><br>
+ <code>bool operator<=(const T&, const T&)</code><br>
+ <code>bool operator>=(const T&, const T&)</code></td>
+
+ <td><code>t < t1</code>. <code>t == t1</code>.<br>
+ Returns convertible to <code>bool</code>. See the <a href=
+ "#ordering">Ordering Note</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="partially_ordered2">partially_ordered<T,
+ U></a></code><br>
+ <code>partially_ordered2<T, U></code></td>
+
+ <td><code>bool operator<=(const T&, const U&)</code><br>
+ <code>bool operator>=(const T&, const U&)</code><br>
+ <code>bool operator>(const U&, const T&)</code><br>
+ <code>bool operator<(const U&, const T&)</code><br>
+ <code>bool operator<=(const U&, const T&)</code><br>
+ <code>bool operator>=(const U&, const T&)</code></td>
+
+ <td><code>t < u</code>. <code>t > u</code>. <code>t ==
+ u</code>.<br>
+ Returns convertible to <code>bool</code>. See the <a href=
+ "#ordering">Ordering Note</a>.</td>
+ </tr>
+ </table>
+
+ <h4><a name="ordering">Ordering</a> Note</h4>
+
+ <p>The <code><a href=
+ "#less_than_comparable1">less_than_comparable<T></a></code> and
+ <code><a href="#partially_ordered1">partially_ordered<T></a></code>
+ templates provide the same set of operations. However, the workings of
+ <code><a href=
+ "#less_than_comparable1">less_than_comparable<T></a></code> assume
+ that all values of type <code>T</code> can be placed in a total order. If
+ that is not true (<i>e.g.</i> Not-a-Number values in IEEE floating point
+ arithmetic), then <code><a href=
+ "#partially_ordered1">partially_ordered<T></a></code> should be
+ used. The <code><a href=
+ "#partially_ordered1">partially_ordered<T></a></code> template can
+ be used for a totally-ordered type, but it is not as efficient as
+ <code><a href=
+ "#less_than_comparable1">less_than_comparable<T></a></code>. This
+ rule also applies for <code><a href=
+ "#less_than_comparable2">less_than_comparable<T, U></a></code> and
+ <code><a href="#partially_ordered2">partially_ordered<T,
+ U></a></code> with respect to the ordering of all <code>T</code> and
+ <code>U</code> values, and for both versions of <code><a href=
+ "#equivalent1">equivalent<></a></code>. The solution for <code><a
+ href="#equivalent1">equivalent<></a></code> is to write a custom
+ <code>operator==</code> for the target class.</p>
+
+ <h4><a name="symmetry">Symmetry</a> Note</h4>
+
+ <p>Before talking about symmetry, we need to talk about optimizations to
+ understand the reasons for the different implementation styles of
+ operators. Let's have a look at <code>operator+</code> for a class
+ <code>T</code> as an example:</p>
+<pre>
+T operator+( const T& lhs, const T& rhs )
+{
+ return T( lhs ) += rhs;
+}
+</pre>
+ This would be a normal implementation of <code>operator+</code>, but it
+ is not an efficient one. An unnamed local copy of <code>lhs</code> is
+ created, <code>operator+=</code> is called on it and it is copied to the
+ function return value (which is another unnamed object of type
+ <code>T</code>). The standard doesn't generally allow the intermediate
+ object to be optimized away:
+
+ <blockquote>
+ 3.7.2/2: Automatic storage duration<br>
+ <br>
+ If a named automatic object has initialization or a destructor with
+ side effects, it shall not be destroyed before the end of its block,
+ nor shall it be eliminated as an optimization even if it appears to be
+ unused, except that a class object or its copy may be eliminated as
+ specified in 12.8.
+ </blockquote>
+ The reference to 12.8 is important for us:
+
+ <blockquote>
+ 12.8/15: Copying class objects<br>
+ ...<br>
+ For a function with a class return type, if the expression in the
+ return statement is the name of a local object, and the cv-unqualified
+ type of the local object is the same as the function return type, an
+ implementation is permitted to omit creating the temporary object to
+ hold the function return value, even if the class copy constructor or
+ destructor has side effects.
+ </blockquote>
+ This optimization is known as the named return value optimization (NRVO),
+ which leads us to the following implementation for
+ <code>operator+</code>:
+<pre>
+T operator+( const T& lhs, const T& rhs )
+{
+ T nrv( lhs );
+ nrv += rhs;
+ return nrv;
+}
+</pre>
+ Given this implementation, the compiler is allowed to remove the
+ intermediate object. Sadly, not all compiler implement the NRVO, some
+ even implement it in an incorrect way which makes it useless here.
+ Without the NRVO, the NRVO-friendly code is no worse than the original
+ code showed above, but there is another possible implementation, which
+ has some very special properties:
+<pre>
+T operator+( T lhs, const T& rhs )
+{
+ return lhs += rhs;
+}
+</pre>
+ The difference to the first implementation is that <code>lhs</code> is
+ not taken as a constant reference used to create a copy; instead,
+ <code>lhs</code> is a by-value parameter, thus it is already the copy
+ needed. This allows another optimization (12.2/2) for some cases.
+ Consider <code>a + b + c</code> where the result of
+ <code>a + b</code> is not copied when used as <code>lhs</code>
+ when adding <code>c</code>. This is more efficient than the original
+ code, but not as efficient as a compiler using the NRVO. For most people,
+ it is still preferable for compilers that don't implement the NRVO, but
+ the <code>operator+</code> now has a different function signature. Also,
+ the number of objects created differs for
+ <code>(a + b ) + c</code> and
+ <code>a + ( b + c )</code>. Most probably,
+ this won't be a problem for you, but if your code relies on the function
+ signature or a strict symmetric behaviour, you should set
+ <code>BOOST_FORCE_SYMMETRIC_OPERATORS</code> in your user-config. This
+ will force the NRVO-friendly implementation to be used even for compilers
+ that don't implement the NRVO. <br>
+ <br>
+
+ <h3><a name="grpd_oprs">Grouped Arithmetic Operators</a></h3>
+
+ <p>The following templates provide common groups of related operations.
+ For example, since a type which is addable is usually also subractable,
+ the <code><a href="#additive1">additive</a></code> template provides the
+ combined operators of both. The grouped operator templates have an
+ additional optional template parameter <code>B</code>, which is not
+ shown, for the <a href="#chaining">base class chaining</a> technique.</p>
+
+ <table cellpadding="5" border="1" align="center">
+ <caption>
+ Grouped Arithmetic Operator Template Classes
+ </caption>
+
+ <tr>
+ <td colspan="2">
+ <table align="center" border="1">
+ <caption>
+ <em>Key</em>
+ </caption>
+
+ <tr>
+ <td><code>T</code>: primary operand type</td>
+
+ <td><code>U</code>: alternate operand type</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>Template</th>
+
+ <th>Component Operator Templates</th>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "totally_ordered1">totally_ordered<T></a></code><br>
+ <code>totally_ordered1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#less_than_comparable1">less_than_comparable<T></a></code></li>
+
+ <li><code><a href=
+ "#equality_comparable1">equality_comparable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="totally_ordered2">totally_ordered<T,
+ U></a></code><br>
+ <code>totally_ordered2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#less_than_comparable2">less_than_comparable<T,
+ U></a></code></li>
+
+ <li><code><a href=
+ "#equality_comparable2">equality_comparable<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="additive1">additive<T></a></code><br>
+ <code>additive1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#addable1">addable<T></a></code></li>
+
+ <li><code><a href=
+ "#subtractable1">subtractable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="additive2">additive<T, U></a></code><br>
+ <code>additive2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#addable2">addable<T, U></a></code></li>
+
+ <li><code><a href="#subtractable2">subtractable<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "multiplicative1">multiplicative<T></a></code><br>
+ <code>multiplicative1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#multipliable1">multipliable<T></a></code></li>
+
+ <li><code><a href=
+ "#dividable1">dividable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="multiplicative2">multiplicative<T,
+ U></a></code><br>
+ <code>multiplicative2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#multipliable2">multipliable<T,
+ U></a></code></li>
+
+ <li><code><a href="#dividable2">dividable<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "integer_multiplicative1">integer_multiplicative<T></a></code><br>
+
+ <code>integer_multiplicative1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#multiplicative1">multiplicative<T></a></code></li>
+
+ <li><code><a href="#modable1">modable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "integer_multiplicative2">integer_multiplicative<T,
+ U></a></code><br>
+ <code>integer_multiplicative2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#multiplicative2">multiplicative<T,
+ U></a></code></li>
+
+ <li><code><a href="#modable2">modable<T, U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="arithmetic1">arithmetic<T></a></code><br>
+ <code>arithmetic1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#additive1">additive<T></a></code></li>
+
+ <li><code><a href=
+ "#multiplicative1">multiplicative<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="arithmetic2">arithmetic<T, U></a></code><br>
+ <code>arithmetic2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#additive2">additive<T,
+ U></a></code></li>
+
+ <li><code><a href="#multiplicative2">multiplicative<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "integer_arithmetic1">integer_arithmetic<T></a></code><br>
+ <code>integer_arithmetic1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#additive1">additive<T></a></code></li>
+
+ <li><code><a href=
+ "#integer_multiplicative1">integer_multiplicative<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="integer_arithmetic2">integer_arithmetic<T,
+ U></a></code><br>
+ <code>integer_arithmetic2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#additive2">additive<T,
+ U></a></code></li>
+
+ <li><code><a href=
+ "#integer_multiplicative2">integer_multiplicative<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="bitwise1">bitwise<T></a></code><br>
+ <code>bitwise1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#xorable1">xorable<T></a></code></li>
+
+ <li><code><a href="#andable1">andable<T></a></code></li>
+
+ <li><code><a href="#orable1">orable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="bitwise2">bitwise<T, U></a></code><br>
+ <code>bitwise2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#xorable2">xorable<T, U></a></code></li>
+
+ <li><code><a href="#andable2">andable<T, U></a></code></li>
+
+ <li><code><a href="#orable2">orable<T, U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "unit_steppable">unit_steppable<T></a></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#incrementable">incrementable<T></a></code></li>
+
+ <li><code><a href=
+ "#decrementable">decrementable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="shiftable1">shiftable<T></a></code><br>
+ <code>shiftable1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#left_shiftable1">left_shiftable<T></a></code></li>
+
+ <li><code><a href=
+ "#right_shiftable1">right_shiftable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="shiftable2">shiftable<T, U></a></code><br>
+ <code>shiftable2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#left_shiftable2">left_shiftable<T,
+ U></a></code></li>
+
+ <li><code><a href="#right_shiftable2">right_shiftable<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "ring_operators1">ring_operators<T></a></code><br>
+ <code>ring_operators1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#additive1">additive<T></a></code></li>
+
+ <li><code><a href=
+ "#multipliable1">multipliable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="ring_operators2">ring_operators<T,
+ U></a></code><br>
+ <code>ring_operators2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#additive2">additive<T,
+ U></a></code></li>
+
+ <li><code><a href="#subtractable2_left">subtractable2_left<T,
+ U></a></code></li>
+
+ <li><code><a href="#multipliable2">multipliable<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "ordered_ring_operators1">ordered_ring_operators<T></a></code><br>
+
+ <code>ordered_ring_operators1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#ring_operators1">ring_operators<T></a></code></li>
+
+ <li><code><a href=
+ "#totally_ordered1">totally_ordered<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "ordered_ring_operators2">ordered_ring_operators<T,
+ U></a></code><br>
+ <code>ordered_ring_operators2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#ring_operators2">ring_operators<T,
+ U></a></code></li>
+
+ <li><code><a href="#totally_ordered2">totally_ordered<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "field_operators1">field_operators<T></a></code><br>
+ <code>field_operators1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#ring_operators1">ring_operators<T></a></code></li>
+
+ <li><code><a href=
+ "#dividable1">dividable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="field_operators2">field_operators<T,
+ U></a></code><br>
+ <code>field_operators2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#ring_operators2">ring_operators<T,
+ U></a></code></li>
+
+ <li><code><a href="#dividable2">dividable<T,
+ U></a></code></li>
+
+ <li><code><a href="#dividable2_left">dividable2_left<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "ordered_field_operators1">ordered_field_operators<T></a></code><br>
+
+ <code>ordered_field_operators1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#field_operators1">field_operators<T></a></code></li>
+
+ <li><code><a href=
+ "#totally_ordered1">totally_ordered<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "ordered_field_operators2">ordered_field_operators<T,
+ U></a></code><br>
+ <code>ordered_field_operators2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#field_operators2">field_operators<T,
+ U></a></code></li>
+
+ <li><code><a href="#totally_ordered2">totally_ordered<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "euclidean_ring_operators1">euclidean_ring_operators<T></a></code><br>
+
+ <code>euclidean_ring_operators1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#ring_operators1">ring_operators<T></a></code></li>
+
+ <li><code><a href=
+ "#dividable1">dividable<T></a></code></li>
+
+ <li><code><a href="#modable1">modable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "euclidean_ring_operators2">euclidean_ring_operators<T,
+ U></a></code><br>
+ <code>euclidean_ring_operators2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#ring_operators2">ring_operators<T,
+ U></a></code></li>
+
+ <li><code><a href="#dividable2">dividable<T,
+ U></a></code></li>
+
+ <li><code><a href="#dividable2_left">dividable2_left<T,
+ U></a></code></li>
+
+ <li><code><a href="#modable2">modable<T, U></a></code></li>
+
+ <li><code><a href="#modable2_left">modable2_left<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "ordered_euclidean_ring_operators1">ordered_euclidean_ring_operators<T></a></code><br>
+
+ <code>ordered_euclidean_ring_operators1<T></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#euclidean_ring_operators1">euclidean_ring_operators<T></a></code></li>
+
+ <li><code><a href=
+ "#totally_ordered1">totally_ordered<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "ordered_euclidean_ring_operators2">ordered_euclidean_ring_operators<T,
+ U></a></code><br>
+ <code>ordered_euclidean_ring_operators2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#euclidean_ring_operators2">euclidean_ring_operators<T,
+ U></a></code></li>
+
+ <li><code><a href="#totally_ordered2">totally_ordered<T,
+ U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+
+ <h4>Spelling: euclidean vs. euclidian</h4>
+
+ <p>Older versions of the Boost.Operators library used
+ "<code>euclidian</code>", but it was pointed out that
+ "<code>euclidean</code>" is the more common spelling.
+ To be compatible with older version, the library now supports
+ both spellings.
+ </p>
+
+ <h3><a name="ex_oprs">Example</a> Templates</h3>
+
+ <p>The arithmetic operator class templates <code><a href=
+ "#operators1">operators<></a></code> and <code><a href=
+ "#operators2">operators2<></a></code> are examples of
+ non-extensible operator grouping classes. These legacy class templates,
+ from previous versions of the header, cannot be used for <a href=
+ "#chaining">base class chaining</a>.</p>
+
+ <table cellpadding="5" border="1" align="center">
+ <caption>
+ Final Arithmetic Operator Template Classes
+ </caption>
+
+ <tr>
+ <td colspan="2">
+ <table align="center" border="1">
+ <caption>
+ <em>Key</em>
+ </caption>
+
+ <tr>
+ <td><code>T</code>: primary operand type</td>
+
+ <td><code>U</code>: alternate operand type</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>Template</th>
+
+ <th>Component Operator Templates</th>
+ </tr>
+
+ <tr>
+ <td><code><a name="operators1">operators<T></a></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#totally_ordered1">totally_ordered<T></a></code></li>
+
+ <li><code><a href=
+ "#integer_arithmetic1">integer_arithmetic<T></a></code></li>
+
+ <li><code><a href="#bitwise1">bitwise<T></a></code></li>
+
+ <li><code><a href=
+ "#unit_steppable">unit_steppable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="operators2">operators<T, U></a></code><br>
+ <code>operators2<T, U></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#totally_ordered2">totally_ordered<T,
+ U></a></code></li>
+
+ <li><code><a href="#integer_arithmetic2">integer_arithmetic<T,
+ U></a></code></li>
+
+ <li><code><a href="#bitwise2">bitwise<T, U></a></code></li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+
+ <h3><a name="a_demo">Arithmetic Operators Demonstration</a> and Test
+ Program</h3>
+
+ <p>The <cite><a href="operators_test.cpp">operators_test.cpp</a></cite>
+ program demonstrates the use of the arithmetic operator templates, and
+ can also be used to verify correct operation. Check the compiler status
+ report for the test results with selected platforms.</p>
+
+ <h2><a name="deref">Dereference</a> Operators and Iterator Helpers</h2>
+
+ <p>The <a href="#iterator">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">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>)!</p>
+
+ <p>The requirements for the types used to instantiate the dereference
+ operators are specified in terms of expressions which must be valid and
+ their return type. The composite operator templates list their component
+ templates, which the instantiating type must support, and possibly other
+ requirements.</p>
+
+ <h3><a name="dereference">Dereference</a> Operators</h3>
+
+ <p>All the dereference operator templates in this table accept an
+ optional template parameter (not shown) to be used for <a href=
+ "#chaining">base class chaining</a>.</p>
+
+ <table cellpadding="5" border="1" align="center">
+ <caption>
+ Dereference Operator Template Classes
+ </caption>
+
+ <tr>
+ <td colspan="3">
+ <table align="center" border="1">
+ <caption>
+ <em>Key</em>
+ </caption>
+
+ <tr>
+ <td><code>T</code>: operand type</td>
+
+ <td><code>P</code>: <code>pointer</code> type</td>
+ </tr>
+
+ <tr>
+ <td><code>D</code>: <code>difference_type</code></td>
+
+ <td><code>R</code>: <code>reference</code> type</td>
+ </tr>
+
+ <tr>
+ <td><code>i</code>: object of type <code>T</code> (an
+ iterator)</td>
+
+ <td><code>n</code>: object of type <code>D</code> (an
+ index)</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>Template</th>
+
+ <th>Supplied Operations</th>
+
+ <th>Requirements</th>
+ </tr>
+
+ <tr>
+ <td><code><a name="dereferenceable">dereferenceable<T,
+ P></a></code></td>
+
+ <td><code>P operator->() const</code></td>
+
+ <td><code>*i</code>. Address of the returned value convertible
+ to <code>P</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code><a name="indexable">indexable<T, D,
+ R></a></code></td>
+
+ <td><code>R operator[](D n) const</code></td>
+
+ <td><code>*(i + n)</code>. Return of type
+ <code>R</code>.</td>
+ </tr>
+ </table>
+
+ <h3><a name="grpd_iter_oprs">Grouped Iterator Operators</a></h3>
+
+ <p>There are five iterator operator class templates, each for a different
+ category of iterator. The following table shows the operator groups for
+ any category that a custom iterator could define. These class templates
+ have an additional optional template parameter <code>B</code>, which is
+ not shown, to support <a href="#chaining">base class chaining</a>.</p>
+
+ <table cellpadding="5" border="1" align="center">
+ <caption>
+ Iterator Operator Class Templates
+ </caption>
+
+ <tr>
+ <td colspan="2">
+ <table align="center" border="1">
+ <caption>
+ <em>Key</em>
+ </caption>
+
+ <tr>
+ <td><code>T</code>: operand type</td>
+
+ <td><code>P</code>: <code>pointer</code> type</td>
+ </tr>
+
+ <tr>
+ <td><code>D</code>: <code>difference_type</code></td>
+
+ <td><code>R</code>: <code>reference</code> type</td>
+ </tr>
+
+ <tr>
+ <td><code>V</code>: <code>value_type</code></td>
+
+ <td>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>Template</th>
+
+ <th>Component Operator Templates</th>
+ </tr>
+
+ <tr>
+ <td><code><a name="input_iteratable">input_iteratable<T,
+ P></a></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#equality_comparable1">equality_comparable<T></a></code></li>
+
+ <li><code><a href=
+ "#incrementable">incrementable<T></a></code></li>
+
+ <li><code><a href="#dereferenceable">dereferenceable<T,
+ P></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "output_iteratable">output_iteratable<T></a></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#incrementable">incrementable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name="forward_iteratable">forward_iteratable<T,
+ P></a></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#input_iteratable">input_iteratable<T,
+ P></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "bidirectional_iteratable">bidirectional_iteratable<T,
+ P></a></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href="#forward_iteratable">forward_iteratable<T,
+ P></a></code></li>
+
+ <li><code><a href=
+ "#decrementable">decrementable<T></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code><a name=
+ "random_access_iteratable">random_access_iteratable<T, P, D,
+ R></a></code></td>
+
+ <td>
+ <ul>
+ <li><code><a href=
+ "#bidirectional_iteratable">bidirectional_iteratable<T,
+ P></a></code></li>
+
+ <li><code><a href=
+ "#totally_ordered1">totally_ordered<T></a></code></li>
+
+ <li><code><a href="#additive2">additive<T,
+ D></a></code></li>
+
+ <li><code><a href="#indexable">indexable<T, D,
+ R></a></code></li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+
+ <h3><a name="iterator">Iterator</a> Helpers</h3>
+
+ <p>There are also five iterator helper class templates, each
+ corresponding to a different iterator category. These classes cannot be
+ used for <a href="#chaining">base class chaining</a>. The following
+ summaries show that these class templates supply both the iterator
+ operators from the <a href="#grpd_iter_oprs">iterator operator class
+ templates</a> and the iterator typedef's required by the C++ standard
+ (<code>iterator_category</code>, <code>value_type</code>,
+ <i>etc.</i>).</p>
+
+ <table cellpadding="5" border="1" align="center">
+ <caption>
+ Iterator Helper Class Templates
+ </caption>
+
+ <tr>
+ <td colspan="2">
+ <table align="center" border="1">
+ <caption>
+ <em>Key</em>
+ </caption>
+
+ <tr>
+ <td><code>T</code>: operand type</td>
+
+ <td><code>P</code>: <code>pointer</code> type</td>
+ </tr>
+
+ <tr>
+ <td><code>D</code>: <code>difference_type</code></td>
+
+ <td><code>R</code>: <code>reference</code> type</td>
+ </tr>
+
+ <tr>
+ <td><code>V</code>: <code>value_type</code></td>
+
+ <td><code>x1, x2</code>: objects of type <code>T</code></td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>Template</th>
+
+ <th>Operations & Requirements</th>
+ </tr>
+
+ <tr valign="baseline">
+ <td><code><a name="input_iterator_helper">input_iterator_helper<T,
+ V, D, P, R></a></code></td>
+
+ <td>
+ Supports the operations and has the requirements of
+
+ <ul>
+ <li><code><a href="#input_iteratable">input_iteratable<T,
+ P></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr valign="baseline">
+ <td><code><a name=
+ "output_iterator_helper">output_iterator_helper<T></a></code></td>
+
+ <td>
+ Supports the operations and has the requirements of
+
+ <ul>
+ <li><code><a href=
+ "#output_iteratable">output_iteratable<T></a></code></li>
+ </ul>
+ See also [<a href="#1">1</a>], [<a href="#2">2</a>].
+ </td>
+ </tr>
+
+ <tr valign="baseline">
+ <td><code><a name=
+ "forward_iterator_helper">forward_iterator_helper<T, V, D, P,
+ R></a></code></td>
+
+ <td>
+ Supports the operations and has the requirements of
+
+ <ul>
+ <li><code><a href="#forward_iteratable">forward_iteratable<T,
+ P></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr valign="baseline">
+ <td><code><a name=
+ "bidirectional_iterator_helper">bidirectional_iterator_helper<T,
+ V, D, P, R></a></code></td>
+
+ <td>
+ Supports the operations and has the requirements of
+
+ <ul>
+ <li><code><a href=
+ "#bidirectional_iteratable">bidirectional_iteratable<T,
+ P></a></code></li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr valign="baseline">
+ <td><code><a name=
+ "random_access_iterator_helper">random_access_iterator_helper<T,
+ V, D, P, R></a></code></td>
+
+ <td>
+ Supports the operations and has the requirements of
+
+ <ul>
+ <li><code><a href=
+ "#random_access_iteratable">random_access_iteratable<T, P, D,
+ R></a></code></li>
+ </ul>
+ To satisfy <cite><a href=
+ "http://www.sgi.com/tech/stl/RandomAccessIterator.html">RandomAccessIterator</a></cite>,
+ <code>x1 - x2</code> with return convertible to <code>D</code> is
+ also required.
+ </td>
+ </tr>
+ </table>
+
+ <h4><a name="iterator_helpers_notes">Iterator Helper Notes</a></h4>
+
+ <p><a name="1">[1]</a> Unlike other iterator helpers templates,
+ <code>output_iterator_helper</code> takes only one template parameter -
+ the type of its target class. Although to some it might seem like an
+ unnecessary restriction, the standard requires
+ <code>difference_type</code> and <code>value_type</code> of any output
+ iterator to be <code>void</code> (24.3.1 [lib.iterator.traits]), and
+ <code>output_iterator_helper</code> template respects this requirement.
+ Also, output iterators in the standard have void <code>pointer</code> and
+ <code>reference</code> types, so the <code>output_iterator_helper</code>
+ does the same.</p>
+
+ <p><a name="2">[2]</a> As self-proxying is the easiest and most common
+ way to implement output iterators (see, for example, insert [24.4.2] and
+ stream iterators [24.5] in the standard library),
+ <code>output_iterator_helper</code> supports the idiom by defining
+ <code>operator*</code> and <code>operator++</code> member functions which
+ just return a non-const reference to the iterator itself. Support for
+ self-proxying allows us, in many cases, to reduce the task of writing an
+ output iterator to writing just two member functions - an appropriate
+ constructor and a copy-assignment operator. For example, here is a
+ possible implementation of <code><a href=
+ "../iterator/doc/function_output_iterator.html">boost::function_output_iterator</a></code>
+ adaptor:</p>
+<pre>
+template<class UnaryFunction>
+struct function_output_iterator
+ : boost::output_iterator_helper< function_output_iterator<UnaryFunction> >
+{
+ explicit function_output_iterator(UnaryFunction const& f = UnaryFunction())
+ : func(f) {}
+
+ template<typename T>
+ function_output_iterator& operator=(T const& value)
+ {
+ this->func(value);
+ return *this;
+ }
+
+ private:
+ UnaryFunction func;
+};
+</pre>
+
+ <p>Note that support for self-proxying does not prevent you from using
+ <code>output_iterator_helper</code> to ease any other, different kind of
+ output iterator's implementation. If
+ <code>output_iterator_helper</code>'s target type provides its own
+ definition of <code>operator*</code> or/and <code>operator++</code>, then
+ these operators will get used and the ones supplied by
+ <code>output_iterator_helper</code> will never be instantiated.</p>
+
+ <h3><a name="i_demo">Iterator Demonstration</a> and Test Program</h3>
+
+ <p>The <cite><a href="iterators_test.cpp">iterators_test.cpp</a></cite>
+ 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:
+ explicit test_iter(T* i =0);
+ test_iter(const self& x);
+ self& operator=(const self& x);
+ Reference operator*() const;
+ self& operator++();
+ self& operator--();
+ self& operator+=(Distance n);
+ self& operator-=(Distance n);
+ bool operator==(const self& x) const;
+ bool operator<(const self& x) const;
+ friend Distance operator-(const self& x, const self& y);
+};
+</pre>
+ </blockquote>
+
+ <p>Check the <a href="http://www.boost.org/development/testing.html">compiler status
+ report</a> for the test results with selected platforms.</p>
+ <hr>
+
+ <h2><a name="contributors">Contributors</a></h2>
+
+ <dl>
+ <dt><a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a></dt>
+
+ <dd>Started the library and contributed the arithmetic operators in
+ <cite><a href=
+ "../../boost/operators.hpp">boost/operators.hpp</a></cite>.</dd>
+
+ <dt><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a></dt>
+
+ <dd>Contributed the <a href="#deref">dereference operators and iterator
+ helpers</a> in <cite><a href=
+ "../../boost/operators.hpp">boost/operators.hpp</a></cite>. Also
+ contributed <cite><a href=
+ "iterators_test.cpp">iterators_test.cpp</a></cite>.</dd>
+
+ <dt><a href="http://www.boost.org/people/aleksey_gurtovoy.htm">Aleksey
+ Gurtovoy</a></dt>
+
+ <dd>Contributed the code to support <a href="#chaining">base class
+ chaining</a> while remaining backward-compatible with old versions of
+ the library.</dd>
+
+ <dt><a href="http://www.boost.org/people/beman_dawes.html">Beman Dawes</a></dt>
+
+ <dd>Contributed <cite><a href=
+ "operators_test.cpp">operators_test.cpp</a></cite>.</dd>
+
+ <dt><a href="http://www.boost.org/people/daryle_walker.html">Daryle Walker</a></dt>
+
+ <dd>Contributed classes for the shift operators, equivalence, partial
+ ordering, and arithmetic conversions. Added the grouped operator
+ classes. Added helper classes for input and output iterators.</dd>
+
+ <dt>Helmut Zeisel</dt>
+
+ <dd>Contributed the 'left' operators and added some grouped operator
+ classes.</dd>
+
+ <dt>Daniel Frey</dt>
+
+ <dd>Contributed the NRVO-friendly and symmetric implementation of
+ arithmetic operators.</dd>
+
+ </dl>
+
+ <h2>Note for Users of <a name="old_lib_note">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 <em>forced</em> 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="#example">example</a>
+ above was 12-24 bytes on various compilers for the Win32 platform,
+ instead of the expected 8 bytes.</p>
+
+ <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] paragraph 5 of the standard).
+ But the language definition also doesn't <em>require</em> 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: 7 Aug 2008</p>
+
+ <p>Copyright © Beman Dawes, David Abrahams, 1999-2001.</p>
+ <p>Copyright © Daniel Frey, 2002-2009.</p>
+ <p>Use, modification, and distribution is subject to the Boost Software
+ License, Version 1.0. (See accompanying file
+ <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
+ <a href="http://www.boost.org/LICENSE_1_0.txt">
+ www.boost.org/LICENSE_1_0.txt</a>)</p>
+ </body>
+</html>
+