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