Blame - operators.htm - RealtimeRoboticsGroup/test

blob: 993436cbbf91cb045b1b554b951ba344323e9759 [file] [log] [blame]

Brian Silverman	60e3e2a	2018-08-04 23:57:12 -0700	[diff] [blame^]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
				2
				3	<html>
				4	<head>
				5	<meta name="generator" content=
				6	"HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
				7	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
				8
				9	<title>Header <boost/operators.hpp> Documentation</title>
				10	</head>
				11
				12	<body text="black" bgcolor="white" link="blue" vlink="purple" alink="red">
				13	<h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align=
				14	"middle" width="277" height="86">Header <cite><<a href=
				15	"../../boost/operators.hpp">boost/operators.hpp</a>></cite></h1>
				16
				17	<p>The header <cite><<a href=
				18	"../../boost/operators.hpp">boost/operators.hpp</a>></cite> supplies
				19	several sets of class templates (in namespace <code>boost</code>). These
				20	templates define operators at namespace scope in terms of a minimal
				21	number of fundamental operators provided by the class.</p>
				22
				23	<h2><a name="contents">Contents</a></h2>
				24
				25	<ul>
				26	<li><a href="#contents">Contents</a></li>
				27
				28	<li>
				29	<a href="#rationale">Rationale</a>
				30
				31	<ul>
				32	<li><a href="#semantics">Summary of Template Semantics</a></li>
				33
				34	<li><a href="#concepts_note">Use of <i>concepts</i></a></li>
				35	</ul>
				36	</li>
				37
				38	<li>
				39	<a href="#usage">Usage</a>
				40
				41	<ul>
				42	<li>
				43	<a href="#two_arg">Two-Argument Template Forms</a>
				44
				45	<ul>
				46	<li><a href="#two_arg_gen">General Considerations</a></li>
				47
				48	<li><a href="#mixed_arithmetics">Mixed arithmetics</a></li>
				49	</ul>
				50	</li>
				51
				52	<li><a href="#chaining">Base Class Chaining and Object
				53	Size</a></li>
				54
				55	<li><a href="#explicit_instantiation">Separate, Explicit
				56	Instantiation</a></li>
				57
				58	<li><a href="#portability">Requirement Portability</a></li>
				59	</ul>
				60	</li>
				61
				62	<li><a href="#example">Example</a></li>
				63
				64	<li>
				65	<a href="#arithmetic">Arithmetic operators</a>
				66
				67	<ul>
				68	<li>
				69	<a href="#smpl_oprs">Simple Arithmetic Operators</a>
				70
				71	<ul>
				72	<li><a href="#ordering">Ordering Note</a></li>
				73
				74	<li><a href="#symmetry">Symmetry Note</a></li>
				75	</ul>
				76	</li>
				77
				78	<li><a href="#grpd_oprs">Grouped Arithmetic Operators</a></li>
				79
				80	<li><a href="#ex_oprs">Example Templates</a></li>
				81
				82	<li><a href="#a_demo">Arithmetic Operators Demonstration and Test
				83	Program</a></li>
				84	</ul>
				85	</li>
				86
				87	<li>
				88	<a href="#deref">Dereference Operators and Iterator Helpers</a>
				89
				90	<ul>
				91	<li><a href="#dereference">Dereference operators</a></li>
				92
				93	<li><a href="#grpd_iter_oprs">Grouped Iterator Operators</a></li>
				94
				95	<li>
				96	<a href="#iterator">Iterator Helpers</a>
				97
				98	<ul>
				99	<li><a href="#iterator_helpers_notes">Iterator Helper
				100	Notes</a></li>
				101	</ul>
				102	</li>
				103
				104	<li><a href="#i_demo">Iterator Demonstration and Test
				105	Program</a></li>
				106	</ul>
				107	</li>
				108
				109	<li><a href="#contributors">Contributors</a></li>
				110
				111	<li><a href="#old_lib_note">Note for Users of Older Versions</a></li>
				112	</ul>
				113
				114	<h2><a name="rationale">Rationale</a></h2>
				115
				116	<p>Overloaded operators for class types typically occur in groups. If you
				117	can write <code>x + y</code>, you probably also want to be able
				118	to write <code>x += y</code>. If you can write <code>x < y,</code> you
				119	also want <code>x > y, x >= y,</code> and <code>x <= y</code>.
				120	Moreover, unless your class has really surprising behavior, some of these
				121	related operators can be defined in terms of others (e.g. <code>x >= y
				122	<=> !(x < y)</code>). Replicating this boilerplate for multiple
				123	classes is both tedious and error-prone. The <cite><a href=
				124	"../../boost/operators.hpp">boost/operators.hpp</a></cite> templates help
				125	by generating operators for you at namespace scope based on other
				126	operators you've defined in your class.</p>
				127
				128	<p>If, for example, you declare a class like this:</p>
				129
				130	<blockquote>
				131	<pre>
				132	class MyInt
				133	: boost::operators<MyInt>
				134	{
				135	bool operator<(const MyInt& x) const;
				136	bool operator==(const MyInt& x) const;
				137	MyInt& operator+=(const MyInt& x);
				138	MyInt& operator-=(const MyInt& x);
				139	MyInt& operator*=(const MyInt& x);
				140	MyInt& operator/=(const MyInt& x);
				141	MyInt& operator%=(const MyInt& x);
				142	MyInt& operator\|=(const MyInt& x);
				143	MyInt& operator&=(const MyInt& x);
				144	MyInt& operator^=(const MyInt& x);
				145	MyInt& operator++();
				146	MyInt& operator--();
				147	};
				148	</pre>
				149	</blockquote>
				150
				151	<p>then the <code><a href="#operators1">operators<></a></code>
				152	template adds more than a dozen additional operators, such as
				153	<code>operator></code>, <code><=</code>, <code>>=</code>, and
				154	(binary) <code>+</code>. <a href="#two_arg">Two-argument forms</a> of the
				155	templates are also provided to allow interaction with other types.</p>
				156
				157	<h3>Summary of Template <a name="semantics">Semantics</a></h3>
				158
				159	<ol>
				160	<li>Each operator template completes the concept(s) it describes by
				161	defining overloaded operators for its target class.</li>
				162
				163	<li>The name of an operator class template indicates the <a href=
				164	"#concepts_note">concept</a> that its target class will model.</li>
				165
				166	<li>Usually, the target class uses an instantation of the operator
				167	class template as a base class. Some operator templates support an <a
				168	href="#explicit_instantiation">alternate method</a>.</li>
				169
				170	<li>The concept can be compound, <i>i.e.</i> it may represent a common
				171	combination of other, simpler concepts.</li>
				172
				173	<li>Most operator templates require their target class to support
				174	operations related to the operators supplied by the template. In
				175	accordance with widely accepted <a href=
				176	"http://www.gotw.ca/gotw/004.htm">coding style recommendations</a>, the
				177	target class is often required to supply the assignment counterpart
				178	operator of the concept's "main operator." For example, the
				179	<code>addable</code> template requires <code>operator+=(T
				180	const&)</code> and in turn supplies <code>operator+(T const&, T
				181	const&)</code>.</li>
				182	</ol>
				183
				184	<h3>Use of <i><a name="concepts_note">concepts</a></i></h3>
				185
				186	<p>The discussed concepts are not necessarily the standard library's
				187	concepts (CopyConstructible, <i>etc.</i>), although some of them could
				188	be; they are what we call <i>concepts with a small 'c'</i>. In
				189	particular, they are different from the former ones in that they <em>do
				190	not</em> describe precise semantics of the operators they require to be
				191	defined, except the requirements that (a) the semantics of the operators
				192	grouped in one concept should be consistent (<i>e.g.</i> effects of
				193	evaluating of <code>a += b</code> and
				194	<code>a = a + b</code> expressions should be the
				195	same), and (b) that the return types of the operators should follow
				196	semantics of return types of corresponding operators for built-in types
				197	(<i>e.g.</i> <code>operator<</code> should return a type convertible
				198	to <code>bool</code>, and <code>T::operator-=</code> should return type
				199	convertible to <code>T</code>). Such "loose" requirements make operators
				200	library applicable to broader set of target classes from different
				201	domains, <i>i.e.</i> eventually more useful.</p>
				202
				203	<h2><a name="usage">Usage</a></h2>
				204
				205	<h3><a name="two_arg">Two-Argument</a> Template Forms</h3>
				206
				207	<h4><a name="two_arg_gen">General Considerations</a></h4>
				208
				209	<p>The arguments to a binary operator commonly have identical types, but
				210	it is not unusual to want to define operators which combine different
				211	types. For <a href="#example">example</a>, one might want to multiply a
				212	mathematical vector by a scalar. The two-argument template forms of the
				213	arithmetic operator templates are supplied for this purpose. When
				214	applying the two-argument form of a template, the desired return type of
				215	the operators typically determines which of the two types in question
				216	should be derived from the operator template. For example, if the result
				217	of <code>T + U</code> is of type <code>T</code>, then
				218	<code>T</code> (not <code>U</code>) should be derived from <code><a href=
				219	"#addable2">addable<T, U></a></code>. The comparison templates
				220	(<code><a href="#less_than_comparable2">less_than_comparable<T,
				221	U></a></code>, <code><a href=
				222	"#equality_comparable2">equality_comparable<T, U></a></code>,
				223	<code><a href="#equivalent2">equivalent<T, U></a></code>, and
				224	<code><a href="#partially_ordered2">partially_ordered<T,
				225	U></a></code>) are exceptions to this guideline, since the return type
				226	of the operators they define is <code>bool</code>.</p>
				227
				228	<p>On compilers which do not support partial specialization, the
				229	two-argument forms must be specified by using the names shown below with
				230	the trailing <code>'2'</code>. The single-argument forms with the
				231	trailing <code>'1'</code> are provided for symmetry and to enable certain
				232	applications of the <a href="#chaining">base class chaining</a>
				233	technique.</p>
				234
				235	<h4><a name="mixed_arithmetics">Mixed Arithmetics</a></h4>
				236
				237	<p>Another application of the two-argument template forms is for mixed
				238	arithmetics between a type <code>T</code> and a type <code>U</code> that
				239	is convertible to <code>T</code>. In this case there are two ways where
				240	the two-argument template forms are helpful: one is to provide the
				241	respective signatures for operator overloading, the second is
				242	performance.</p>
				243
				244	<p>With respect to the operator overloading assume <i>e.g.</i> that
				245	<code>U</code> is <code>int</code>, that <code>T</code> is an
				246	user-defined unlimited integer type, and that <code>double
				247	operator-(double, const T&)</code> exists. If one wants to compute
				248	<code>int - T</code> and does not provide <code>T operator-(int, const
				249	T&)</code>, the compiler will consider <code>double operator-(double,
				250	const T&)</code> to be a better match than <code>T operator-(const
				251	T&, const T&)</code>, which will probably be different from the
				252	user's intention. To define a complete set of operator signatures,
				253	additional 'left' forms of the two-argument template forms are provided
				254	(<code><a href="#subtractable2_left">subtractable2_left<T,
				255	U></a></code>, <code><a href="#dividable2_left">dividable2_left<T,
				256	U></a></code>, <code><a href="#modable2_left">modable2_left<T,
				257	U></a></code>) that define the signatures for non-commutative
				258	operators where <code>U</code> appears on the left hand side
				259	(<code>operator-(const U&, const T&)</code>,
				260	<code>operator/(const U&, const T&)</code>, <code>operator%(const
				261	U&, const T&)</code>).</p>
				262
				263	<p>With respect to the performance observe that when one uses the single
				264	type binary operator for mixed type arithmetics, the type <code>U</code>
				265	argument has to be converted to type <code>T</code>. In practice,
				266	however, there are often more efficient implementations of, say
				267	<code>T::operator-=(const U&)</code> that avoid unnecessary
				268	conversions from <code>U</code> to <code>T</code>. The two-argument
				269	template forms of the arithmetic operator create additional operator
				270	interfaces that use these more efficient implementations. There is,
				271	however, no performance gain in the 'left' forms: they still need a
				272	conversion from <code>U</code> to <code>T</code> and have an
				273	implementation equivalent to the code that would be automatically created
				274	by the compiler if it considered the single type binary operator to be
				275	the best match.</p>
				276
				277	<h3>Base Class <a name="chaining">Chaining</a> and Object Size</h3>
				278
				279	<p>Every operator class template, except the <a href=
				280	"#ex_oprs">arithmetic examples</a> and the <a href="#iterator">iterator
				281	helpers</a>, has an additional, but optional, template type parameter
				282	<code>B</code>. This parameter will be a publicly-derived base class of
				283	the instantiated template. This means it must be a class type. It can be
				284	used to avoid the bloating of object sizes that is commonly associated
				285	with multiple-inheritance from several empty base classes (see the <a
				286	href="#old_lib_note">note for users of older versions</a> for more
				287	details). To provide support for a group of operators, use the
				288	<code>B</code> parameter to chain operator templates into a single-base
				289	class hierarchy, demostrated in the <a href="#example">usage example</a>.
				290	The technique is also used by the composite operator templates to group
				291	operator definitions. If a chain becomes too long for the compiler to
				292	support, try replacing some of the operator templates with a single
				293	grouped operator template that chains the old templates together; the
				294	length limit only applies to the number of templates directly in the
				295	chain, not those hidden in group templates.</p>
				296
				297	<p><strong>Caveat:</strong> to chain to a base class which is
				298	<em>not</em> a Boost operator template when using the <a href=
				299	"#two_arg">single-argument form</a> of a Boost operator template, you
				300	must specify the operator template with the trailing <code>'1'</code> in
				301	its name. Otherwise the library will assume you mean to define a binary
				302	operation combining the class you intend to use as a base class and the
				303	class you're deriving.</p>
				304
				305	<h3>Separate, <a name="explicit_instantiation">Explicit
				306	Instantiation</a></h3>
				307
				308	<p>On some compilers (<i>e.g.</i> Borland, GCC) even single-inheritance
				309	seems to cause an increase in object size in some cases. If you are not
				310	defining a class template, you may get better object-size performance by
				311	avoiding derivation altogether, and instead explicitly instantiating the
				312	operator template as follows:</p>
				313
				314	<blockquote>
				315	<pre>
				316	class myclass // lose the inheritance...
				317	{
				318	//...
				319	};
				320
				321	// explicitly instantiate the operators I need.
				322	template struct less_than_comparable<myclass>;
				323	template struct equality_comparable<myclass>;
				324	template struct incrementable<myclass>;
				325	template struct decrementable<myclass>;
				326	template struct addable<myclass,long>;
				327	template struct subtractable<myclass,long>;
				328	</pre>
				329	</blockquote>
				330
				331	<p>Note that some operator templates cannot use this workaround and must
				332	be a base class of their primary operand type. Those templates define
				333	operators which must be member functions, and the workaround needs the
				334	operators to be independent friend functions. The relevant templates
				335	are:</p>
				336
				337	<ul>
				338	<li><code><a href=
				339	"#dereferenceable">dereferenceable<></a></code></li>
				340
				341	<li><code><a href="#indexable">indexable<></a></code></li>
				342
				343	<li>Any composite operator template that includes at least one of the
				344	above</li>
				345	</ul>
				346
				347	<p>As Daniel Krügler pointed out, this technique violates 14.6.5/2
				348	and is thus non-portable. The reasoning is, that the operators injected
				349	by the instantiation of e.g.
				350	<code>less_than_comparable<myclass></code> can not be found
				351	by ADL according to the rules given by 3.4.2/2, since myclass is
				352	not an associated class of
				353	<code>less_than_comparable<myclass></code>.
				354	Thus only use this technique if all else fails.</p>
				355
				356	<h3>Requirement <a name="portability">Portability</a></h3>
				357
				358	<p>Many compilers (<i>e.g.</i> MSVC 6.3, GCC 2.95.2) will not enforce the
				359	requirements in the operator template tables unless the operations which
				360	depend on them are actually used. This is not standard-conforming
				361	behavior. In particular, although it would be convenient to derive all
				362	your classes which need binary operators from the <code><a href=
				363	"#operators1">operators<></a></code> and <code><a href=
				364	"#operators2">operators2<></a></code> templates, regardless of
				365	whether they implement all the requirements of those templates, this
				366	shortcut is not portable. Even if this currently works with your
				367	compiler, it may not work later.</p>
				368
				369	<h2><a name="example">Example</a></h2>
				370
				371	<p>This example shows how some of the <a href="#arithmetic">arithmetic
				372	operator templates</a> can be used with a geometric point class
				373	(template).</p>
				374	<pre>
				375	template <class T>
				376	class point // note: private inheritance is OK here!
				377	: boost::addable< point<T> // point + point
				378	, boost::subtractable< point<T> // point - point
				379	, boost::dividable2< point<T>, T // point / T
				380	, boost::multipliable2< point<T>, T // point * T, T * point
				381	> > > >
				382	{
				383	public:
				384	point(T, T);
				385	T x() const;
				386	T y() const;
				387
				388	point operator+=(const point&);
				389	// point operator+(point, const point&) automatically
				390	// generated by addable.
				391
				392	point operator-=(const point&);
				393	// point operator-(point, const point&) automatically
				394	// generated by subtractable.
				395
				396	point operator*=(T);
				397	// point operator*(point, const T&) and
				398	// point operator*(const T&, point) auto-generated
				399	// by multipliable.
				400
				401	point operator/=(T);
				402	// point operator/(point, const T&) auto-generated
				403	// by dividable.
				404	private:
				405	T x_;
				406	T y_;
				407	};
				408
				409	// now use the point<> class:
				410
				411	template <class T>
				412	T length(const point<T> p)
				413	{
				414	return sqrt(p.x()p.x() + p.y()p.y());
				415	}
				416
				417	const point<float> right(0, 1);
				418	const point<float> up(1, 0);
				419	const point<float> pi_over_4 = up + right;
				420	const point<float> pi_over_4_normalized = pi_over_4 / length(pi_over_4);
				421	</pre>
				422
				423	<h2><a name="arithmetic">Arithmetic</a> Operators</h2>
				424
				425	<p>The arithmetic operator templates ease the task of creating a custom
				426	numeric type. Given a core set of operators, the templates add related
				427	operators to the numeric class. These operations are like the ones the
				428	standard arithmetic types have, and may include comparisons, adding,
				429	incrementing, logical and bitwise manipulations, <i>etc</i>. Further,
				430	since most numeric types need more than one of these operators, some
				431	templates are provided to combine several of the basic operator templates
				432	in one declaration.</p>
				433
				434	<p>The requirements for the types used to instantiate the simple operator
				435	templates are specified in terms of expressions which must be valid and
				436	the expression's return type. The composite operator templates only list
				437	what other templates they use. The supplied operations and requirements
				438	of the composite operator templates can be inferred from the operations
				439	and requirements of the listed components.</p>
				440
				441	<h3><a name="smpl_oprs">Simple Arithmetic Operators</a></h3>
				442
				443	<p>These templates are "simple" since they provide operators based on a
				444	single operation the base type has to provide. They have an additional
				445	optional template parameter <code>B</code>, which is not shown, for the
				446	<a href="#chaining">base class chaining</a> technique.</p>
				447
				448	<p>The primary operand type <code>T</code> needs to be of class type,
				449	built-in types are not supported.</p>
				450
				451	<table cellpadding="5" border="1" align="center">
				452	<caption>
				453	Simple Arithmetic Operator Template Classes
				454	</caption>
				455
				456	<tr>
				457	<td colspan="3">
				458	<table align="center" border="1">
				459	<caption>
				460	<em>Key</em>
				461	</caption>
				462
				463	<tr>
				464	<td><code>T</code>: primary operand type</td>
				465
				466	<td><code>U</code>: alternate operand type</td>
				467	</tr>
				468
				469	<tr>
				470	<td><code>t</code>, <code>t1</code>: values of type
				471	<code>T</code></td>
				472
				473	<td><code>u</code>: value of type <code>U</code></td>
				474	</tr>
				475	</table>
				476	</td>
				477	</tr>
				478
				479	<tr>
				480	<th>Template</th>
				481
				482	<th>Supplied Operations</th>
				483
				484	<th>Requirements</th>
				485	</tr>
				486
				487	<tr>
				488	<td><code><a name=
				489	"less_than_comparable1">less_than_comparable<T></a></code><br>
				490	<code>less_than_comparable1<T></code></td>
				491
				492	<td><code>bool operator>(const T&, const T&)</code><br>
				493	<code>bool operator<=(const T&, const T&)</code><br>
				494	<code>bool operator>=(const T&, const T&)</code></td>
				495
				496	<td><code>t < t1</code>.<br>
				497	Return convertible to <code>bool</code>. See the <a href=
				498	"#ordering">Ordering Note</a>.</td>
				499	</tr>
				500
				501	<tr>
				502	<td><code><a name="less_than_comparable2">less_than_comparable<T,
				503	U></a></code><br>
				504	<code>less_than_comparable2<T, U></code></td>
				505
				506	<td><code>bool operator<=(const T&, const U&)</code><br>
				507	<code>bool operator>=(const T&, const U&)</code><br>
				508	<code>bool operator>(const U&, const T&)</code><br>
				509	<code>bool operator<(const U&, const T&)</code><br>
				510	<code>bool operator<=(const U&, const T&)</code><br>
				511	<code>bool operator>=(const U&, const T&)</code></td>
				512
				513	<td><code>t < u</code>. <code>t > u</code>.<br>
				514	Returns convertible to <code>bool</code>. See the <a href=
				515	"#ordering">Ordering Note</a>.</td>
				516	</tr>
				517
				518	<tr>
				519	<td><code><a name=
				520	"equality_comparable1">equality_comparable<T></a></code><br>
				521	<code>equality_comparable1<T></code></td>
				522
				523	<td><code>bool operator!=(const T&, const T&)</code></td>
				524
				525	<td><code>t == t1</code>.<br>
				526	Return convertible to <code>bool</code>.</td>
				527	</tr>
				528
				529	<tr>
				530	<td><code><a name="equality_comparable2">equality_comparable<T,
				531	U></a></code><br>
				532	<code>equality_comparable2<T, U></code></td>
				533
				534	<td><code>bool operator==(const U&, const T&)</code><br>
				535	<code>bool operator!=(const U&, const T&)</code><br>
				536	<code>bool operator!=(const T&, const U&)</code></td>
				537
				538	<td><code>t == u</code>.<br>
				539	Return convertible to <code>bool</code>.</td>
				540	</tr>
				541
				542	<tr>
				543	<td><code><a name="addable1">addable<T></a></code><br>
				544	<code>addable1<T></code></td>
				545
				546	<td><code>T operator+(const T&, const T&)</code></td>
				547
				548	<td><code>T temp(t); temp += t1</code>.<br>
				549	Return convertible to <code>T</code>. See the <a href=
				550	"#symmetry">Symmetry Note</a>.</td>
				551	</tr>
				552
				553	<tr>
				554	<td><code><a name="addable2">addable<T, U></a></code><br>
				555	<code>addable2<T, U></code></td>
				556
				557	<td><code>T operator+(const T&, const U&)</code><br>
				558	<code>T operator+(const U&, const T& )</code></td>
				559
				560	<td><code>T temp(t); temp += u</code>.<br>
				561	Return convertible to <code>T</code>. See the <a href=
				562	"#symmetry">Symmetry Note</a>.</td>
				563	</tr>
				564
				565	<tr>
				566	<td><code><a name=
				567	"subtractable1">subtractable<T></a></code><br>
				568	<code>subtractable1<T></code></td>
				569
				570	<td><code>T operator-(const T&, const T&)</code></td>
				571
				572	<td><code>T temp(t); temp -= t1</code>.<br>
				573	Return convertible to <code>T</code>. See the <a href=
				574	"#symmetry">Symmetry Note</a>.</td>
				575	</tr>
				576
				577	<tr>
				578	<td><code><a name="subtractable2">subtractable<T,
				579	U></a></code><br>
				580	<code>subtractable2<T, U></code></td>
				581
				582	<td><code>T operator-(const T&, const U&)</code></td>
				583
				584	<td><code>T temp(t); temp -= u</code>.<br>
				585	Return convertible to <code>T</code>. See the <a href=
				586	"#symmetry">Symmetry Note</a>.</td>
				587	</tr>
				588
				589	<tr>
				590	<td><code><a name="subtractable2_left">subtractable2_left<T,
				591	U></a></code></td>
				592
				593	<td><code>T operator-(const U&, const T&)</code></td>
				594
				595	<td><code>T temp(u); temp -= t</code>.<br>
				596	Return convertible to <code>T</code>.</td>
				597	</tr>
				598
				599	<tr>
				600	<td><code><a name=
				601	"multipliable1">multipliable<T></a></code><br>
				602	<code>multipliable1<T></code></td>
				603
				604	<td><code>T operator*(const T&, const T&)</code></td>
				605
				606	<td><code>T temp(t); temp *= t1</code>.<br>
				607	Return convertible to <code>T</code>. See the <a href=
				608	"#symmetry">Symmetry Note</a>.</td>
				609	</tr>
				610
				611	<tr>
				612	<td><code><a name="multipliable2">multipliable<T,
				613	U></a></code><br>
				614	<code>multipliable2<T, U></code></td>
				615
				616	<td><code>T operator*(const T&, const U&)</code><br>
				617	<code>T operator*(const U&, const T&)</code></td>
				618
				619	<td><code>T temp(t); temp *= u</code>.<br>
				620	Return convertible to <code>T</code>. See the <a href=
				621	"#symmetry">Symmetry Note</a>.</td>
				622	</tr>
				623
				624	<tr>
				625	<td><code><a name="dividable1">dividable<T></a></code><br>
				626	<code>dividable1<T></code></td>
				627
				628	<td><code>T operator/(const T&, const T&)</code></td>
				629
				630	<td><code>T temp(t); temp /= t1</code>.<br>
				631	Return convertible to <code>T</code>. See the <a href=
				632	"#symmetry">Symmetry Note</a>.</td>
				633	</tr>
				634
				635	<tr>
				636	<td><code><a name="dividable2">dividable<T, U></a></code><br>
				637	<code>dividable2<T, U></code></td>
				638
				639	<td><code>T operator/(const T&, const U&)</code></td>
				640
				641	<td><code>T temp(t); temp /= u</code>.<br>
				642	Return convertible to <code>T</code>. See the <a href=
				643	"#symmetry">Symmetry Note</a>.</td>
				644	</tr>
				645
				646	<tr>
				647	<td><code><a name="dividable2_left">dividable2_left<T,
				648	U></a></code></td>
				649
				650	<td><code>T operator/(const U&, const T&)</code></td>
				651
				652	<td><code>T temp(u); temp /= t</code>.<br>
				653	Return convertible to <code>T</code>.</td>
				654	</tr>
				655
				656	<tr>
				657	<td><code><a name="modable1">modable<T></a></code><br>
				658	<code>modable1<T></code></td>
				659
				660	<td><code>T operator%(const T&, const T&)</code></td>
				661
				662	<td><code>T temp(t); temp %= t1</code>.<br>
				663	Return convertible to <code>T</code>. See the <a href=
				664	"#symmetry">Symmetry Note</a>.</td>
				665	</tr>
				666
				667	<tr>
				668	<td><code><a name="modable2">modable<T, U></a></code><br>
				669	<code>modable2<T, U></code></td>
				670
				671	<td><code>T operator%(const T&, const U&)</code></td>
				672
				673	<td><code>T temp(t); temp %= u</code>.<br>
				674	Return convertible to <code>T</code>. See the <a href=
				675	"#symmetry">Symmetry Note</a>.</td>
				676	</tr>
				677
				678	<tr>
				679	<td><code><a name="modable2_left">modable2_left<T,
				680	U></a></code></td>
				681
				682	<td><code>T operator%(const U&, const T&)</code></td>
				683
				684	<td><code>T temp(u); temp %= t</code>.<br>
				685	Return convertible to <code>T</code>.</td>
				686	</tr>
				687
				688	<tr>
				689	<td><code><a name="orable1">orable<T></a></code><br>
				690	<code>orable1<T></code></td>
				691
				692	<td><code>T operator\|(const T&, const T&)</code></td>
				693
				694	<td><code>T temp(t); temp \|= t1</code>.<br>
				695	Return convertible to <code>T</code>. See the <a href=
				696	"#symmetry">Symmetry Note</a>.</td>
				697	</tr>
				698
				699	<tr>
				700	<td><code><a name="orable2">orable<T, U></a></code><br>
				701	<code>orable2<T, U></code></td>
				702
				703	<td><code>T operator\|(const T&, const U&)</code><br>
				704	<code>T operator\|(const U&, const T&)</code></td>
				705
				706	<td><code>T temp(t); temp \|= u</code>.<br>
				707	Return convertible to <code>T</code>. See the <a href=
				708	"#symmetry">Symmetry Note</a>.</td>
				709	</tr>
				710
				711	<tr>
				712	<td><code><a name="andable1">andable<T></a></code><br>
				713	<code>andable1<T></code></td>
				714
				715	<td><code>T operator&(const T&, const T&)</code></td>
				716
				717	<td><code>T temp(t); temp &= t1</code>.<br>
				718	Return convertible to <code>T</code>. See the <a href=
				719	"#symmetry">Symmetry Note</a>.</td>
				720	</tr>
				721
				722	<tr>
				723	<td><code><a name="andable2">andable<T, U></a></code><br>
				724	<code>andable2<T, U></code></td>
				725
				726	<td><code>T operator&(const T&, const U&)</code><br>
				727	<code>T operator&(const U&, const T&)</code></td>
				728
				729	<td><code>T temp(t); temp &= u</code>.<br>
				730	Return convertible to <code>T</code>. See the <a href=
				731	"#symmetry">Symmetry Note</a>.</td>
				732	</tr>
				733
				734	<tr>
				735	<td><code><a name="xorable1">xorable<T></a></code><br>
				736	<code>xorable1<T></code></td>
				737
				738	<td><code>T operator^(const T&, const T&)</code></td>
				739
				740	<td><code>T temp(t); temp ^= t1</code>.<br>
				741	Return convertible to <code>T</code>. See the <a href=
				742	"#symmetry">Symmetry Note</a>.</td>
				743	</tr>
				744
				745	<tr>
				746	<td><code><a name="xorable2">xorable<T, U></a></code><br>
				747	<code>xorable2<T, U></code></td>
				748
				749	<td><code>T operator^(const T&, const U&)</code><br>
				750	<code>T operator^(const U&, const T&)</code></td>
				751
				752	<td><code>T temp(t); temp ^= u</code>.<br>
				753	Return convertible to <code>T</code>. See the <a href=
				754	"#symmetry">Symmetry Note</a>.</td>
				755	</tr>
				756
				757	<tr>
				758	<td><code><a name=
				759	"incrementable">incrementable<T></a></code></td>
				760
				761	<td><code>T operator++(T&, int)</code></td>
				762
				763	<td><code>T temp(t); ++t</code><br>
				764	Return convertible to <code>T</code>.</td>
				765	</tr>
				766
				767	<tr>
				768	<td><code><a name=
				769	"decrementable">decrementable<T></a></code></td>
				770
				771	<td><code>T operator--(T&, int)</code></td>
				772
				773	<td><code>T temp(t); --t;</code><br>
				774	Return convertible to <code>T</code>.</td>
				775	</tr>
				776
				777	<tr>
				778	<td><code><a name=
				779	"left_shiftable1">left_shiftable<T></a></code><br>
				780	<code>left_shiftable1<T></code></td>
				781
				782	<td><code>T operator<<(const T&, const T&)</code></td>
				783
				784	<td><code>T temp(t); temp <<= t1</code>.<br>
				785	Return convertible to <code>T</code>. See the <a href=
				786	"#symmetry">Symmetry Note</a>.</td>
				787	</tr>
				788
				789	<tr>
				790	<td><code><a name="left_shiftable2">left_shiftable<T,
				791	U></a></code><br>
				792	<code>left_shiftable2<T, U></code></td>
				793
				794	<td><code>T operator<<(const T&, const U&)</code></td>
				795
				796	<td><code>T temp(t); temp <<= u</code>.<br>
				797	Return convertible to <code>T</code>. See the <a href=
				798	"#symmetry">Symmetry Note</a>.</td>
				799	</tr>
				800
				801	<tr>
				802	<td><code><a name=
				803	"right_shiftable1">right_shiftable<T></a></code><br>
				804	<code>right_shiftable1<T></code></td>
				805
				806	<td><code>T operator>>(const T&, const T&)</code></td>
				807
				808	<td><code>T temp(t); temp >>= t1</code>.<br>
				809	Return convertible to <code>T</code>. See the <a href=
				810	"#symmetry">Symmetry Note</a>.</td>
				811	</tr>
				812
				813	<tr>
				814	<td><code><a name="right_shiftable2">right_shiftable<T,
				815	U></a></code><br>
				816	<code>right_shiftable2<T, U></code></td>
				817
				818	<td><code>T operator>>(const T&, const U&)</code></td>
				819
				820	<td><code>T temp(t); temp >>= u</code>.<br>
				821	Return convertible to <code>T</code>. See the <a href=
				822	"#symmetry">Symmetry Note</a>.</td>
				823	</tr>
				824
				825	<tr>
				826	<td><code><a name="equivalent1">equivalent<T></a></code><br>
				827	<code>equivalent1<T></code></td>
				828
				829	<td><code>bool operator==(const T&, const T&)</code></td>
				830
				831	<td><code>t < t1</code>.<br>
				832	Return convertible to <code>bool</code>. See the <a href=
				833	"#ordering">Ordering Note</a>.</td>
				834	</tr>
				835
				836	<tr>
				837	<td><code><a name="equivalent2">equivalent<T, U></a></code><br>
				838	<code>equivalent2<T, U></code></td>
				839
				840	<td><code>bool operator==(const T&, const U&)</code></td>
				841
				842	<td><code>t < u</code>. <code>t > u</code>.<br>
				843	Returns convertible to <code>bool</code>. See the <a href=
				844	"#ordering">Ordering Note</a>.</td>
				845	</tr>
				846
				847	<tr>
				848	<td><code><a name=
				849	"partially_ordered1">partially_ordered<T></a></code><br>
				850	<code>partially_ordered1<T></code></td>
				851
				852	<td><code>bool operator>(const T&, const T&)</code><br>
				853	<code>bool operator<=(const T&, const T&)</code><br>
				854	<code>bool operator>=(const T&, const T&)</code></td>
				855
				856	<td><code>t < t1</code>. <code>t == t1</code>.<br>
				857	Returns convertible to <code>bool</code>. See the <a href=
				858	"#ordering">Ordering Note</a>.</td>
				859	</tr>
				860
				861	<tr>
				862	<td><code><a name="partially_ordered2">partially_ordered<T,
				863	U></a></code><br>
				864	<code>partially_ordered2<T, U></code></td>
				865
				866	<td><code>bool operator<=(const T&, const U&)</code><br>
				867	<code>bool operator>=(const T&, const U&)</code><br>
				868	<code>bool operator>(const U&, const T&)</code><br>
				869	<code>bool operator<(const U&, const T&)</code><br>
				870	<code>bool operator<=(const U&, const T&)</code><br>
				871	<code>bool operator>=(const U&, const T&)</code></td>
				872
				873	<td><code>t < u</code>. <code>t > u</code>. <code>t ==
				874	u</code>.<br>
				875	Returns convertible to <code>bool</code>. See the <a href=
				876	"#ordering">Ordering Note</a>.</td>
				877	</tr>
				878	</table>
				879
				880	<h4><a name="ordering">Ordering</a> Note</h4>
				881
				882	<p>The <code><a href=
				883	"#less_than_comparable1">less_than_comparable<T></a></code> and
				884	<code><a href="#partially_ordered1">partially_ordered<T></a></code>
				885	templates provide the same set of operations. However, the workings of
				886	<code><a href=
				887	"#less_than_comparable1">less_than_comparable<T></a></code> assume
				888	that all values of type <code>T</code> can be placed in a total order. If
				889	that is not true (<i>e.g.</i> Not-a-Number values in IEEE floating point
				890	arithmetic), then <code><a href=
				891	"#partially_ordered1">partially_ordered<T></a></code> should be
				892	used. The <code><a href=
				893	"#partially_ordered1">partially_ordered<T></a></code> template can
				894	be used for a totally-ordered type, but it is not as efficient as
				895	<code><a href=
				896	"#less_than_comparable1">less_than_comparable<T></a></code>. This
				897	rule also applies for <code><a href=
				898	"#less_than_comparable2">less_than_comparable<T, U></a></code> and
				899	<code><a href="#partially_ordered2">partially_ordered<T,
				900	U></a></code> with respect to the ordering of all <code>T</code> and
				901	<code>U</code> values, and for both versions of <code><a href=
				902	"#equivalent1">equivalent<></a></code>. The solution for <code><a
				903	href="#equivalent1">equivalent<></a></code> is to write a custom
				904	<code>operator==</code> for the target class.</p>
				905
				906	<h4><a name="symmetry">Symmetry</a> Note</h4>
				907
				908	<p>Before talking about symmetry, we need to talk about optimizations to
				909	understand the reasons for the different implementation styles of
				910	operators. Let's have a look at <code>operator+</code> for a class
				911	<code>T</code> as an example:</p>
				912	<pre>
				913	T operator+( const T& lhs, const T& rhs )
				914	{
				915	return T( lhs ) += rhs;
				916	}
				917	</pre>
				918	This would be a normal implementation of <code>operator+</code>, but it
				919	is not an efficient one. An unnamed local copy of <code>lhs</code> is
				920	created, <code>operator+=</code> is called on it and it is copied to the
				921	function return value (which is another unnamed object of type
				922	<code>T</code>). The standard doesn't generally allow the intermediate
				923	object to be optimized away:
				924
				925	<blockquote>
				926	3.7.2/2: Automatic storage duration<br>
				927	<br>
				928	If a named automatic object has initialization or a destructor with
				929	side effects, it shall not be destroyed before the end of its block,
				930	nor shall it be eliminated as an optimization even if it appears to be
				931	unused, except that a class object or its copy may be eliminated as
				932	specified in 12.8.
				933	</blockquote>
				934	The reference to 12.8 is important for us:
				935
				936	<blockquote>
				937	12.8/15: Copying class objects<br>
				938	...<br>
				939	For a function with a class return type, if the expression in the
				940	return statement is the name of a local object, and the cv-unqualified
				941	type of the local object is the same as the function return type, an
				942	implementation is permitted to omit creating the temporary object to
				943	hold the function return value, even if the class copy constructor or
				944	destructor has side effects.
				945	</blockquote>
				946	This optimization is known as the named return value optimization (NRVO),
				947	which leads us to the following implementation for
				948	<code>operator+</code>:
				949	<pre>
				950	T operator+( const T& lhs, const T& rhs )
				951	{
				952	T nrv( lhs );
				953	nrv += rhs;
				954	return nrv;
				955	}
				956	</pre>
				957	Given this implementation, the compiler is allowed to remove the
				958	intermediate object. Sadly, not all compiler implement the NRVO, some
				959	even implement it in an incorrect way which makes it useless here.
				960	Without the NRVO, the NRVO-friendly code is no worse than the original
				961	code showed above, but there is another possible implementation, which
				962	has some very special properties:
				963	<pre>
				964	T operator+( T lhs, const T& rhs )
				965	{
				966	return lhs += rhs;
				967	}
				968	</pre>
				969	The difference to the first implementation is that <code>lhs</code> is
				970	not taken as a constant reference used to create a copy; instead,
				971	<code>lhs</code> is a by-value parameter, thus it is already the copy
				972	needed. This allows another optimization (12.2/2) for some cases.
				973	Consider <code>a + b + c</code> where the result of
				974	<code>a + b</code> is not copied when used as <code>lhs</code>
				975	when adding <code>c</code>. This is more efficient than the original
				976	code, but not as efficient as a compiler using the NRVO. For most people,
				977	it is still preferable for compilers that don't implement the NRVO, but
				978	the <code>operator+</code> now has a different function signature. Also,
				979	the number of objects created differs for
				980	<code>(a + b ) + c</code> and
				981	<code>a + ( b + c )</code>. Most probably,
				982	this won't be a problem for you, but if your code relies on the function
				983	signature or a strict symmetric behaviour, you should set
				984	<code>BOOST_FORCE_SYMMETRIC_OPERATORS</code> in your user-config. This
				985	will force the NRVO-friendly implementation to be used even for compilers
				986	that don't implement the NRVO. <br>
				987	<br>
				988
				989	<h3><a name="grpd_oprs">Grouped Arithmetic Operators</a></h3>
				990
				991	<p>The following templates provide common groups of related operations.
				992	For example, since a type which is addable is usually also subractable,
				993	the <code><a href="#additive1">additive</a></code> template provides the
				994	combined operators of both. The grouped operator templates have an
				995	additional optional template parameter <code>B</code>, which is not
				996	shown, for the <a href="#chaining">base class chaining</a> technique.</p>
				997
				998	<table cellpadding="5" border="1" align="center">
				999	<caption>
				1000	Grouped Arithmetic Operator Template Classes
				1001	</caption>
				1002
				1003	<tr>
				1004	<td colspan="2">
				1005	<table align="center" border="1">
				1006	<caption>
				1007	<em>Key</em>
				1008	</caption>
				1009
				1010	<tr>
				1011	<td><code>T</code>: primary operand type</td>
				1012
				1013	<td><code>U</code>: alternate operand type</td>
				1014	</tr>
				1015	</table>
				1016	</td>
				1017	</tr>
				1018
				1019	<tr>
				1020	<th>Template</th>
				1021
				1022	<th>Component Operator Templates</th>
				1023	</tr>
				1024
				1025	<tr>
				1026	<td><code><a name=
				1027	"totally_ordered1">totally_ordered<T></a></code><br>
				1028	<code>totally_ordered1<T></code></td>
				1029
				1030	<td>
				1031	<ul>
				1032	<li><code><a href=
				1033	"#less_than_comparable1">less_than_comparable<T></a></code></li>
				1034
				1035	<li><code><a href=
				1036	"#equality_comparable1">equality_comparable<T></a></code></li>
				1037	</ul>
				1038	</td>
				1039	</tr>
				1040
				1041	<tr>
				1042	<td><code><a name="totally_ordered2">totally_ordered<T,
				1043	U></a></code><br>
				1044	<code>totally_ordered2<T, U></code></td>
				1045
				1046	<td>
				1047	<ul>
				1048	<li><code><a href=
				1049	"#less_than_comparable2">less_than_comparable<T,
				1050	U></a></code></li>
				1051
				1052	<li><code><a href=
				1053	"#equality_comparable2">equality_comparable<T,
				1054	U></a></code></li>
				1055	</ul>
				1056	</td>
				1057	</tr>
				1058
				1059	<tr>
				1060	<td><code><a name="additive1">additive<T></a></code><br>
				1061	<code>additive1<T></code></td>
				1062
				1063	<td>
				1064	<ul>
				1065	<li><code><a href="#addable1">addable<T></a></code></li>
				1066
				1067	<li><code><a href=
				1068	"#subtractable1">subtractable<T></a></code></li>
				1069	</ul>
				1070	</td>
				1071	</tr>
				1072
				1073	<tr>
				1074	<td><code><a name="additive2">additive<T, U></a></code><br>
				1075	<code>additive2<T, U></code></td>
				1076
				1077	<td>
				1078	<ul>
				1079	<li><code><a href="#addable2">addable<T, U></a></code></li>
				1080
				1081	<li><code><a href="#subtractable2">subtractable<T,
				1082	U></a></code></li>
				1083	</ul>
				1084	</td>
				1085	</tr>
				1086
				1087	<tr>
				1088	<td><code><a name=
				1089	"multiplicative1">multiplicative<T></a></code><br>
				1090	<code>multiplicative1<T></code></td>
				1091
				1092	<td>
				1093	<ul>
				1094	<li><code><a href=
				1095	"#multipliable1">multipliable<T></a></code></li>
				1096
				1097	<li><code><a href=
				1098	"#dividable1">dividable<T></a></code></li>
				1099	</ul>
				1100	</td>
				1101	</tr>
				1102
				1103	<tr>
				1104	<td><code><a name="multiplicative2">multiplicative<T,
				1105	U></a></code><br>
				1106	<code>multiplicative2<T, U></code></td>
				1107
				1108	<td>
				1109	<ul>
				1110	<li><code><a href="#multipliable2">multipliable<T,
				1111	U></a></code></li>
				1112
				1113	<li><code><a href="#dividable2">dividable<T,
				1114	U></a></code></li>
				1115	</ul>
				1116	</td>
				1117	</tr>
				1118
				1119	<tr>
				1120	<td><code><a name=
				1121	"integer_multiplicative1">integer_multiplicative<T></a></code><br>
				1122
				1123	<code>integer_multiplicative1<T></code></td>
				1124
				1125	<td>
				1126	<ul>
				1127	<li><code><a href=
				1128	"#multiplicative1">multiplicative<T></a></code></li>
				1129
				1130	<li><code><a href="#modable1">modable<T></a></code></li>
				1131	</ul>
				1132	</td>
				1133	</tr>
				1134
				1135	<tr>
				1136	<td><code><a name=
				1137	"integer_multiplicative2">integer_multiplicative<T,
				1138	U></a></code><br>
				1139	<code>integer_multiplicative2<T, U></code></td>
				1140
				1141	<td>
				1142	<ul>
				1143	<li><code><a href="#multiplicative2">multiplicative<T,
				1144	U></a></code></li>
				1145
				1146	<li><code><a href="#modable2">modable<T, U></a></code></li>
				1147	</ul>
				1148	</td>
				1149	</tr>
				1150
				1151	<tr>
				1152	<td><code><a name="arithmetic1">arithmetic<T></a></code><br>
				1153	<code>arithmetic1<T></code></td>
				1154
				1155	<td>
				1156	<ul>
				1157	<li><code><a href="#additive1">additive<T></a></code></li>
				1158
				1159	<li><code><a href=
				1160	"#multiplicative1">multiplicative<T></a></code></li>
				1161	</ul>
				1162	</td>
				1163	</tr>
				1164
				1165	<tr>
				1166	<td><code><a name="arithmetic2">arithmetic<T, U></a></code><br>
				1167	<code>arithmetic2<T, U></code></td>
				1168
				1169	<td>
				1170	<ul>
				1171	<li><code><a href="#additive2">additive<T,
				1172	U></a></code></li>
				1173
				1174	<li><code><a href="#multiplicative2">multiplicative<T,
				1175	U></a></code></li>
				1176	</ul>
				1177	</td>
				1178	</tr>
				1179
				1180	<tr>
				1181	<td><code><a name=
				1182	"integer_arithmetic1">integer_arithmetic<T></a></code><br>
				1183	<code>integer_arithmetic1<T></code></td>
				1184
				1185	<td>
				1186	<ul>
				1187	<li><code><a href="#additive1">additive<T></a></code></li>
				1188
				1189	<li><code><a href=
				1190	"#integer_multiplicative1">integer_multiplicative<T></a></code></li>
				1191	</ul>
				1192	</td>
				1193	</tr>
				1194
				1195	<tr>
				1196	<td><code><a name="integer_arithmetic2">integer_arithmetic<T,
				1197	U></a></code><br>
				1198	<code>integer_arithmetic2<T, U></code></td>
				1199
				1200	<td>
				1201	<ul>
				1202	<li><code><a href="#additive2">additive<T,
				1203	U></a></code></li>
				1204
				1205	<li><code><a href=
				1206	"#integer_multiplicative2">integer_multiplicative<T,
				1207	U></a></code></li>
				1208	</ul>
				1209	</td>
				1210	</tr>
				1211
				1212	<tr>
				1213	<td><code><a name="bitwise1">bitwise<T></a></code><br>
				1214	<code>bitwise1<T></code></td>
				1215
				1216	<td>
				1217	<ul>
				1218	<li><code><a href="#xorable1">xorable<T></a></code></li>
				1219
				1220	<li><code><a href="#andable1">andable<T></a></code></li>
				1221
				1222	<li><code><a href="#orable1">orable<T></a></code></li>
				1223	</ul>
				1224	</td>
				1225	</tr>
				1226
				1227	<tr>
				1228	<td><code><a name="bitwise2">bitwise<T, U></a></code><br>
				1229	<code>bitwise2<T, U></code></td>
				1230
				1231	<td>
				1232	<ul>
				1233	<li><code><a href="#xorable2">xorable<T, U></a></code></li>
				1234
				1235	<li><code><a href="#andable2">andable<T, U></a></code></li>
				1236
				1237	<li><code><a href="#orable2">orable<T, U></a></code></li>
				1238	</ul>
				1239	</td>
				1240	</tr>
				1241
				1242	<tr>
				1243	<td><code><a name=
				1244	"unit_steppable">unit_steppable<T></a></code></td>
				1245
				1246	<td>
				1247	<ul>
				1248	<li><code><a href=
				1249	"#incrementable">incrementable<T></a></code></li>
				1250
				1251	<li><code><a href=
				1252	"#decrementable">decrementable<T></a></code></li>
				1253	</ul>
				1254	</td>
				1255	</tr>
				1256
				1257	<tr>
				1258	<td><code><a name="shiftable1">shiftable<T></a></code><br>
				1259	<code>shiftable1<T></code></td>
				1260
				1261	<td>
				1262	<ul>
				1263	<li><code><a href=
				1264	"#left_shiftable1">left_shiftable<T></a></code></li>
				1265
				1266	<li><code><a href=
				1267	"#right_shiftable1">right_shiftable<T></a></code></li>
				1268	</ul>
				1269	</td>
				1270	</tr>
				1271
				1272	<tr>
				1273	<td><code><a name="shiftable2">shiftable<T, U></a></code><br>
				1274	<code>shiftable2<T, U></code></td>
				1275
				1276	<td>
				1277	<ul>
				1278	<li><code><a href="#left_shiftable2">left_shiftable<T,
				1279	U></a></code></li>
				1280
				1281	<li><code><a href="#right_shiftable2">right_shiftable<T,
				1282	U></a></code></li>
				1283	</ul>
				1284	</td>
				1285	</tr>
				1286
				1287	<tr>
				1288	<td><code><a name=
				1289	"ring_operators1">ring_operators<T></a></code><br>
				1290	<code>ring_operators1<T></code></td>
				1291
				1292	<td>
				1293	<ul>
				1294	<li><code><a href="#additive1">additive<T></a></code></li>
				1295
				1296	<li><code><a href=
				1297	"#multipliable1">multipliable<T></a></code></li>
				1298	</ul>
				1299	</td>
				1300	</tr>
				1301
				1302	<tr>
				1303	<td><code><a name="ring_operators2">ring_operators<T,
				1304	U></a></code><br>
				1305	<code>ring_operators2<T, U></code></td>
				1306
				1307	<td>
				1308	<ul>
				1309	<li><code><a href="#additive2">additive<T,
				1310	U></a></code></li>
				1311
				1312	<li><code><a href="#subtractable2_left">subtractable2_left<T,
				1313	U></a></code></li>
				1314
				1315	<li><code><a href="#multipliable2">multipliable<T,
				1316	U></a></code></li>
				1317	</ul>
				1318	</td>
				1319	</tr>
				1320
				1321	<tr>
				1322	<td><code><a name=
				1323	"ordered_ring_operators1">ordered_ring_operators<T></a></code><br>
				1324
				1325	<code>ordered_ring_operators1<T></code></td>
				1326
				1327	<td>
				1328	<ul>
				1329	<li><code><a href=
				1330	"#ring_operators1">ring_operators<T></a></code></li>
				1331
				1332	<li><code><a href=
				1333	"#totally_ordered1">totally_ordered<T></a></code></li>
				1334	</ul>
				1335	</td>
				1336	</tr>
				1337
				1338	<tr>
				1339	<td><code><a name=
				1340	"ordered_ring_operators2">ordered_ring_operators<T,
				1341	U></a></code><br>
				1342	<code>ordered_ring_operators2<T, U></code></td>
				1343
				1344	<td>
				1345	<ul>
				1346	<li><code><a href="#ring_operators2">ring_operators<T,
				1347	U></a></code></li>
				1348
				1349	<li><code><a href="#totally_ordered2">totally_ordered<T,
				1350	U></a></code></li>
				1351	</ul>
				1352	</td>
				1353	</tr>
				1354
				1355	<tr>
				1356	<td><code><a name=
				1357	"field_operators1">field_operators<T></a></code><br>
				1358	<code>field_operators1<T></code></td>
				1359
				1360	<td>
				1361	<ul>
				1362	<li><code><a href=
				1363	"#ring_operators1">ring_operators<T></a></code></li>
				1364
				1365	<li><code><a href=
				1366	"#dividable1">dividable<T></a></code></li>
				1367	</ul>
				1368	</td>
				1369	</tr>
				1370
				1371	<tr>
				1372	<td><code><a name="field_operators2">field_operators<T,
				1373	U></a></code><br>
				1374	<code>field_operators2<T, U></code></td>
				1375
				1376	<td>
				1377	<ul>
				1378	<li><code><a href="#ring_operators2">ring_operators<T,
				1379	U></a></code></li>
				1380
				1381	<li><code><a href="#dividable2">dividable<T,
				1382	U></a></code></li>
				1383
				1384	<li><code><a href="#dividable2_left">dividable2_left<T,
				1385	U></a></code></li>
				1386	</ul>
				1387	</td>
				1388	</tr>
				1389
				1390	<tr>
				1391	<td><code><a name=
				1392	"ordered_field_operators1">ordered_field_operators<T></a></code><br>
				1393
				1394	<code>ordered_field_operators1<T></code></td>
				1395
				1396	<td>
				1397	<ul>
				1398	<li><code><a href=
				1399	"#field_operators1">field_operators<T></a></code></li>
				1400
				1401	<li><code><a href=
				1402	"#totally_ordered1">totally_ordered<T></a></code></li>
				1403	</ul>
				1404	</td>
				1405	</tr>
				1406
				1407	<tr>
				1408	<td><code><a name=
				1409	"ordered_field_operators2">ordered_field_operators<T,
				1410	U></a></code><br>
				1411	<code>ordered_field_operators2<T, U></code></td>
				1412
				1413	<td>
				1414	<ul>
				1415	<li><code><a href="#field_operators2">field_operators<T,
				1416	U></a></code></li>
				1417
				1418	<li><code><a href="#totally_ordered2">totally_ordered<T,
				1419	U></a></code></li>
				1420	</ul>
				1421	</td>
				1422	</tr>
				1423
				1424	<tr>
				1425	<td><code><a name=
				1426	"euclidean_ring_operators1">euclidean_ring_operators<T></a></code><br>
				1427
				1428	<code>euclidean_ring_operators1<T></code></td>
				1429
				1430	<td>
				1431	<ul>
				1432	<li><code><a href=
				1433	"#ring_operators1">ring_operators<T></a></code></li>
				1434
				1435	<li><code><a href=
				1436	"#dividable1">dividable<T></a></code></li>
				1437
				1438	<li><code><a href="#modable1">modable<T></a></code></li>
				1439	</ul>
				1440	</td>
				1441	</tr>
				1442
				1443	<tr>
				1444	<td><code><a name=
				1445	"euclidean_ring_operators2">euclidean_ring_operators<T,
				1446	U></a></code><br>
				1447	<code>euclidean_ring_operators2<T, U></code></td>
				1448
				1449	<td>
				1450	<ul>
				1451	<li><code><a href="#ring_operators2">ring_operators<T,
				1452	U></a></code></li>
				1453
				1454	<li><code><a href="#dividable2">dividable<T,
				1455	U></a></code></li>
				1456
				1457	<li><code><a href="#dividable2_left">dividable2_left<T,
				1458	U></a></code></li>
				1459
				1460	<li><code><a href="#modable2">modable<T, U></a></code></li>
				1461
				1462	<li><code><a href="#modable2_left">modable2_left<T,
				1463	U></a></code></li>
				1464	</ul>
				1465	</td>
				1466	</tr>
				1467
				1468	<tr>
				1469	<td><code><a name=
				1470	"ordered_euclidean_ring_operators1">ordered_euclidean_ring_operators<T></a></code><br>
				1471
				1472	<code>ordered_euclidean_ring_operators1<T></code></td>
				1473
				1474	<td>
				1475	<ul>
				1476	<li><code><a href=
				1477	"#euclidean_ring_operators1">euclidean_ring_operators<T></a></code></li>
				1478
				1479	<li><code><a href=
				1480	"#totally_ordered1">totally_ordered<T></a></code></li>
				1481	</ul>
				1482	</td>
				1483	</tr>
				1484
				1485	<tr>
				1486	<td><code><a name=
				1487	"ordered_euclidean_ring_operators2">ordered_euclidean_ring_operators<T,
				1488	U></a></code><br>
				1489	<code>ordered_euclidean_ring_operators2<T, U></code></td>
				1490
				1491	<td>
				1492	<ul>
				1493	<li><code><a href=
				1494	"#euclidean_ring_operators2">euclidean_ring_operators<T,
				1495	U></a></code></li>
				1496
				1497	<li><code><a href="#totally_ordered2">totally_ordered<T,
				1498	U></a></code></li>
				1499	</ul>
				1500	</td>
				1501	</tr>
				1502	</table>
				1503
				1504	<h4>Spelling: euclidean vs. euclidian</h4>
				1505
				1506	<p>Older versions of the Boost.Operators library used
				1507	"<code>euclidian</code>", but it was pointed out that
				1508	"<code>euclidean</code>" is the more common spelling.
				1509	To be compatible with older version, the library now supports
				1510	both spellings.
				1511	</p>
				1512
				1513	<h3><a name="ex_oprs">Example</a> Templates</h3>
				1514
				1515	<p>The arithmetic operator class templates <code><a href=
				1516	"#operators1">operators<></a></code> and <code><a href=
				1517	"#operators2">operators2<></a></code> are examples of
				1518	non-extensible operator grouping classes. These legacy class templates,
				1519	from previous versions of the header, cannot be used for <a href=
				1520	"#chaining">base class chaining</a>.</p>
				1521
				1522	<table cellpadding="5" border="1" align="center">
				1523	<caption>
				1524	Final Arithmetic Operator Template Classes
				1525	</caption>
				1526
				1527	<tr>
				1528	<td colspan="2">
				1529	<table align="center" border="1">
				1530	<caption>
				1531	<em>Key</em>
				1532	</caption>
				1533
				1534	<tr>
				1535	<td><code>T</code>: primary operand type</td>
				1536
				1537	<td><code>U</code>: alternate operand type</td>
				1538	</tr>
				1539	</table>
				1540	</td>
				1541	</tr>
				1542
				1543	<tr>
				1544	<th>Template</th>
				1545
				1546	<th>Component Operator Templates</th>
				1547	</tr>
				1548
				1549	<tr>
				1550	<td><code><a name="operators1">operators<T></a></code></td>
				1551
				1552	<td>
				1553	<ul>
				1554	<li><code><a href=
				1555	"#totally_ordered1">totally_ordered<T></a></code></li>
				1556
				1557	<li><code><a href=
				1558	"#integer_arithmetic1">integer_arithmetic<T></a></code></li>
				1559
				1560	<li><code><a href="#bitwise1">bitwise<T></a></code></li>
				1561
				1562	<li><code><a href=
				1563	"#unit_steppable">unit_steppable<T></a></code></li>
				1564	</ul>
				1565	</td>
				1566	</tr>
				1567
				1568	<tr>
				1569	<td><code><a name="operators2">operators<T, U></a></code><br>
				1570	<code>operators2<T, U></code></td>
				1571
				1572	<td>
				1573	<ul>
				1574	<li><code><a href="#totally_ordered2">totally_ordered<T,
				1575	U></a></code></li>
				1576
				1577	<li><code><a href="#integer_arithmetic2">integer_arithmetic<T,
				1578	U></a></code></li>
				1579
				1580	<li><code><a href="#bitwise2">bitwise<T, U></a></code></li>
				1581	</ul>
				1582	</td>
				1583	</tr>
				1584	</table>
				1585
				1586	<h3><a name="a_demo">Arithmetic Operators Demonstration</a> and Test
				1587	Program</h3>
				1588
				1589	<p>The <cite><a href="operators_test.cpp">operators_test.cpp</a></cite>
				1590	program demonstrates the use of the arithmetic operator templates, and
				1591	can also be used to verify correct operation. Check the compiler status
				1592	report for the test results with selected platforms.</p>
				1593
				1594	<h2><a name="deref">Dereference</a> Operators and Iterator Helpers</h2>
				1595
				1596	<p>The <a href="#iterator">iterator helper</a> templates ease the task of
				1597	creating a custom iterator. Similar to arithmetic types, a complete
				1598	iterator has many operators that are "redundant" and can be implemented
				1599	in terms of the core set of operators.</p>
				1600
				1601	<p>The <a href="#dereference">dereference operators</a> were motivated by
				1602	the <a href="#iterator">iterator helpers</a>, but are often useful in
				1603	non-iterator contexts as well. Many of the redundant iterator operators
				1604	are also arithmetic operators, so the iterator helper classes borrow many
				1605	of the operators defined above. In fact, only two new operators need to
				1606	be defined (the pointer-to-member <code>operator-></code> and the
				1607	subscript <code>operator[]</code>)!</p>
				1608
				1609	<p>The requirements for the types used to instantiate the dereference
				1610	operators are specified in terms of expressions which must be valid and
				1611	their return type. The composite operator templates list their component
				1612	templates, which the instantiating type must support, and possibly other
				1613	requirements.</p>
				1614
				1615	<h3><a name="dereference">Dereference</a> Operators</h3>
				1616
				1617	<p>All the dereference operator templates in this table accept an
				1618	optional template parameter (not shown) to be used for <a href=
				1619	"#chaining">base class chaining</a>.</p>
				1620
				1621	<table cellpadding="5" border="1" align="center">
				1622	<caption>
				1623	Dereference Operator Template Classes
				1624	</caption>
				1625
				1626	<tr>
				1627	<td colspan="3">
				1628	<table align="center" border="1">
				1629	<caption>
				1630	<em>Key</em>
				1631	</caption>
				1632
				1633	<tr>
				1634	<td><code>T</code>: operand type</td>
				1635
				1636	<td><code>P</code>: <code>pointer</code> type</td>
				1637	</tr>
				1638
				1639	<tr>
				1640	<td><code>D</code>: <code>difference_type</code></td>
				1641
				1642	<td><code>R</code>: <code>reference</code> type</td>
				1643	</tr>
				1644
				1645	<tr>
				1646	<td><code>i</code>: object of type <code>T</code> (an
				1647	iterator)</td>
				1648
				1649	<td><code>n</code>: object of type <code>D</code> (an
				1650	index)</td>
				1651	</tr>
				1652	</table>
				1653	</td>
				1654	</tr>
				1655
				1656	<tr>
				1657	<th>Template</th>
				1658
				1659	<th>Supplied Operations</th>
				1660
				1661	<th>Requirements</th>
				1662	</tr>
				1663
				1664	<tr>
				1665	<td><code><a name="dereferenceable">dereferenceable<T,
				1666	P></a></code></td>
				1667
				1668	<td><code>P operator->() const</code></td>
				1669
				1670	<td><code>*i</code>. Address of the returned value convertible
				1671	to <code>P</code>.</td>
				1672	</tr>
				1673
				1674	<tr>
				1675	<td><code><a name="indexable">indexable<T, D,
				1676	R></a></code></td>
				1677
				1678	<td><code>R operator[](D n) const</code></td>
				1679
				1680	<td><code>*(i + n)</code>. Return of type
				1681	<code>R</code>.</td>
				1682	</tr>
				1683	</table>
				1684
				1685	<h3><a name="grpd_iter_oprs">Grouped Iterator Operators</a></h3>
				1686
				1687	<p>There are five iterator operator class templates, each for a different
				1688	category of iterator. The following table shows the operator groups for
				1689	any category that a custom iterator could define. These class templates
				1690	have an additional optional template parameter <code>B</code>, which is
				1691	not shown, to support <a href="#chaining">base class chaining</a>.</p>
				1692
				1693	<table cellpadding="5" border="1" align="center">
				1694	<caption>
				1695	Iterator Operator Class Templates
				1696	</caption>
				1697
				1698	<tr>
				1699	<td colspan="2">
				1700	<table align="center" border="1">
				1701	<caption>
				1702	<em>Key</em>
				1703	</caption>
				1704
				1705	<tr>
				1706	<td><code>T</code>: operand type</td>
				1707
				1708	<td><code>P</code>: <code>pointer</code> type</td>
				1709	</tr>
				1710
				1711	<tr>
				1712	<td><code>D</code>: <code>difference_type</code></td>
				1713
				1714	<td><code>R</code>: <code>reference</code> type</td>
				1715	</tr>
				1716
				1717	<tr>
				1718	<td><code>V</code>: <code>value_type</code></td>
				1719
				1720	<td>
				1721	</td>
				1722	</tr>
				1723	</table>
				1724	</td>
				1725	</tr>
				1726
				1727	<tr>
				1728	<th>Template</th>
				1729
				1730	<th>Component Operator Templates</th>
				1731	</tr>
				1732
				1733	<tr>
				1734	<td><code><a name="input_iteratable">input_iteratable<T,
				1735	P></a></code></td>
				1736
				1737	<td>
				1738	<ul>
				1739	<li><code><a href=
				1740	"#equality_comparable1">equality_comparable<T></a></code></li>
				1741
				1742	<li><code><a href=
				1743	"#incrementable">incrementable<T></a></code></li>
				1744
				1745	<li><code><a href="#dereferenceable">dereferenceable<T,
				1746	P></a></code></li>
				1747	</ul>
				1748	</td>
				1749	</tr>
				1750
				1751	<tr>
				1752	<td><code><a name=
				1753	"output_iteratable">output_iteratable<T></a></code></td>
				1754
				1755	<td>
				1756	<ul>
				1757	<li><code><a href=
				1758	"#incrementable">incrementable<T></a></code></li>
				1759	</ul>
				1760	</td>
				1761	</tr>
				1762
				1763	<tr>
				1764	<td><code><a name="forward_iteratable">forward_iteratable<T,
				1765	P></a></code></td>
				1766
				1767	<td>
				1768	<ul>
				1769	<li><code><a href="#input_iteratable">input_iteratable<T,
				1770	P></a></code></li>
				1771	</ul>
				1772	</td>
				1773	</tr>
				1774
				1775	<tr>
				1776	<td><code><a name=
				1777	"bidirectional_iteratable">bidirectional_iteratable<T,
				1778	P></a></code></td>
				1779
				1780	<td>
				1781	<ul>
				1782	<li><code><a href="#forward_iteratable">forward_iteratable<T,
				1783	P></a></code></li>
				1784
				1785	<li><code><a href=
				1786	"#decrementable">decrementable<T></a></code></li>
				1787	</ul>
				1788	</td>
				1789	</tr>
				1790
				1791	<tr>
				1792	<td><code><a name=
				1793	"random_access_iteratable">random_access_iteratable<T, P, D,
				1794	R></a></code></td>
				1795
				1796	<td>
				1797	<ul>
				1798	<li><code><a href=
				1799	"#bidirectional_iteratable">bidirectional_iteratable<T,
				1800	P></a></code></li>
				1801
				1802	<li><code><a href=
				1803	"#totally_ordered1">totally_ordered<T></a></code></li>
				1804
				1805	<li><code><a href="#additive2">additive<T,
				1806	D></a></code></li>
				1807
				1808	<li><code><a href="#indexable">indexable<T, D,
				1809	R></a></code></li>
				1810	</ul>
				1811	</td>
				1812	</tr>
				1813	</table>
				1814
				1815	<h3><a name="iterator">Iterator</a> Helpers</h3>
				1816
				1817	<p>There are also five iterator helper class templates, each
				1818	corresponding to a different iterator category. These classes cannot be
				1819	used for <a href="#chaining">base class chaining</a>. The following
				1820	summaries show that these class templates supply both the iterator
				1821	operators from the <a href="#grpd_iter_oprs">iterator operator class
				1822	templates</a> and the iterator typedef's required by the C++ standard
				1823	(<code>iterator_category</code>, <code>value_type</code>,
				1824	<i>etc.</i>).</p>
				1825
				1826	<table cellpadding="5" border="1" align="center">
				1827	<caption>
				1828	Iterator Helper Class Templates
				1829	</caption>
				1830
				1831	<tr>
				1832	<td colspan="2">
				1833	<table align="center" border="1">
				1834	<caption>
				1835	<em>Key</em>
				1836	</caption>
				1837
				1838	<tr>
				1839	<td><code>T</code>: operand type</td>
				1840
				1841	<td><code>P</code>: <code>pointer</code> type</td>
				1842	</tr>
				1843
				1844	<tr>
				1845	<td><code>D</code>: <code>difference_type</code></td>
				1846
				1847	<td><code>R</code>: <code>reference</code> type</td>
				1848	</tr>
				1849
				1850	<tr>
				1851	<td><code>V</code>: <code>value_type</code></td>
				1852
				1853	<td><code>x1, x2</code>: objects of type <code>T</code></td>
				1854	</tr>
				1855	</table>
				1856	</td>
				1857	</tr>
				1858
				1859	<tr>
				1860	<th>Template</th>
				1861
				1862	<th>Operations & Requirements</th>
				1863	</tr>
				1864
				1865	<tr valign="baseline">
				1866	<td><code><a name="input_iterator_helper">input_iterator_helper<T,
				1867	V, D, P, R></a></code></td>
				1868
				1869	<td>
				1870	Supports the operations and has the requirements of
				1871
				1872	<ul>
				1873	<li><code><a href="#input_iteratable">input_iteratable<T,
				1874	P></a></code></li>
				1875	</ul>
				1876	</td>
				1877	</tr>
				1878
				1879	<tr valign="baseline">
				1880	<td><code><a name=
				1881	"output_iterator_helper">output_iterator_helper<T></a></code></td>
				1882
				1883	<td>
				1884	Supports the operations and has the requirements of
				1885
				1886	<ul>
				1887	<li><code><a href=
				1888	"#output_iteratable">output_iteratable<T></a></code></li>
				1889	</ul>
				1890	See also [<a href="#1">1</a>], [<a href="#2">2</a>].
				1891	</td>
				1892	</tr>
				1893
				1894	<tr valign="baseline">
				1895	<td><code><a name=
				1896	"forward_iterator_helper">forward_iterator_helper<T, V, D, P,
				1897	R></a></code></td>
				1898
				1899	<td>
				1900	Supports the operations and has the requirements of
				1901
				1902	<ul>
				1903	<li><code><a href="#forward_iteratable">forward_iteratable<T,
				1904	P></a></code></li>
				1905	</ul>
				1906	</td>
				1907	</tr>
				1908
				1909	<tr valign="baseline">
				1910	<td><code><a name=
				1911	"bidirectional_iterator_helper">bidirectional_iterator_helper<T,
				1912	V, D, P, R></a></code></td>
				1913
				1914	<td>
				1915	Supports the operations and has the requirements of
				1916
				1917	<ul>
				1918	<li><code><a href=
				1919	"#bidirectional_iteratable">bidirectional_iteratable<T,
				1920	P></a></code></li>
				1921	</ul>
				1922	</td>
				1923	</tr>
				1924
				1925	<tr valign="baseline">
				1926	<td><code><a name=
				1927	"random_access_iterator_helper">random_access_iterator_helper<T,
				1928	V, D, P, R></a></code></td>
				1929
				1930	<td>
				1931	Supports the operations and has the requirements of
				1932
				1933	<ul>
				1934	<li><code><a href=
				1935	"#random_access_iteratable">random_access_iteratable<T, P, D,
				1936	R></a></code></li>
				1937	</ul>
				1938	To satisfy <cite><a href=
				1939	"http://www.sgi.com/tech/stl/RandomAccessIterator.html">RandomAccessIterator</a></cite>,
				1940	<code>x1 - x2</code> with return convertible to <code>D</code> is
				1941	also required.
				1942	</td>
				1943	</tr>
				1944	</table>
				1945
				1946	<h4><a name="iterator_helpers_notes">Iterator Helper Notes</a></h4>
				1947
				1948	<p><a name="1">[1]</a> Unlike other iterator helpers templates,
				1949	<code>output_iterator_helper</code> takes only one template parameter -
				1950	the type of its target class. Although to some it might seem like an
				1951	unnecessary restriction, the standard requires
				1952	<code>difference_type</code> and <code>value_type</code> of any output
				1953	iterator to be <code>void</code> (24.3.1 [lib.iterator.traits]), and
				1954	<code>output_iterator_helper</code> template respects this requirement.
				1955	Also, output iterators in the standard have void <code>pointer</code> and
				1956	<code>reference</code> types, so the <code>output_iterator_helper</code>
				1957	does the same.</p>
				1958
				1959	<p><a name="2">[2]</a> As self-proxying is the easiest and most common
				1960	way to implement output iterators (see, for example, insert [24.4.2] and
				1961	stream iterators [24.5] in the standard library),
				1962	<code>output_iterator_helper</code> supports the idiom by defining
				1963	<code>operator*</code> and <code>operator++</code> member functions which
				1964	just return a non-const reference to the iterator itself. Support for
				1965	self-proxying allows us, in many cases, to reduce the task of writing an
				1966	output iterator to writing just two member functions - an appropriate
				1967	constructor and a copy-assignment operator. For example, here is a
				1968	possible implementation of <code><a href=
				1969	"../iterator/doc/function_output_iterator.html">boost::function_output_iterator</a></code>
				1970	adaptor:</p>
				1971	<pre>
				1972	template<class UnaryFunction>
				1973	struct function_output_iterator
				1974	: boost::output_iterator_helper< function_output_iterator<UnaryFunction> >
				1975	{
				1976	explicit function_output_iterator(UnaryFunction const& f = UnaryFunction())
				1977	: func(f) {}
				1978
				1979	template<typename T>
				1980	function_output_iterator& operator=(T const& value)
				1981	{
				1982	this->func(value);
				1983	return *this;
				1984	}
				1985
				1986	private:
				1987	UnaryFunction func;
				1988	};
				1989	</pre>
				1990
				1991	<p>Note that support for self-proxying does not prevent you from using
				1992	<code>output_iterator_helper</code> to ease any other, different kind of
				1993	output iterator's implementation. If
				1994	<code>output_iterator_helper</code>'s target type provides its own
				1995	definition of <code>operator*</code> or/and <code>operator++</code>, then
				1996	these operators will get used and the ones supplied by
				1997	<code>output_iterator_helper</code> will never be instantiated.</p>
				1998
				1999	<h3><a name="i_demo">Iterator Demonstration</a> and Test Program</h3>
				2000
				2001	<p>The <cite><a href="iterators_test.cpp">iterators_test.cpp</a></cite>
				2002	program demonstrates the use of the iterator templates, and can also be
				2003	used to verify correct operation. The following is the custom iterator
				2004	defined in the test program. It demonstrates a correct (though trivial)
				2005	implementation of the core operations that must be defined in order for
				2006	the iterator helpers to "fill in" the rest of the iterator
				2007	operations.</p>
				2008
				2009	<blockquote>
				2010	<pre>
				2011	template <class T, class R, class P>
				2012	struct test_iter
				2013	: public boost::random_access_iterator_helper<
				2014	test_iter<T,R,P>, T, std::ptrdiff_t, P, R>
				2015	{
				2016	typedef test_iter self;
				2017	typedef R Reference;
				2018	typedef std::ptrdiff_t Distance;
				2019
				2020	public:
				2021	explicit test_iter(T* i =0);
				2022	test_iter(const self& x);
				2023	self& operator=(const self& x);
				2024	Reference operator*() const;
				2025	self& operator++();
				2026	self& operator--();
				2027	self& operator+=(Distance n);
				2028	self& operator-=(Distance n);
				2029	bool operator==(const self& x) const;
				2030	bool operator<(const self& x) const;
				2031	friend Distance operator-(const self& x, const self& y);
				2032	};
				2033	</pre>
				2034	</blockquote>
				2035
				2036	<p>Check the <a href="http://www.boost.org/development/testing.html">compiler status
				2037	report</a> for the test results with selected platforms.</p>
				2038	<hr>
				2039
				2040	<h2><a name="contributors">Contributors</a></h2>
				2041
				2042	<dl>
				2043	<dt><a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a></dt>
				2044
				2045	<dd>Started the library and contributed the arithmetic operators in
				2046	<cite><a href=
				2047	"../../boost/operators.hpp">boost/operators.hpp</a></cite>.</dd>
				2048
				2049	<dt><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a></dt>
				2050
				2051	<dd>Contributed the <a href="#deref">dereference operators and iterator
				2052	helpers</a> in <cite><a href=
				2053	"../../boost/operators.hpp">boost/operators.hpp</a></cite>. Also
				2054	contributed <cite><a href=
				2055	"iterators_test.cpp">iterators_test.cpp</a></cite>.</dd>
				2056
				2057	<dt><a href="http://www.boost.org/people/aleksey_gurtovoy.htm">Aleksey
				2058	Gurtovoy</a></dt>
				2059
				2060	<dd>Contributed the code to support <a href="#chaining">base class
				2061	chaining</a> while remaining backward-compatible with old versions of
				2062	the library.</dd>
				2063
				2064	<dt><a href="http://www.boost.org/people/beman_dawes.html">Beman Dawes</a></dt>
				2065
				2066	<dd>Contributed <cite><a href=
				2067	"operators_test.cpp">operators_test.cpp</a></cite>.</dd>
				2068
				2069	<dt><a href="http://www.boost.org/people/daryle_walker.html">Daryle Walker</a></dt>
				2070
				2071	<dd>Contributed classes for the shift operators, equivalence, partial
				2072	ordering, and arithmetic conversions. Added the grouped operator
				2073	classes. Added helper classes for input and output iterators.</dd>
				2074
				2075	<dt>Helmut Zeisel</dt>
				2076
				2077	<dd>Contributed the 'left' operators and added some grouped operator
				2078	classes.</dd>
				2079
				2080	<dt>Daniel Frey</dt>
				2081
				2082	<dd>Contributed the NRVO-friendly and symmetric implementation of
				2083	arithmetic operators.</dd>
				2084
				2085	</dl>
				2086
				2087	<h2>Note for Users of <a name="old_lib_note">Older Versions</a></h2>
				2088
				2089	<p>The <a href="#chaining">changes in the library interface and
				2090	recommended usage</a> were motivated by some practical issues described
				2091	below. The new version of the library is still backward-compatible with
				2092	the former one (so you're not <em>forced</em> change any existing code),
				2093	but the old usage is deprecated. Though it was arguably simpler and more
				2094	intuitive than using <a href="#chaining">base class chaining</a>, it has
				2095	been discovered that the old practice of deriving from multiple operator
				2096	templates can cause the resulting classes to be much larger than they
				2097	should be. Most modern C++ compilers significantly bloat the size of
				2098	classes derived from multiple empty base classes, even though the base
				2099	classes themselves have no state. For instance, the size of
				2100	<code>point<int></code> from the <a href="#example">example</a>
				2101	above was 12-24 bytes on various compilers for the Win32 platform,
				2102	instead of the expected 8 bytes.</p>
				2103
				2104	<p>Strictly speaking, it was not the library's fault--the language rules
				2105	allow the compiler to apply the empty base class optimization in that
				2106	situation. In principle an arbitrary number of empty base classes can be
				2107	allocated at the same offset, provided that none of them have a common
				2108	ancestor (see section 10.5 [class.derived] paragraph 5 of the standard).
				2109	But the language definition also doesn't <em>require</em> implementations
				2110	to do the optimization, and few if any of today's compilers implement it
				2111	when multiple inheritance is involved. What's worse, it is very unlikely
				2112	that implementors will adopt it as a future enhancement to existing
				2113	compilers, because it would break binary compatibility between code
				2114	generated by two different versions of the same compiler. As Matt Austern
				2115	said, "One of the few times when you have the freedom to do this sort of
				2116	thing is when you're targeting a new architecture...". On the other hand,
				2117	many common compilers will use the empty base optimization for single
				2118	inheritance hierarchies.</p>
				2119
				2120	<p>Given the importance of the issue for the users of the library (which
				2121	aims to be useful for writing light-weight classes like
				2122	<code>MyInt</code> or <code>point<></code>), and the forces
				2123	described above, we decided to change the library interface so that the
				2124	object size bloat could be eliminated even on compilers that support only
				2125	the simplest form of the empty base class optimization. The current
				2126	library interface is the result of those changes. Though the new usage is
				2127	a bit more complicated than the old one, we think it's worth it to make
				2128	the library more useful in real world. Alexy Gurtovoy contributed the
				2129	code which supports the new usage idiom while allowing the library remain
				2130	backward-compatible.</p>
				2131	<hr>
				2132
				2133	<p>Revised: 7 Aug 2008</p>
				2134
				2135	<p>Copyright © Beman Dawes, David Abrahams, 1999-2001.</p>
				2136	<p>Copyright © Daniel Frey, 2002-2009.</p>
				2137	<p>Use, modification, and distribution is subject to the Boost Software
				2138	License, Version 1.0. (See accompanying file
				2139	<a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
				2140	<a href="http://www.boost.org/LICENSE_1_0.txt">
				2141	www.boost.org/LICENSE_1_0.txt</a>)</p>
				2142	</body>
				2143	</html>
				2144