Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/libs/utility/operators.htm @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago
updated boost from 1_33_1 to 1_34_1
File size: 74.2 KB

Rev	Line
[29]	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	<table cellpadding="5" border="1" align="center">
	449	<caption>
	450	Simple Arithmetic Operator Template Classes
	451	</caption>
	452
	453	<tr>
	454	<td colspan="3">
	455	<table align="center" border="1">
	456	<caption>
	457	<em>Key</em>
	458	</caption>
	459
	460	<tr>
	461	<td><code>T</code>: primary operand type</td>
	462
	463	<td><code>U</code>: alternate operand type</td>
	464	</tr>
	465
	466	<tr>
	467	<td><code>t</code>, <code>t1</code>: values of type
	468	<code>T</code></td>
	469
	470	<td><code>u</code>: value of type <code>U</code></td>
	471	</tr>
	472	</table>
	473	</td>
	474	</tr>
	475
	476	<tr>
	477	<th>Template</th>
	478
	479	<th>Supplied Operations</th>
	480
	481	<th>Requirements</th>
	482	</tr>
	483
	484	<tr>
	485	<td><code><a name=
	486	"less_than_comparable1">less_than_comparable<T></a></code><br>
	487	<code>less_than_comparable1<T></code></td>
	488
	489	<td><code>bool operator>(const T&, const T&)</code><br>
	490	<code>bool operator<=(const T&, const T&)</code><br>
	491	<code>bool operator>=(const T&, const T&)</code></td>
	492
	493	<td><code>t < t1</code>.<br>
	494	Return convertible to <code>bool</code>. See the <a href=
	495	"#ordering">Ordering Note</a>.</td>
	496	</tr>
	497
	498	<tr>
	499	<td><code><a name="less_than_comparable2">less_than_comparable<T,
	500	U></a></code><br>
	501	<code>less_than_comparable2<T, U></code></td>
	502
	503	<td><code>bool operator<=(const T&, const U&)</code><br>
	504	<code>bool operator>=(const T&, const U&)</code><br>
	505	<code>bool operator>(const U&, const T&)</code><br>
	506	<code>bool operator<(const U&, const T&)</code><br>
	507	<code>bool operator<=(const U&, const T&)</code><br>
	508	<code>bool operator>=(const U&, const T&)</code></td>
	509
	510	<td><code>t < u</code>. <code>t > u</code>.<br>
	511	Returns convertible to <code>bool</code>. See the <a href=
	512	"#ordering">Ordering Note</a>.</td>
	513	</tr>
	514
	515	<tr>
	516	<td><code><a name=
	517	"equality_comparable1">equality_comparable<T></a></code><br>
	518	<code>equality_comparable1<T></code></td>
	519
	520	<td><code>bool operator!=(const T&, const T&)</code></td>
	521
	522	<td><code>t == t1</code>.<br>
	523	Return convertible to <code>bool</code>.</td>
	524	</tr>
	525
	526	<tr>
	527	<td><code><a name="equality_comparable2">equality_comparable<T,
	528	U></a></code><br>
	529	<code>equality_comparable2<T, U></code></td>
	530
	531	<td><code>bool operator==(const U&, const T&)</code><br>
	532	<code>bool operator!=(const U&, const T&)</code><br>
	533	<code>bool operator!=(const T&, const U&)</code></td>
	534
	535	<td><code>t == u</code>.<br>
	536	Return convertible to <code>bool</code>.</td>
	537	</tr>
	538
	539	<tr>
	540	<td><code><a name="addable1">addable<T></a></code><br>
	541	<code>addable1<T></code></td>
	542
	543	<td><code>T operator+(const T&, const T&)</code></td>
	544
	545	<td><code>T temp(t); temp += t1</code>.<br>
	546	Return convertible to <code>T</code>. See the <a href=
	547	"#symmetry">Symmetry Note</a>.</td>
	548	</tr>
	549
	550	<tr>
	551	<td><code><a name="addable2">addable<T, U></a></code><br>
	552	<code>addable2<T, U></code></td>
	553
	554	<td><code>T operator+(const T&, const U&)</code><br>
	555	<code>T operator+(const U&, const T& )</code></td>
	556
	557	<td><code>T temp(t); temp += u</code>.<br>
	558	Return convertible to <code>T</code>. See the <a href=
	559	"#symmetry">Symmetry Note</a>.</td>
	560	</tr>
	561
	562	<tr>
	563	<td><code><a name=
	564	"subtractable1">subtractable<T></a></code><br>
	565	<code>subtractable1<T></code></td>
	566
	567	<td><code>T operator-(const T&, const T&)</code></td>
	568
	569	<td><code>T temp(t); temp -= t1</code>.<br>
	570	Return convertible to <code>T</code>. See the <a href=
	571	"#symmetry">Symmetry Note</a>.</td>
	572	</tr>
	573
	574	<tr>
	575	<td><code><a name="subtractable2">subtractable<T,
	576	U></a></code><br>
	577	<code>subtractable2<T, U></code></td>
	578
	579	<td><code>T operator-(const T&, const U&)</code></td>
	580
	581	<td><code>T temp(t); temp -= u</code>.<br>
	582	Return convertible to <code>T</code>. See the <a href=
	583	"#symmetry">Symmetry Note</a>.</td>
	584	</tr>
	585
	586	<tr>
	587	<td><code><a name="subtractable2_left">subtractable2_left<T,
	588	U></a></code></td>
	589
	590	<td><code>T operator-(const U&, const T&)</code></td>
	591
	592	<td><code>T temp(u); temp -= t</code>.<br>
	593	Return convertible to <code>T</code>.</td>
	594	</tr>
	595
	596	<tr>
	597	<td><code><a name=
	598	"multipliable1">multipliable<T></a></code><br>
	599	<code>multipliable1<T></code></td>
	600
	601	<td><code>T operator*(const T&, const T&)</code></td>
	602
	603	<td><code>T temp(t); temp *= t1</code>.<br>
	604	Return convertible to <code>T</code>. See the <a href=
	605	"#symmetry">Symmetry Note</a>.</td>
	606	</tr>
	607
	608	<tr>
	609	<td><code><a name="multipliable2">multipliable<T,
	610	U></a></code><br>
	611	<code>multipliable2<T, U></code></td>
	612
	613	<td><code>T operator*(const T&, const U&)</code><br>
	614	<code>T operator*(const U&, const T&)</code></td>
	615
	616	<td><code>T temp(t); temp *= u</code>.<br>
	617	Return convertible to <code>T</code>. See the <a href=
	618	"#symmetry">Symmetry Note</a>.</td>
	619	</tr>
	620
	621	<tr>
	622	<td><code><a name="dividable1">dividable<T></a></code><br>
	623	<code>dividable1<T></code></td>
	624
	625	<td><code>T operator/(const T&, const T&)</code></td>
	626
	627	<td><code>T temp(t); temp /= t1</code>.<br>
	628	Return convertible to <code>T</code>. See the <a href=
	629	"#symmetry">Symmetry Note</a>.</td>
	630	</tr>
	631
	632	<tr>
	633	<td><code><a name="dividable2">dividable<T, U></a></code><br>
	634	<code>dividable2<T, U></code></td>
	635
	636	<td><code>T operator/(const T&, const U&)</code></td>
	637
	638	<td><code>T temp(t); temp /= u</code>.<br>
	639	Return convertible to <code>T</code>. See the <a href=
	640	"#symmetry">Symmetry Note</a>.</td>
	641	</tr>
	642
	643	<tr>
	644	<td><code><a name="dividable2_left">dividable2_left<T,
	645	U></a></code></td>
	646
	647	<td><code>T operator/(const U&, const T&)</code></td>
	648
	649	<td><code>T temp(u); temp /= t</code>.<br>
	650	Return convertible to <code>T</code>.</td>
	651	</tr>
	652
	653	<tr>
	654	<td><code><a name="modable1">modable<T></a></code><br>
	655	<code>modable1<T></code></td>
	656
	657	<td><code>T operator%(const T&, const T&)</code></td>
	658
	659	<td><code>T temp(t); temp %= t1</code>.<br>
	660	Return convertible to <code>T</code>. See the <a href=
	661	"#symmetry">Symmetry Note</a>.</td>
	662	</tr>
	663
	664	<tr>
	665	<td><code><a name="modable2">modable<T, U></a></code><br>
	666	<code>modable2<T, U></code></td>
	667
	668	<td><code>T operator%(const T&, const U&)</code></td>
	669
	670	<td><code>T temp(t); temp %= u</code>.<br>
	671	Return convertible to <code>T</code>. See the <a href=
	672	"#symmetry">Symmetry Note</a>.</td>
	673	</tr>
	674
	675	<tr>
	676	<td><code><a name="modable2_left">modable2_left<T,
	677	U></a></code></td>
	678
	679	<td><code>T operator%(const U&, const T&)</code></td>
	680
	681	<td><code>T temp(u); temp %= t</code>.<br>
	682	Return convertible to <code>T</code>.</td>
	683	</tr>
	684
	685	<tr>
	686	<td><code><a name="orable1">orable<T></a></code><br>
	687	<code>orable1<T></code></td>
	688
	689	<td><code>T operator\|(const T&, const T&)</code></td>
	690
	691	<td><code>T temp(t); temp \|= t1</code>.<br>
	692	Return convertible to <code>T</code>. See the <a href=
	693	"#symmetry">Symmetry Note</a>.</td>
	694	</tr>
	695
	696	<tr>
	697	<td><code><a name="orable2">orable<T, U></a></code><br>
	698	<code>orable2<T, U></code></td>
	699
	700	<td><code>T operator\|(const T&, const U&)</code><br>
	701	<code>T operator\|(const U&, const T&)</code></td>
	702
	703	<td><code>T temp(t); temp \|= u</code>.<br>
	704	Return convertible to <code>T</code>. See the <a href=
	705	"#symmetry">Symmetry Note</a>.</td>
	706	</tr>
	707
	708	<tr>
	709	<td><code><a name="andable1">andable<T></a></code><br>
	710	<code>andable1<T></code></td>
	711
	712	<td><code>T operator&(const T&, const T&)</code></td>
	713
	714	<td><code>T temp(t); temp &= t1</code>.<br>
	715	Return convertible to <code>T</code>. See the <a href=
	716	"#symmetry">Symmetry Note</a>.</td>
	717	</tr>
	718
	719	<tr>
	720	<td><code><a name="andable2">andable<T, U></a></code><br>
	721	<code>andable2<T, U></code></td>
	722
	723	<td><code>T operator&(const T&, const U&)</code><br>
	724	<code>T operator&(const U&, const T&)</code></td>
	725
	726	<td><code>T temp(t); temp &= u</code>.<br>
	727	Return convertible to <code>T</code>. See the <a href=
	728	"#symmetry">Symmetry Note</a>.</td>
	729	</tr>
	730
	731	<tr>
	732	<td><code><a name="xorable1">xorable<T></a></code><br>
	733	<code>xorable1<T></code></td>
	734
	735	<td><code>T operator^(const T&, const T&)</code></td>
	736
	737	<td><code>T temp(t); temp ^= t1</code>.<br>
	738	Return convertible to <code>T</code>. See the <a href=
	739	"#symmetry">Symmetry Note</a>.</td>
	740	</tr>
	741
	742	<tr>
	743	<td><code><a name="xorable2">xorable<T, U></a></code><br>
	744	<code>xorable2<T, U></code></td>
	745
	746	<td><code>T operator^(const T&, const U&)</code><br>
	747	<code>T operator^(const U&, const T&)</code></td>
	748
	749	<td><code>T temp(t); temp ^= u</code>.<br>
	750	Return convertible to <code>T</code>. See the <a href=
	751	"#symmetry">Symmetry Note</a>.</td>
	752	</tr>
	753
	754	<tr>
	755	<td><code><a name=
	756	"incrementable">incrementable<T></a></code></td>
	757
	758	<td><code>T operator++(T&, int)</code></td>
	759
	760	<td><code>T temp(t); ++t</code><br>
	761	Return convertible to <code>T</code>.</td>
	762	</tr>
	763
	764	<tr>
	765	<td><code><a name=
	766	"decrementable">decrementable<T></a></code></td>
	767
	768	<td><code>T operator--(T&, int)</code></td>
	769
	770	<td><code>T temp(t); --t;</code><br>
	771	Return convertible to <code>T</code>.</td>
	772	</tr>
	773
	774	<tr>
	775	<td><code><a name=
	776	"left_shiftable1">left_shiftable<T></a></code><br>
	777	<code>left_shiftable1<T></code></td>
	778
	779	<td><code>T operator<<(const T&, const T&)</code></td>
	780
	781	<td><code>T temp(t); temp <<= t1</code>.<br>
	782	Return convertible to <code>T</code>. See the <a href=
	783	"#symmetry">Symmetry Note</a>.</td>
	784	</tr>
	785
	786	<tr>
	787	<td><code><a name="left_shiftable2">left_shiftable<T,
	788	U></a></code><br>
	789	<code>left_shiftable2<T, U></code></td>
	790
	791	<td><code>T operator<<(const T&, const U&)</code></td>
	792
	793	<td><code>T temp(t); temp <<= u</code>.<br>
	794	Return convertible to <code>T</code>. See the <a href=
	795	"#symmetry">Symmetry Note</a>.</td>
	796	</tr>
	797
	798	<tr>
	799	<td><code><a name=
	800	"right_shiftable1">right_shiftable<T></a></code><br>
	801	<code>right_shiftable1<T></code></td>
	802
	803	<td><code>T operator>>(const T&, const T&)</code></td>
	804
	805	<td><code>T temp(t); temp >>= t1</code>.<br>
	806	Return convertible to <code>T</code>. See the <a href=
	807	"#symmetry">Symmetry Note</a>.</td>
	808	</tr>
	809
	810	<tr>
	811	<td><code><a name="right_shiftable2">right_shiftable<T,
	812	U></a></code><br>
	813	<code>right_shiftable2<T, U></code></td>
	814
	815	<td><code>T operator>>(const T&, const U&)</code></td>
	816
	817	<td><code>T temp(t); temp >>= u</code>.<br>
	818	Return convertible to <code>T</code>. See the <a href=
	819	"#symmetry">Symmetry Note</a>.</td>
	820	</tr>
	821
	822	<tr>
	823	<td><code><a name="equivalent1">equivalent<T></a></code><br>
	824	<code>equivalent1<T></code></td>
	825
	826	<td><code>bool operator==(const T&, const T&)</code></td>
	827
	828	<td><code>t < t1</code>.<br>
	829	Return convertible to <code>bool</code>. See the <a href=
	830	"#ordering">Ordering Note</a>.</td>
	831	</tr>
	832
	833	<tr>
	834	<td><code><a name="equivalent2">equivalent<T, U></a></code><br>
	835	<code>equivalent2<T, U></code></td>
	836
	837	<td><code>bool operator==(const T&, const U&)</code></td>
	838
	839	<td><code>t < u</code>. <code>t > u</code>.<br>
	840	Returns convertible to <code>bool</code>. See the <a href=
	841	"#ordering">Ordering Note</a>.</td>
	842	</tr>
	843
	844	<tr>
	845	<td><code><a name=
	846	"partially_ordered1">partially_ordered<T></a></code><br>
	847	<code>partially_ordered1<T></code></td>
	848
	849	<td><code>bool operator>(const T&, const T&)</code><br>
	850	<code>bool operator<=(const T&, const T&)</code><br>
	851	<code>bool operator>=(const T&, const T&)</code></td>
	852
	853	<td><code>t < t1</code>. <code>t == t1</code>.<br>
	854	Returns convertible to <code>bool</code>. See the <a href=
	855	"#ordering">Ordering Note</a>.</td>
	856	</tr>
	857
	858	<tr>
	859	<td><code><a name="partially_ordered2">partially_ordered<T,
	860	U></a></code><br>
	861	<code>partially_ordered2<T, U></code></td>
	862
	863	<td><code>bool operator<=(const T&, const U&)</code><br>
	864	<code>bool operator>=(const T&, const U&)</code><br>
	865	<code>bool operator>(const U&, const T&)</code><br>
	866	<code>bool operator<(const U&, const T&)</code><br>
	867	<code>bool operator<=(const U&, const T&)</code><br>
	868	<code>bool operator>=(const U&, const T&)</code></td>
	869
	870	<td><code>t < u</code>. <code>t > u</code>. <code>t ==
	871	u</code>.<br>
	872	Returns convertible to <code>bool</code>. See the <a href=
	873	"#ordering">Ordering Note</a>.</td>
	874	</tr>
	875	</table>
	876
	877	<h4><a name="ordering">Ordering</a> Note</h4>
	878
	879	<p>The <code><a href=
	880	"#less_than_comparable1">less_than_comparable<T></a></code> and
	881	<code><a href="#partially_ordered1">partially_ordered<T></a></code>
	882	templates provide the same set of operations. However, the workings of
	883	<code><a href=
	884	"#less_than_comparable1">less_than_comparable<T></a></code> assume
	885	that all values of type <code>T</code> can be placed in a total order. If
	886	that is not true (<i>e.g.</i> Not-a-Number values in IEEE floating point
	887	arithmetic), then <code><a href=
	888	"#partially_ordered1">partially_ordered<T></a></code> should be
	889	used. The <code><a href=
	890	"#partially_ordered1">partially_ordered<T></a></code> template can
	891	be used for a totally-ordered type, but it is not as efficient as
	892	<code><a href=
	893	"#less_than_comparable1">less_than_comparable<T></a></code>. This
	894	rule also applies for <code><a href=
	895	"#less_than_comparable2">less_than_comparable<T, U></a></code> and
	896	<code><a href="#partially_ordered2">partially_ordered<T,
	897	U></a></code> with respect to the ordering of all <code>T</code> and
	898	<code>U</code> values, and for both versions of <code><a href=
	899	"#equivalent1">equivalent<></a></code>. The solution for <code><a
	900	href="#equivalent1">equivalent<></a></code> is to write a custom
	901	<code>operator==</code> for the target class.</p>
	902
	903	<h4><a name="symmetry">Symmetry</a> Note</h4>
	904
	905	<p>Before talking about symmetry, we need to talk about optimizations to
	906	understand the reasons for the different implementation styles of
	907	operators. Let's have a look at <code>operator+</code> for a class
	908	<code>T</code> as an example:</p>
	909	<pre>
	910	T operator+( const T& lhs, const T& rhs )
	911	{
	912	return T( lhs ) += rhs;
	913	}
	914	</pre>
	915	This would be a normal implementation of <code>operator+</code>, but it
	916	is not an efficient one. An unnamed local copy of <code>lhs</code> is
	917	created, <code>operator+=</code> is called on it and it is copied to the
	918	function return value (which is another unnamed object of type
	919	<code>T</code>). The standard doesn't generally allow the intermediate
	920	object to be optimized away:
	921
	922	<blockquote>
	923	3.7.2/2: Automatic storage duration<br>
	924	<br>
	925	If a named automatic object has initialization or a destructor with
	926	side effects, it shall not be destroyed before the end of its block,
	927	nor shall it be eliminated as an optimization even if it appears to be
	928	unused, except that a class object or its copy may be eliminated as
	929	specified in 12.8.
	930	</blockquote>
	931	The reference to 12.8 is important for us:
	932
	933	<blockquote>
	934	12.8/15: Copying class objects<br>
	935	...<br>
	936	For a function with a class return type, if the expression in the
	937	return statement is the name of a local object, and the cv-unqualified
	938	type of the local object is the same as the function return type, an
	939	implementation is permitted to omit creating the temporary object to
	940	hold the function return value, even if the class copy constructor or
	941	destructor has side effects.
	942	</blockquote>
	943	This optimization is known as the named return value optimization (NRVO),
	944	which leads us to the following implementation for
	945	<code>operator+</code>:
	946	<pre>
	947	T operator+( const T& lhs, const T& rhs )
	948	{
	949	T nrv( lhs );
	950	nrv += rhs;
	951	return nrv;
	952	}
	953	</pre>
	954	Given this implementation, the compiler is allowed to remove the
	955	intermediate object. Sadly, not all compiler implement the NRVO, some
	956	even implement it in an incorrect way which makes it useless here.
	957	Without the NRVO, the NRVO-friendly code is no worse than the original
	958	code showed above, but there is another possible implementation, which
	959	has some very special properties:
	960	<pre>
	961	T operator+( T lhs, const T& rhs )
	962	{
	963	return lhs += rhs;
	964	}
	965	</pre>
	966	The difference to the first implementation is that <code>lhs</code> is
	967	not taken as a constant reference used to create a copy; instead,
	968	<code>lhs</code> is a by-value parameter, thus it is already the copy
	969	needed. This allows another optimization (12.2/2) for some cases.
	970	Consider <code>a + b + c</code> where the result of
	971	<code>a + b</code> is not copied when used as <code>lhs</code>
	972	when adding <code>c</code>. This is more efficient than the original
	973	code, but not as efficient as a compiler using the NRVO. For most people,
	974	it is still preferable for compilers that don't implement the NRVO, but
	975	the <code>operator+</code> now has a different function signature. Also,
	976	the number of objects created differs for
	977	<code>(a + b ) + c</code> and
	978	<code>a + ( b + c )</code>. Most probably,
	979	this won't be a problem for you, but if your code relies on the function
	980	signature or a strict symmetric behaviour, you should set
	981	<code>BOOST_FORCE_SYMMETRIC_OPERATORS</code> in your user-config. This
	982	will force the NRVO-friendly implementation to be used even for compilers
	983	that don't implement the NRVO. <br>
	984	<br>
	985
	986	<h3><a name="grpd_oprs">Grouped Arithmetic Operators</a></h3>
	987
	988	<p>The following templates provide common groups of related operations.
	989	For example, since a type which is addable is usually also subractable,
	990	the <code><a href="#additive1">additive</a></code> template provides the
	991	combined operators of both. The grouped operator templates have an
	992	additional optional template parameter <code>B</code>, which is not
	993	shown, for the <a href="#chaining">base class chaining</a> technique.</p>
	994
	995	<table cellpadding="5" border="1" align="center">
	996	<caption>
	997	Grouped Arithmetic Operator Template Classes
	998	</caption>
	999
	1000	<tr>
	1001	<td colspan="2">
	1002	<table align="center" border="1">
	1003	<caption>
	1004	<em>Key</em>
	1005	</caption>
	1006
	1007	<tr>
	1008	<td><code>T</code>: primary operand type</td>
	1009
	1010	<td><code>U</code>: alternate operand type</td>
	1011	</tr>
	1012	</table>
	1013	</td>
	1014	</tr>
	1015
	1016	<tr>
	1017	<th>Template</th>
	1018
	1019	<th>Component Operator Templates</th>
	1020	</tr>
	1021
	1022	<tr>
	1023	<td><code><a name=
	1024	"totally_ordered1">totally_ordered<T></a></code><br>
	1025	<code>totally_ordered1<T></code></td>
	1026
	1027	<td>
	1028	<ul>
	1029	<li><code><a href=
	1030	"#less_than_comparable1">less_than_comparable<T></a></code></li>
	1031
	1032	<li><code><a href=
	1033	"#equality_comparable1">equality_comparable<T></a></code></li>
	1034	</ul>
	1035	</td>
	1036	</tr>
	1037
	1038	<tr>
	1039	<td><code><a name="totally_ordered2">totally_ordered<T,
	1040	U></a></code><br>
	1041	<code>totally_ordered2<T, U></code></td>
	1042
	1043	<td>
	1044	<ul>
	1045	<li><code><a href=
	1046	"#less_than_comparable2">less_than_comparable<T,
	1047	U></a></code></li>
	1048
	1049	<li><code><a href=
	1050	"#equality_comparable2">equality_comparable<T,
	1051	U></a></code></li>
	1052	</ul>
	1053	</td>
	1054	</tr>
	1055
	1056	<tr>
	1057	<td><code><a name="additive1">additive<T></a></code><br>
	1058	<code>additive1<T></code></td>
	1059
	1060	<td>
	1061	<ul>
	1062	<li><code><a href="#addable1">addable<T></a></code></li>
	1063
	1064	<li><code><a href=
	1065	"#subtractable1">subtractable<T></a></code></li>
	1066	</ul>
	1067	</td>
	1068	</tr>
	1069
	1070	<tr>
	1071	<td><code><a name="additive2">additive<T, U></a></code><br>
	1072	<code>additive2<T, U></code></td>
	1073
	1074	<td>
	1075	<ul>
	1076	<li><code><a href="#addable2">addable<T, U></a></code></li>
	1077
	1078	<li><code><a href="#subtractable2">subtractable<T,
	1079	U></a></code></li>
	1080	</ul>
	1081	</td>
	1082	</tr>
	1083
	1084	<tr>
	1085	<td><code><a name=
	1086	"multiplicative1">multiplicative<T></a></code><br>
	1087	<code>multiplicative1<T></code></td>
	1088
	1089	<td>
	1090	<ul>
	1091	<li><code><a href=
	1092	"#multipliable1">multipliable<T></a></code></li>
	1093
	1094	<li><code><a href=
	1095	"#dividable1">dividable<T></a></code></li>
	1096	</ul>
	1097	</td>
	1098	</tr>
	1099
	1100	<tr>
	1101	<td><code><a name="multiplicative2">multiplicative<T,
	1102	U></a></code><br>
	1103	<code>multiplicative2<T, U></code></td>
	1104
	1105	<td>
	1106	<ul>
	1107	<li><code><a href="#multipliable2">multipliable<T,
	1108	U></a></code></li>
	1109
	1110	<li><code><a href="#dividable2">dividable<T,
	1111	U></a></code></li>
	1112	</ul>
	1113	</td>
	1114	</tr>
	1115
	1116	<tr>
	1117	<td><code><a name=
	1118	"integer_multiplicative1">integer_multiplicative<T></a></code><br>
	1119
	1120	<code>integer_multiplicative1<T></code></td>
	1121
	1122	<td>
	1123	<ul>
	1124	<li><code><a href=
	1125	"#multiplicative1">multiplicative<T></a></code></li>
	1126
	1127	<li><code><a href="#modable1">modable<T></a></code></li>
	1128	</ul>
	1129	</td>
	1130	</tr>
	1131
	1132	<tr>
	1133	<td><code><a name=
	1134	"integer_multiplicative2">integer_multiplicative<T,
	1135	U></a></code><br>
	1136	<code>integer_multiplicative2<T, U></code></td>
	1137
	1138	<td>
	1139	<ul>
	1140	<li><code><a href="#multiplicative2">multiplicative<T,
	1141	U></a></code></li>
	1142
	1143	<li><code><a href="#modable2">modable<T, U></a></code></li>
	1144	</ul>
	1145	</td>
	1146	</tr>
	1147
	1148	<tr>
	1149	<td><code><a name="arithmetic1">arithmetic<T></a></code><br>
	1150	<code>arithmetic1<T></code></td>
	1151
	1152	<td>
	1153	<ul>
	1154	<li><code><a href="#additive1">additive<T></a></code></li>
	1155
	1156	<li><code><a href=
	1157	"#multiplicative1">multiplicative<T></a></code></li>
	1158	</ul>
	1159	</td>
	1160	</tr>
	1161
	1162	<tr>
	1163	<td><code><a name="arithmetic2">arithmetic<T, U></a></code><br>
	1164	<code>arithmetic2<T, U></code></td>
	1165
	1166	<td>
	1167	<ul>
	1168	<li><code><a href="#additive2">additive<T,
	1169	U></a></code></li>
	1170
	1171	<li><code><a href="#multiplicative2">multiplicative<T,
	1172	U></a></code></li>
	1173	</ul>
	1174	</td>
	1175	</tr>
	1176
	1177	<tr>
	1178	<td><code><a name=
	1179	"integer_arithmetic1">integer_arithmetic<T></a></code><br>
	1180	<code>integer_arithmetic1<T></code></td>
	1181
	1182	<td>
	1183	<ul>
	1184	<li><code><a href="#additive1">additive<T></a></code></li>
	1185
	1186	<li><code><a href=
	1187	"#integer_multiplicative1">integer_multiplicative<T></a></code></li>
	1188	</ul>
	1189	</td>
	1190	</tr>
	1191
	1192	<tr>
	1193	<td><code><a name="integer_arithmetic2">integer_arithmetic<T,
	1194	U></a></code><br>
	1195	<code>integer_arithmetic2<T, U></code></td>
	1196
	1197	<td>
	1198	<ul>
	1199	<li><code><a href="#additive2">additive<T,
	1200	U></a></code></li>
	1201
	1202	<li><code><a href=
	1203	"#integer_multiplicative2">integer_multiplicative<T,
	1204	U></a></code></li>
	1205	</ul>
	1206	</td>
	1207	</tr>
	1208
	1209	<tr>
	1210	<td><code><a name="bitwise1">bitwise<T></a></code><br>
	1211	<code>bitwise1<T></code></td>
	1212
	1213	<td>
	1214	<ul>
	1215	<li><code><a href="#xorable1">xorable<T></a></code></li>
	1216
	1217	<li><code><a href="#andable1">andable<T></a></code></li>
	1218
	1219	<li><code><a href="#orable1">orable<T></a></code></li>
	1220	</ul>
	1221	</td>
	1222	</tr>
	1223
	1224	<tr>
	1225	<td><code><a name="bitwise2">bitwise<T, U></a></code><br>
	1226	<code>bitwise2<T, U></code></td>
	1227
	1228	<td>
	1229	<ul>
	1230	<li><code><a href="#xorable2">xorable<T, U></a></code></li>
	1231
	1232	<li><code><a href="#andable2">andable<T, U></a></code></li>
	1233
	1234	<li><code><a href="#orable2">orable<T, U></a></code></li>
	1235	</ul>
	1236	</td>
	1237	</tr>
	1238
	1239	<tr>
	1240	<td><code><a name=
	1241	"unit_steppable">unit_steppable<T></a></code></td>
	1242
	1243	<td>
	1244	<ul>
	1245	<li><code><a href=
	1246	"#incrementable">incrementable<T></a></code></li>
	1247
	1248	<li><code><a href=
	1249	"#decrementable">decrementable<T></a></code></li>
	1250	</ul>
	1251	</td>
	1252	</tr>
	1253
	1254	<tr>
	1255	<td><code><a name="shiftable1">shiftable<T></a></code><br>
	1256	<code>shiftable1<T></code></td>
	1257
	1258	<td>
	1259	<ul>
	1260	<li><code><a href=
	1261	"#left_shiftable1">left_shiftable<T></a></code></li>
	1262
	1263	<li><code><a href=
	1264	"#right_shiftable1">right_shiftable<T></a></code></li>
	1265	</ul>
	1266	</td>
	1267	</tr>
	1268
	1269	<tr>
	1270	<td><code><a name="shiftable2">shiftable<T, U></a></code><br>
	1271	<code>shiftable2<T, U></code></td>
	1272
	1273	<td>
	1274	<ul>
	1275	<li><code><a href="#left_shiftable2">left_shiftable<T,
	1276	U></a></code></li>
	1277
	1278	<li><code><a href="#right_shiftable2">right_shiftable<T,
	1279	U></a></code></li>
	1280	</ul>
	1281	</td>
	1282	</tr>
	1283
	1284	<tr>
	1285	<td><code><a name=
	1286	"ring_operators1">ring_operators<T></a></code><br>
	1287	<code>ring_operators1<T></code></td>
	1288
	1289	<td>
	1290	<ul>
	1291	<li><code><a href="#additive1">additive<T></a></code></li>
	1292
	1293	<li><code><a href=
	1294	"#multipliable1">multipliable<T></a></code></li>
	1295	</ul>
	1296	</td>
	1297	</tr>
	1298
	1299	<tr>
	1300	<td><code><a name="ring_operators2">ring_operators<T,
	1301	U></a></code><br>
	1302	<code>ring_operators2<T, U></code></td>
	1303
	1304	<td>
	1305	<ul>
	1306	<li><code><a href="#additive2">additive<T,
	1307	U></a></code></li>
	1308
	1309	<li><code><a href="#subtractable2_left">subtractable2_left<T,
	1310	U></a></code></li>
	1311
	1312	<li><code><a href="#multipliable2">multipliable<T,
	1313	U></a></code></li>
	1314	</ul>
	1315	</td>
	1316	</tr>
	1317
	1318	<tr>
	1319	<td><code><a name=
	1320	"ordered_ring_operators1">ordered_ring_operators<T></a></code><br>
	1321
	1322	<code>ordered_ring_operators1<T></code></td>
	1323
	1324	<td>
	1325	<ul>
	1326	<li><code><a href=
	1327	"#ring_operators1">ring_operators<T></a></code></li>
	1328
	1329	<li><code><a href=
	1330	"#totally_ordered1">totally_ordered<T></a></code></li>
	1331	</ul>
	1332	</td>
	1333	</tr>
	1334
	1335	<tr>
	1336	<td><code><a name=
	1337	"ordered_ring_operators2">ordered_ring_operators<T,
	1338	U></a></code><br>
	1339	<code>ordered_ring_operators2<T, U></code></td>
	1340
	1341	<td>
	1342	<ul>
	1343	<li><code><a href="#ring_operators2">ring_operators<T,
	1344	U></a></code></li>
	1345
	1346	<li><code><a href="#totally_ordered2">totally_ordered<T,
	1347	U></a></code></li>
	1348	</ul>
	1349	</td>
	1350	</tr>
	1351
	1352	<tr>
	1353	<td><code><a name=
	1354	"field_operators1">field_operators<T></a></code><br>
	1355	<code>field_operators1<T></code></td>
	1356
	1357	<td>
	1358	<ul>
	1359	<li><code><a href=
	1360	"#ring_operators1">ring_operators<T></a></code></li>
	1361
	1362	<li><code><a href=
	1363	"#dividable1">dividable<T></a></code></li>
	1364	</ul>
	1365	</td>
	1366	</tr>
	1367
	1368	<tr>
	1369	<td><code><a name="field_operators2">field_operators<T,
	1370	U></a></code><br>
	1371	<code>field_operators2<T, U></code></td>
	1372
	1373	<td>
	1374	<ul>
	1375	<li><code><a href="#ring_operators2">ring_operators<T,
	1376	U></a></code></li>
	1377
	1378	<li><code><a href="#dividable2">dividable<T,
	1379	U></a></code></li>
	1380
	1381	<li><code><a href="#dividable2_left">dividable2_left<T,
	1382	U></a></code></li>
	1383	</ul>
	1384	</td>
	1385	</tr>
	1386
	1387	<tr>
	1388	<td><code><a name=
	1389	"ordered_field_operators1">ordered_field_operators<T></a></code><br>
	1390
	1391	<code>ordered_field_operators1<T></code></td>
	1392
	1393	<td>
	1394	<ul>
	1395	<li><code><a href=
	1396	"#field_operators1">field_operators<T></a></code></li>
	1397
	1398	<li><code><a href=
	1399	"#totally_ordered1">totally_ordered<T></a></code></li>
	1400	</ul>
	1401	</td>
	1402	</tr>
	1403
	1404	<tr>
	1405	<td><code><a name=
	1406	"ordered_field_operators2">ordered_field_operators<T,
	1407	U></a></code><br>
	1408	<code>ordered_field_operators2<T, U></code></td>
	1409
	1410	<td>
	1411	<ul>
	1412	<li><code><a href="#field_operators2">field_operators<T,
	1413	U></a></code></li>
	1414
	1415	<li><code><a href="#totally_ordered2">totally_ordered<T,
	1416	U></a></code></li>
	1417	</ul>
	1418	</td>
	1419	</tr>
	1420
	1421	<tr>
	1422	<td><code><a name=
	1423	"euclidian_ring_operators1">euclidian_ring_operators<T></a></code><br>
	1424
	1425	<code>euclidian_ring_operators1<T></code></td>
	1426
	1427	<td>
	1428	<ul>
	1429	<li><code><a href=
	1430	"#ring_operators1">ring_operators<T></a></code></li>
	1431
	1432	<li><code><a href=
	1433	"#dividable1">dividable<T></a></code></li>
	1434
	1435	<li><code><a href="#modable1">modable<T></a></code></li>
	1436	</ul>
	1437	</td>
	1438	</tr>
	1439
	1440	<tr>
	1441	<td><code><a name=
	1442	"euclidian_ring_operators2">euclidian_ring_operators<T,
	1443	U></a></code><br>
	1444	<code>euclidian_ring_operators2<T, U></code></td>
	1445
	1446	<td>
	1447	<ul>
	1448	<li><code><a href="#ring_operators2">ring_operators<T,
	1449	U></a></code></li>
	1450
	1451	<li><code><a href="#dividable2">dividable<T,
	1452	U></a></code></li>
	1453
	1454	<li><code><a href="#dividable2_left">dividable2_left<T,
	1455	U></a></code></li>
	1456
	1457	<li><code><a href="#modable2">modable<T, U></a></code></li>
	1458
	1459	<li><code><a href="#modable2_left">modable2_left<T,
	1460	U></a></code></li>
	1461	</ul>
	1462	</td>
	1463	</tr>
	1464
	1465	<tr>
	1466	<td><code><a name=
	1467	"ordered_euclidian_ring_operators1">ordered_euclidian_ring_operators<T></a></code><br>
	1468
	1469	<code>ordered_euclidian_ring_operators1<T></code></td>
	1470
	1471	<td>
	1472	<ul>
	1473	<li><code><a href=
	1474	"#euclidian_ring_operators1">euclidian_ring_operators<T></a></code></li>
	1475
	1476	<li><code><a href=
	1477	"#totally_ordered1">totally_ordered<T></a></code></li>
	1478	</ul>
	1479	</td>
	1480	</tr>
	1481
	1482	<tr>
	1483	<td><code><a name=
	1484	"ordered_euclidian_ring_operators2">ordered_euclidian_ring_operators<T,
	1485	U></a></code><br>
	1486	<code>ordered_euclidian_ring_operators2<T, U></code></td>
	1487
	1488	<td>
	1489	<ul>
	1490	<li><code><a href=
	1491	"#euclidian_ring_operators2">euclidian_ring_operators<T,
	1492	U></a></code></li>
	1493
	1494	<li><code><a href="#totally_ordered2">totally_ordered<T,
	1495	U></a></code></li>
	1496	</ul>
	1497	</td>
	1498	</tr>
	1499	</table>
	1500
	1501	<h3><a name="ex_oprs">Example</a> Templates</h3>
	1502
	1503	<p>The arithmetic operator class templates <code><a href=
	1504	"#operators1">operators<></a></code> and <code><a href=
	1505	"#operators2">operators2<></a></code> are examples of
	1506	non-extensible operator grouping classes. These legacy class templates,
	1507	from previous versions of the header, cannot be used for <a href=
	1508	"#chaining">base class chaining</a>.</p>
	1509
	1510	<table cellpadding="5" border="1" align="center">
	1511	<caption>
	1512	Final Arithmetic Operator Template Classes
	1513	</caption>
	1514
	1515	<tr>
	1516	<td colspan="2">
	1517	<table align="center" border="1">
	1518	<caption>
	1519	<em>Key</em>
	1520	</caption>
	1521
	1522	<tr>
	1523	<td><code>T</code>: primary operand type</td>
	1524
	1525	<td><code>U</code>: alternate operand type</td>
	1526	</tr>
	1527	</table>
	1528	</td>
	1529	</tr>
	1530
	1531	<tr>
	1532	<th>Template</th>
	1533
	1534	<th>Component Operator Templates</th>
	1535	</tr>
	1536
	1537	<tr>
	1538	<td><code><a name="operators1">operators<T></a></code></td>
	1539
	1540	<td>
	1541	<ul>
	1542	<li><code><a href=
	1543	"#totally_ordered1">totally_ordered<T></a></code></li>
	1544
	1545	<li><code><a href=
	1546	"#integer_arithmetic1">integer_arithmetic<T></a></code></li>
	1547
	1548	<li><code><a href="#bitwise1">bitwise<T></a></code></li>
	1549
	1550	<li><code><a href=
	1551	"#unit_steppable">unit_steppable<T></a></code></li>
	1552	</ul>
	1553	</td>
	1554	</tr>
	1555
	1556	<tr>
	1557	<td><code><a name="operators2">operators<T, U></a></code><br>
	1558	<code>operators2<T, U></code></td>
	1559
	1560	<td>
	1561	<ul>
	1562	<li><code><a href="#totally_ordered2">totally_ordered<T,
	1563	U></a></code></li>
	1564
	1565	<li><code><a href="#integer_arithmetic2">integer_arithmetic<T,
	1566	U></a></code></li>
	1567
	1568	<li><code><a href="#bitwise2">bitwise<T, U></a></code></li>
	1569	</ul>
	1570	</td>
	1571	</tr>
	1572	</table>
	1573
	1574	<h3><a name="a_demo">Arithmetic Operators Demonstration</a> and Test
	1575	Program</h3>
	1576
	1577	<p>The <cite><a href="operators_test.cpp">operators_test.cpp</a></cite>
	1578	program demonstrates the use of the arithmetic operator templates, and
	1579	can also be used to verify correct operation. Check the <a href=
	1580	"../../status/compiler_status.html">compiler status report</a> for the
	1581	test results with selected platforms.</p>
	1582
	1583	<h2><a name="deref">Dereference</a> Operators and Iterator Helpers</h2>
	1584
	1585	<p>The <a href="#iterator">iterator helper</a> templates ease the task of
	1586	creating a custom iterator. Similar to arithmetic types, a complete
	1587	iterator has many operators that are "redundant" and can be implemented
	1588	in terms of the core set of operators.</p>
	1589
	1590	<p>The <a href="#dereference">dereference operators</a> were motivated by
	1591	the <a href="#iterator">iterator helpers</a>, but are often useful in
	1592	non-iterator contexts as well. Many of the redundant iterator operators
	1593	are also arithmetic operators, so the iterator helper classes borrow many
	1594	of the operators defined above. In fact, only two new operators need to
	1595	be defined (the pointer-to-member <code>operator-></code> and the
	1596	subscript <code>operator[]</code>)!</p>
	1597
	1598	<p>The requirements for the types used to instantiate the dereference
	1599	operators are specified in terms of expressions which must be valid and
	1600	their return type. The composite operator templates list their component
	1601	templates, which the instantiating type must support, and possibly other
	1602	requirements.</p>
	1603
	1604	<h3><a name="dereference">Dereference</a> Operators</h3>
	1605
	1606	<p>All the dereference operator templates in this table accept an
	1607	optional template parameter (not shown) to be used for <a href=
	1608	"#chaining">base class chaining</a>.</p>
	1609
	1610	<table cellpadding="5" border="1" align="center">
	1611	<caption>
	1612	Dereference Operator Template Classes
	1613	</caption>
	1614
	1615	<tr>
	1616	<td colspan="3">
	1617	<table align="center" border="1">
	1618	<caption>
	1619	<em>Key</em>
	1620	</caption>
	1621
	1622	<tr>
	1623	<td><code>T</code>: operand type</td>
	1624
	1625	<td><code>P</code>: <code>pointer</code> type</td>
	1626	</tr>
	1627
	1628	<tr>
	1629	<td><code>D</code>: <code>difference_type</code></td>
	1630
	1631	<td><code>R</code>: <code>reference</code> type</td>
	1632	</tr>
	1633
	1634	<tr>
	1635	<td><code>i</code>: object of type <code>T</code> (an
	1636	iterator)</td>
	1637
	1638	<td><code>n</code>: object of type <code>D</code> (an
	1639	index)</td>
	1640	</tr>
	1641	</table>
	1642	</td>
	1643	</tr>
	1644
	1645	<tr>
	1646	<th>Template</th>
	1647
	1648	<th>Supplied Operations</th>
	1649
	1650	<th>Requirements</th>
	1651	</tr>
	1652
	1653	<tr>
	1654	<td><code><a name="dereferenceable">dereferenceable<T,
	1655	P></a></code></td>
	1656
	1657	<td><code>P operator->() const</code></td>
	1658
	1659	<td><code>(&*i)</code>. Return convertible to
	1660	<code>P</code>.</td>
	1661	</tr>
	1662
	1663	<tr>
	1664	<td><code><a name="indexable">indexable<T, D,
	1665	R></a></code></td>
	1666
	1667	<td><code>R operator[](D n) const</code></td>
	1668
	1669	<td><code>*(i + n)</code>. Return of type
	1670	<code>R</code>.</td>
	1671	</tr>
	1672	</table>
	1673
	1674	<h3><a name="grpd_iter_oprs">Grouped Iterator Operators</a></h3>
	1675
	1676	<p>There are five iterator operator class templates, each for a different
	1677	category of iterator. The following table shows the operator groups for
	1678	any category that a custom iterator could define. These class templates
	1679	have an additional optional template parameter <code>B</code>, which is
	1680	not shown, to support <a href="#chaining">base class chaining</a>.</p>
	1681
	1682	<table cellpadding="5" border="1" align="center">
	1683	<caption>
	1684	Iterator Operator Class Templates
	1685	</caption>
	1686
	1687	<tr>
	1688	<td colspan="2">
	1689	<table align="center" border="1">
	1690	<caption>
	1691	<em>Key</em>
	1692	</caption>
	1693
	1694	<tr>
	1695	<td><code>T</code>: operand type</td>
	1696
	1697	<td><code>P</code>: <code>pointer</code> type</td>
	1698	</tr>
	1699
	1700	<tr>
	1701	<td><code>D</code>: <code>difference_type</code></td>
	1702
	1703	<td><code>R</code>: <code>reference</code> type</td>
	1704	</tr>
	1705
	1706	<tr>
	1707	<td><code>V</code>: <code>value_type</code></td>
	1708
	1709	<td>
	1710	</td>
	1711	</tr>
	1712	</table>
	1713	</td>
	1714	</tr>
	1715
	1716	<tr>
	1717	<th>Template</th>
	1718
	1719	<th>Component Operator Templates</th>
	1720	</tr>
	1721
	1722	<tr>
	1723	<td><code><a name="input_iteratable">input_iteratable<T,
	1724	P></a></code></td>
	1725
	1726	<td>
	1727	<ul>
	1728	<li><code><a href=
	1729	"#equality_comparable1">equality_comparable<T></a></code></li>
	1730
	1731	<li><code><a href=
	1732	"#incrementable">incrementable<T></a></code></li>
	1733
	1734	<li><code><a href="#dereferenceable">dereferenceable<T,
	1735	P></a></code></li>
	1736	</ul>
	1737	</td>
	1738	</tr>
	1739
	1740	<tr>
	1741	<td><code><a name=
	1742	"output_iteratable">output_iteratable<T></a></code></td>
	1743
	1744	<td>
	1745	<ul>
	1746	<li><code><a href=
	1747	"#incrementable">incrementable<T></a></code></li>
	1748	</ul>
	1749	</td>
	1750	</tr>
	1751
	1752	<tr>
	1753	<td><code><a name="forward_iteratable">forward_iteratable<T,
	1754	P></a></code></td>
	1755
	1756	<td>
	1757	<ul>
	1758	<li><code><a href="#input_iteratable">input_iteratable<T,
	1759	P></a></code></li>
	1760	</ul>
	1761	</td>
	1762	</tr>
	1763
	1764	<tr>
	1765	<td><code><a name=
	1766	"bidirectional_iteratable">bidirectional_iteratable<T,
	1767	P></a></code></td>
	1768
	1769	<td>
	1770	<ul>
	1771	<li><code><a href="#forward_iteratable">forward_iteratable<T,
	1772	P></a></code></li>
	1773
	1774	<li><code><a href=
	1775	"#decrementable">decrementable<T></a></code></li>
	1776	</ul>
	1777	</td>
	1778	</tr>
	1779
	1780	<tr>
	1781	<td><code><a name=
	1782	"random_access_iteratable">random_access_iteratable<T, P, D,
	1783	R></a></code></td>
	1784
	1785	<td>
	1786	<ul>
	1787	<li><code><a href=
	1788	"#bidirectional_iteratable">bidirectional_iteratable<T,
	1789	P></a></code></li>
	1790
	1791	<li><code><a href=
	1792	"#totally_ordered1">totally_ordered<T></a></code></li>
	1793
	1794	<li><code><a href="#additive2">additive<T,
	1795	D></a></code></li>
	1796
	1797	<li><code><a href="#indexable">indexable<T, D,
	1798	R></a></code></li>
	1799	</ul>
	1800	</td>
	1801	</tr>
	1802	</table>
	1803
	1804	<h3><a name="iterator">Iterator</a> Helpers</h3>
	1805
	1806	<p>There are also five iterator helper class templates, each
	1807	corresponding to a different iterator category. These classes cannot be
	1808	used for <a href="#chaining">base class chaining</a>. The following
	1809	summaries show that these class templates supply both the iterator
	1810	operators from the <a href="#grpd_iter_oprs">iterator operator class
	1811	templates</a> and the iterator typedef's required by the C++ standard
	1812	(<code>iterator_category</code>, <code>value_type</code>,
	1813	<i>etc.</i>).</p>
	1814
	1815	<table cellpadding="5" border="1" align="center">
	1816	<caption>
	1817	Iterator Helper Class Templates
	1818	</caption>
	1819
	1820	<tr>
	1821	<td colspan="2">
	1822	<table align="center" border="1">
	1823	<caption>
	1824	<em>Key</em>
	1825	</caption>
	1826
	1827	<tr>
	1828	<td><code>T</code>: operand type</td>
	1829
	1830	<td><code>P</code>: <code>pointer</code> type</td>
	1831	</tr>
	1832
	1833	<tr>
	1834	<td><code>D</code>: <code>difference_type</code></td>
	1835
	1836	<td><code>R</code>: <code>reference</code> type</td>
	1837	</tr>
	1838
	1839	<tr>
	1840	<td><code>V</code>: <code>value_type</code></td>
	1841
	1842	<td><code>x1, x2</code>: objects of type <code>T</code></td>
	1843	</tr>
	1844	</table>
	1845	</td>
	1846	</tr>
	1847
	1848	<tr>
	1849	<th>Template</th>
	1850
	1851	<th>Operations & Requirements</th>
	1852	</tr>
	1853
	1854	<tr valign="baseline">
	1855	<td><code><a name="input_iterator_helper">input_iterator_helper<T,
	1856	V, D, P, R></a></code></td>
	1857
	1858	<td>
	1859	Supports the operations and has the requirements of
	1860
	1861	<ul>
	1862	<li><code><a href="#input_iteratable">input_iteratable<T,
	1863	P></a></code></li>
	1864	</ul>
	1865	</td>
	1866	</tr>
	1867
	1868	<tr valign="baseline">
	1869	<td><code><a name=
	1870	"output_iterator_helper">output_iterator_helper<T></a></code></td>
	1871
	1872	<td>
	1873	Supports the operations and has the requirements of
	1874
	1875	<ul>
	1876	<li><code><a href=
	1877	"#output_iteratable">output_iteratable<T></a></code></li>
	1878	</ul>
	1879	See also [<a href="#1">1</a>], [<a href="#2">2</a>].
	1880	</td>
	1881	</tr>
	1882
	1883	<tr valign="baseline">
	1884	<td><code><a name=
	1885	"forward_iterator_helper">forward_iterator_helper<T, V, D, P,
	1886	R></a></code></td>
	1887
	1888	<td>
	1889	Supports the operations and has the requirements of
	1890
	1891	<ul>
	1892	<li><code><a href="#forward_iteratable">forward_iteratable<T,
	1893	P></a></code></li>
	1894	</ul>
	1895	</td>
	1896	</tr>
	1897
	1898	<tr valign="baseline">
	1899	<td><code><a name=
	1900	"bidirectional_iterator_helper">bidirectional_iterator_helper<T,
	1901	V, D, P, R></a></code></td>
	1902
	1903	<td>
	1904	Supports the operations and has the requirements of
	1905
	1906	<ul>
	1907	<li><code><a href=
	1908	"#bidirectional_iteratable">bidirectional_iteratable<T,
	1909	P></a></code></li>
	1910	</ul>
	1911	</td>
	1912	</tr>
	1913
	1914	<tr valign="baseline">
	1915	<td><code><a name=
	1916	"random_access_iterator_helper">random_access_iterator_helper<T,
	1917	V, D, P, R></a></code></td>
	1918
	1919	<td>
	1920	Supports the operations and has the requirements of
	1921
	1922	<ul>
	1923	<li><code><a href=
	1924	"#random_access_iteratable">random_access_iteratable<T, P, D,
	1925	R></a></code></li>
	1926	</ul>
	1927	To satisfy <cite><a href=
	1928	"http://www.sgi.com/tech/stl/RandomAccessIterator.html">RandomAccessIterator</a></cite>,
	1929	<code>x1 - x2</code> with return convertible to <code>D</code> is
	1930	also required.
	1931	</td>
	1932	</tr>
	1933	</table>
	1934
	1935	<h4><a name="iterator_helpers_notes">Iterator Helper Notes</a></h4>
	1936
	1937	<p><a name="1">[1]</a> Unlike other iterator helpers templates,
	1938	<code>output_iterator_helper</code> takes only one template parameter -
	1939	the type of its target class. Although to some it might seem like an
	1940	unnecessary restriction, the standard requires
	1941	<code>difference_type</code> and <code>value_type</code> of any output
	1942	iterator to be <code>void</code> (24.3.1 [lib.iterator.traits]), and
	1943	<code>output_iterator_helper</code> template respects this requirement.
	1944	Also, output iterators in the standard have void <code>pointer</code> and
	1945	<code>reference</code> types, so the <code>output_iterator_helper</code>
	1946	does the same.</p>
	1947
	1948	<p><a name="2">[2]</a> As self-proxying is the easiest and most common
	1949	way to implement output iterators (see, for example, insert [24.4.2] and
	1950	stream iterators [24.5] in the standard library),
	1951	<code>output_iterator_helper</code> supports the idiom by defining
	1952	<code>operator*</code> and <code>operator++</code> member functions which
	1953	just return a non-const reference to the iterator itself. Support for
	1954	self-proxying allows us, in many cases, to reduce the task of writing an
	1955	output iterator to writing just two member functions - an appropriate
	1956	constructor and a copy-assignment operator. For example, here is a
	1957	possible implementation of <code><a href=
	1958	"../iterator/doc/function_output_iterator.html">boost::function_output_iterator</a></code>
	1959	adaptor:</p>
	1960	<pre>
	1961	template<class UnaryFunction>
	1962	struct function_output_iterator
	1963	: boost::output_iterator_helper< function_output_iterator<UnaryFunction> >
	1964	{
	1965	explicit function_output_iterator(UnaryFunction const& f = UnaryFunction())
	1966	: func(f) {}
	1967
	1968	template<typename T>
	1969	function_output_iterator& operator=(T const& value)
	1970	{
	1971	this->func(value);
	1972	return *this;
	1973	}
	1974
	1975	private:
	1976	UnaryFunction func;
	1977	};
	1978	</pre>
	1979
	1980	<p>Note that support for self-proxying does not prevent you from using
	1981	<code>output_iterator_helper</code> to ease any other, different kind of
	1982	output iterator's implementation. If
	1983	<code>output_iterator_helper</code>'s target type provides its own
	1984	definition of <code>operator*</code> or/and <code>operator++</code>, then
	1985	these operators will get used and the ones supplied by
	1986	<code>output_iterator_helper</code> will never be instantiated.</p>
	1987
	1988	<h3><a name="i_demo">Iterator Demonstration</a> and Test Program</h3>
	1989
	1990	<p>The <cite><a href="iterators_test.cpp">iterators_test.cpp</a></cite>
	1991	program demonstrates the use of the iterator templates, and can also be
	1992	used to verify correct operation. The following is the custom iterator
	1993	defined in the test program. It demonstrates a correct (though trivial)
	1994	implementation of the core operations that must be defined in order for
	1995	the iterator helpers to "fill in" the rest of the iterator
	1996	operations.</p>
	1997
	1998	<blockquote>
	1999	<pre>
	2000	template <class T, class R, class P>
	2001	struct test_iter
	2002	: public boost::random_access_iterator_helper<
	2003	test_iter<T,R,P>, T, std::ptrdiff_t, P, R>
	2004	{
	2005	typedef test_iter self;
	2006	typedef R Reference;
	2007	typedef std::ptrdiff_t Distance;
	2008
	2009	public:
	2010	explicit test_iter(T* i =0);
	2011	test_iter(const self& x);
	2012	self& operator=(const self& x);
	2013	Reference operator*() const;
	2014	self& operator++();
	2015	self& operator--();
	2016	self& operator+=(Distance n);
	2017	self& operator-=(Distance n);
	2018	bool operator==(const self& x) const;
	2019	bool operator<(const self& x) const;
	2020	friend Distance operator-(const self& x, const self& y);
	2021	};
	2022	</pre>
	2023	</blockquote>
	2024
	2025	<p>Check the <a href="../../status/compiler_status.html">compiler status
	2026	report</a> for the test results with selected platforms.</p>
	2027	<hr>
	2028
	2029	<h2><a name="contributors">Contributors</a></h2>
	2030
	2031	<dl>
	2032	<dt><a href="../../people/dave_abrahams.htm">Dave Abrahams</a></dt>
	2033
	2034	<dd>Started the library and contributed the arithmetic operators in
	2035	<cite><a href=
	2036	"../../boost/operators.hpp">boost/operators.hpp</a></cite>.</dd>
	2037
	2038	<dt><a href="../../people/jeremy_siek.htm">Jeremy Siek</a></dt>
	2039
	2040	<dd>Contributed the <a href="#deref">dereference operators and iterator
	2041	helpers</a> in <cite><a href=
	2042	"../../boost/operators.hpp">boost/operators.hpp</a></cite>. Also
	2043	contributed <cite><a href=
	2044	"iterators_test.cpp">iterators_test.cpp</a></cite>.</dd>
	2045
	2046	<dt><a href="../../people/aleksey_gurtovoy.htm">Aleksey
	2047	Gurtovoy</a></dt>
	2048
	2049	<dd>Contributed the code to support <a href="#chaining">base class
	2050	chaining</a> while remaining backward-compatible with old versions of
	2051	the library.</dd>
	2052
	2053	<dt><a href="../../people/beman_dawes.html">Beman Dawes</a></dt>
	2054
	2055	<dd>Contributed <cite><a href=
	2056	"operators_test.cpp">operators_test.cpp</a></cite>.</dd>
	2057
	2058	<dt><a href="../../people/daryle_walker.html">Daryle Walker</a></dt>
	2059
	2060	<dd>Contributed classes for the shift operators, equivalence, partial
	2061	ordering, and arithmetic conversions. Added the grouped operator
	2062	classes. Added helper classes for input and output iterators.</dd>
	2063
	2064	<dt>Helmut Zeisel</dt>
	2065
	2066	<dd>Contributed the 'left' operators and added some grouped operator
	2067	classes.</dd>
	2068
	2069	<dt>Daniel Frey</dt>
	2070
	2071	<dd>Contributed the NRVO-friendly and symmetric implementation of
	2072	arithmetic operators.</dd>
	2073
	2074	</dl>
	2075
	2076	<h2>Note for Users of <a name="old_lib_note">Older Versions</a></h2>
	2077
	2078	<p>The <a href="#chaining">changes in the library interface and
	2079	recommended usage</a> were motivated by some practical issues described
	2080	below. The new version of the library is still backward-compatible with
	2081	the former one (so you're not <em>forced</em> change any existing code),
	2082	but the old usage is deprecated. Though it was arguably simpler and more
	2083	intuitive than using <a href="#chaining">base class chaining</a>, it has
	2084	been discovered that the old practice of deriving from multiple operator
	2085	templates can cause the resulting classes to be much larger than they
	2086	should be. Most modern C++ compilers significantly bloat the size of
	2087	classes derived from multiple empty base classes, even though the base
	2088	classes themselves have no state. For instance, the size of
	2089	<code>point<int></code> from the <a href="#example">example</a>
	2090	above was 12-24 bytes on various compilers for the Win32 platform,
	2091	instead of the expected 8 bytes.</p>
	2092
	2093	<p>Strictly speaking, it was not the library's fault--the language rules
	2094	allow the compiler to apply the empty base class optimization in that
	2095	situation. In principle an arbitrary number of empty base classes can be
	2096	allocated at the same offset, provided that none of them have a common
	2097	ancestor (see section 10.5 [class.derived] paragraph 5 of the standard).
	2098	But the language definition also doesn't <em>require</em> implementations
	2099	to do the optimization, and few if any of today's compilers implement it
	2100	when multiple inheritance is involved. What's worse, it is very unlikely
	2101	that implementors will adopt it as a future enhancement to existing
	2102	compilers, because it would break binary compatibility between code
	2103	generated by two different versions of the same compiler. As Matt Austern
	2104	said, "One of the few times when you have the freedom to do this sort of
	2105	thing is when you're targeting a new architecture...". On the other hand,
	2106	many common compilers will use the empty base optimization for single
	2107	inheritance hierarchies.</p>
	2108
	2109	<p>Given the importance of the issue for the users of the library (which
	2110	aims to be useful for writing light-weight classes like
	2111	<code>MyInt</code> or <code>point<></code>), and the forces
	2112	described above, we decided to change the library interface so that the
	2113	object size bloat could be eliminated even on compilers that support only
	2114	the simplest form of the empty base class optimization. The current
	2115	library interface is the result of those changes. Though the new usage is
	2116	a bit more complicated than the old one, we think it's worth it to make
	2117	the library more useful in real world. Alexy Gurtovoy contributed the
	2118	code which supports the new usage idiom while allowing the library remain
	2119	backward-compatible.</p>
	2120	<hr>
	2121
	2122	<p>Revised: 29 Oct 2004</p>
	2123
	2124	<p>Copyright © Beman Dawes, David Abrahams, 1999-2001.</p>
	2125	<p>Copyright © Daniel Frey, 2002-2004.</p>
	2126	<p>Use, modification, and distribution is subject to the Boost Software
	2127	License, Version 1.0. (See accompanying file
	2128	<a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
	2129	<a href="http://www.boost.org/LICENSE_1_0.txt">
	2130	www.boost.org/LICENSE_1_0.txt</a>)</p>
	2131	</body>
	2132	</html>
	2133

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

Download in other formats: