ceph/src/boost/libs/variant/doc/reference/variant.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4 <!--
   5     Copyright 2003, Eric Friedman, Itay Maman.
   6
   7     Distributed under the Boost Software License, Version 1.0. (See accompanying
   8     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   9 -->
  10 <header name="boost/variant/variant.hpp">
  11   <namespace name="boost">
  12     <class name="variant">
  13       <purpose>Safe, generic, stack-based discriminated union container.</purpose>
  14       <description>
  15         <simpara>The <code>variant</code> class template (inspired by Andrei
  16         Alexandrescu's class of the same name
  17         [<link linkend="variant.refs.ale01a">Ale01A</link>]) is an efficient,
  18         <link linkend="variant.tutorial.recursive">recursive-capable</link>,
  19         bounded discriminated union value type capable of containing any value
  20         type (either POD or non-POD). It supports construction from any type
  21         convertible to one of its bounded types or from a source
  22         <code>variant</code> whose bounded types are each convertible to one
  23         of the destination <code>variant</code>'s bounded types. As well,
  24         through <code><functionname>apply_visitor</functionname></code>,
  25         <code>variant</code> supports compile-time checked, type-safe
  26         visitation; and through <code><functionname>get</functionname></code>,
  27         <code>variant</code> supports run-time checked, type-safe value
  28         retrieval.</simpara>
  29
  30         <simpara><emphasis role="bold">Notes</emphasis>:</simpara>
  31         <itemizedlist>
  32           <listitem>The bounded types of the <code>variant</code> are exposed
  33             via the nested typedef <code>types</code>, which is an
  34             <libraryname>MPL</libraryname>-compatible Sequence containing the
  35             set of types that must be handled by any
  36             <link linkend="variant.concepts.static-visitor">visitor</link> to
  37             the <code>variant</code>.</listitem>
  38           <listitem>All members of <code>variant</code> satisfy at least the
  39             basic guarantee of exception-safety. That is, all operations on
  40             a <code>variant</code> remain defined even after previous
  41             operations have failed.</listitem>
  42           <listitem>Each type specified as a template argument to
  43             <code>variant</code> must meet the requirements of the
  44             <emphasis><link linkend="variant.concepts.bounded-type">BoundedType</link></emphasis>
  45             concept.</listitem>
  46           <listitem>Each type specified as a template argument to
  47             <code>variant</code> must be distinct after removal of qualifiers.
  48             Thus, for instance, both <code>variant&lt;int, int&gt;</code> and
  49             <code>variant&lt;int, const int&gt;</code> have undefined
  50             behavior.</listitem>
  51           <listitem>Conforming implementations of <code>variant</code> must
  52             allow at least ten types as template arguments. The exact number
  53             of allowed arguments is exposed by the preprocessor macro
  54             <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>.
  55             (See <code><classname>make_variant_over</classname></code> for a
  56             means to specify the bounded types of a <code>variant</code> by
  57             the elements of an <libraryname>MPL</libraryname> or compatible
  58             Sequence, thus overcoming this limitation.)</listitem>
  59         </itemizedlist>
  60       </description>
  61
  62       <template>
  63         <template-type-parameter name="T1"/>
  64         <template-type-parameter name="T2">
  65           <default><emphasis>unspecified</emphasis></default>
  66         </template-type-parameter>
  67         <template-varargs/>
  68         <template-type-parameter name="TN">
  69           <default><emphasis>unspecified</emphasis></default>
  70         </template-type-parameter>
  71       </template>
  72
  73       <typedef name="types">
  74         <type><emphasis>unspecified</emphasis></type>
  75       </typedef>
  76
  77       <destructor>
  78         <effects>
  79           <simpara>Destroys the content of <code>*this</code>.</simpara>
  80         </effects>
  81
  82         <throws>Will not throw.</throws>
  83       </destructor>
  84
  85       <constructor>
  86         <requires>
  87           <simpara>The first bounded type of the <code>variant</code> (i.e.,
  88             <code>T1</code>) must fulfill the requirements of the
  89             <emphasis>DefaultConstructible</emphasis> [20.1.4]
  90             concept.</simpara>
  91         </requires>
  92
  93         <postconditions>
  94           <simpara>Content of <code>*this</code> is the default value of the
  95             first bounded type (i.e, <code>T1</code>).</simpara>
  96         </postconditions>
  97
  98         <throws>
  99           <simpara>May fail with any exceptions arising from the default
 100             constructor of <code>T1</code>.</simpara>
 101         </throws>
 102       </constructor>
 103
 104       <constructor>
 105         <parameter name="other">
 106           <paramtype>const variant &amp;</paramtype>
 107         </parameter>
 108
 109         <postconditions>
 110           <simpara>Content of <code>*this</code> is a copy of the content of
 111             <code>other</code>.</simpara>
 112         </postconditions>
 113
 114         <throws>
 115           <simpara>May fail with any exceptions arising from the
 116             copy constructor of <code>other</code>'s contained type.</simpara>
 117         </throws>
 118       </constructor>
 119
 120       <constructor>
 121         <parameter name="other">
 122           <paramtype>variant &amp;&amp;</paramtype>
 123         </parameter>
 124
 125         <requires>
 126           <simpara>C++11 compatible compiler.</simpara>
 127         </requires>
 128
 129         <postconditions>
 130           <simpara>Content of <code>*this</code> is move constructed from the content of
 131             <code>other</code>.</simpara>
 132         </postconditions>
 133
 134         <throws>
 135           <simpara>May fail with any exceptions arising from the
 136             move constructor of <code>other</code>'s contained type.</simpara>
 137         </throws>
 138       </constructor>
 139
 140       <constructor>
 141         <template>
 142           <template-type-parameter name="T"/>
 143         </template>
 144
 145         <parameter name="operand">
 146           <paramtype>T &amp;</paramtype>
 147         </parameter>
 148
 149         <requires>
 150           <simpara><code>T</code> must be unambiguously convertible to one of
 151             the bounded types (i.e., <code>T1</code>, <code>T2</code>,
 152             etc.).</simpara>
 153         </requires>
 154
 155         <postconditions>
 156           <simpara>Content of <code>*this</code> is the best conversion of
 157             <code>operand</code> to one of the bounded types, as determined
 158             by standard overload resolution rules.</simpara>
 159         </postconditions>
 160
 161         <throws>
 162           <simpara>May fail with any exceptions arising from the conversion of
 163             <code>operand</code> to one of the bounded types.</simpara>
 164         </throws>
 165       </constructor>
 166
 167       <constructor>
 168         <template>
 169           <template-type-parameter name="T"/>
 170         </template>
 171
 172         <parameter name="operand">
 173           <paramtype>const T &amp;</paramtype>
 174         </parameter>
 175
 176         <notes>
 177           <simpara>Same semantics as previous constructor, but allows
 178             construction from temporaries.</simpara>
 179         </notes>
 180       </constructor>
 181
 182       <constructor>
 183         <template>
 184           <template-type-parameter name="T"/>
 185         </template>
 186
 187         <parameter name="operand">
 188           <paramtype>T &amp;&amp;</paramtype>
 189         </parameter>
 190
 191         <requires>
 192           <simpara>C++11 compatible compiler.</simpara>
 193         </requires>
 194
 195         <notes>
 196           <simpara>Same semantics as previous constructor, but allows
 197             move construction if <code>operand</code> is an rvalue.</simpara>
 198         </notes>
 199       </constructor>
 200
 201       <constructor>
 202         <template>
 203           <template-type-parameter name="U1"/>
 204           <template-type-parameter name="U2"/>
 205           <template-varargs/>
 206           <template-type-parameter name="UN"/>
 207         </template>
 208
 209         <parameter name="operand">
 210           <paramtype>variant&lt;U1, U2, ..., UN&gt; &amp;</paramtype>
 211         </parameter>
 212
 213         <requires>
 214           <simpara><emphasis>Every</emphasis> one of <code>U1</code>,
 215             <code>U2</code>, ..., <code>UN</code> must have an unambiguous
 216             conversion to one of the bounded types (i.e., <code>T1</code>,
 217             <code>T2</code>, ..., <code>TN</code>).</simpara>
 218         </requires>
 219
 220         <postconditions>
 221           <simpara>If <code>variant&lt;U1, U2, ..., UN&gt;</code> is itself
 222             one of the bounded types, then content of <code>*this</code> is a
 223             copy of <code>operand</code>. Otherwise, content of
 224             <code>*this</code> is the best conversion of the content of
 225             <code>operand</code> to one of the bounded types, as determined
 226             by standard overload resolution rules.</simpara>
 227         </postconditions>
 228
 229         <throws>
 230           <simpara>If <code>variant&lt;U1, U2, ..., UN&gt;</code> is itself
 231           one of the bounded types, then may fail with any exceptions arising
 232           from the copy constructor of
 233           <code>variant&lt;U1, U2, ..., UN&gt;</code>. Otherwise, may fail
 234           with any exceptions arising from the conversion of the content of
 235           <code>operand</code> to one of the bounded types.</simpara>
 236         </throws>
 237       </constructor>
 238
 239       <constructor>
 240         <template>
 241           <template-type-parameter name="U1"/>
 242           <template-type-parameter name="U2"/>
 243           <template-varargs/>
 244           <template-type-parameter name="UN"/>
 245         </template>
 246
 247         <parameter name="operand">
 248           <paramtype>const variant&lt;U1, U2, ..., UN&gt; &amp;</paramtype>
 249         </parameter>
 250
 251         <notes>
 252           <simpara>Same semantics as previous constructor, but allows
 253             construction from temporaries.</simpara>
 254         </notes>
 255       </constructor>
 256
 257       <constructor>
 258         <template>
 259           <template-type-parameter name="U1"/>
 260           <template-type-parameter name="U2"/>
 261           <template-varargs/>
 262           <template-type-parameter name="UN"/>
 263         </template>
 264
 265         <requires>
 266           <simpara>C++11 compatible compiler.</simpara>
 267         </requires>
 268
 269         <parameter name="operand">
 270           <paramtype>variant&lt;U1, U2, ..., UN&gt; &amp;&amp;</paramtype>
 271         </parameter>
 272
 273         <notes>
 274           <simpara>Same semantics as previous constructor, but allows
 275             move construction.</simpara>
 276         </notes>
 277       </constructor>
 278
 279       <method-group name="modifiers">
 280
 281         <method name="swap">
 282           <type>void</type>
 283
 284           <parameter name="other">
 285             <paramtype>variant &amp;</paramtype>
 286           </parameter>
 287
 288           <requires>
 289             <simpara>Every bounded type must fulfill the requirements of the
 290               <conceptname>MoveAssignable</conceptname>
 291               concept.</simpara>
 292           </requires>
 293
 294           <effects>
 295             <simpara>Interchanges the content of <code>*this</code> and
 296               <code>other</code>.</simpara>
 297           </effects>
 298
 299           <throws>
 300             <simpara>If the contained type of <code>other</code> is the same as
 301               the contained type of <code>*this</code>, then may fail with any
 302               exceptions arising from the <code>swap</code> of the contents of
 303               <code>*this</code> and <code>other</code>. Otherwise, may fail
 304               with any exceptions arising from either of the move or copy constructors
 305               of the contained types. Also, in the event of insufficient
 306               memory, may fail with <code>std::bad_alloc</code>
 307               (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
 308           </throws>
 309         </method>
 310
 311         <method name="operator=">
 312           <type>variant &amp;</type>
 313
 314           <parameter name="rhs">
 315             <paramtype>const variant &amp;</paramtype>
 316           </parameter>
 317
 318           <requires>
 319             <simpara>Every bounded type must fulfill the requirements of the
 320               <conceptname>Assignable</conceptname>
 321               concept.</simpara>
 322           </requires>
 323
 324           <effects>
 325             <simpara>If the contained type of <code>rhs</code> is the same as
 326               the contained type of <code>*this</code>, then assigns the
 327               content of <code>rhs</code> into the content of
 328               <code>*this</code>. Otherwise, makes the content of
 329               <code>*this</code> a copy of the content of <code>rhs</code>,
 330               destroying the previous content of <code>*this</code>.</simpara>
 331           </effects>
 332
 333           <throws>
 334             <simpara>If the contained type of <code>rhs</code> is the same as
 335               the contained type of <code>*this</code>, then may fail with any
 336               exceptions arising from the assignment of the content of
 337               <code>rhs</code> into the content <code>*this</code>. Otherwise,
 338               may fail with any exceptions arising from the copy constructor
 339               of the contained type of <code>rhs</code>. Also, in the event of
 340               insufficient memory, may fail with <code>std::bad_alloc</code>
 341               (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
 342           </throws>
 343         </method>
 344
 345         <method name="operator=">
 346           <type>variant &amp;</type>
 347
 348           <parameter name="rhs">
 349             <paramtype>variant &amp;&amp;</paramtype>
 350           </parameter>
 351
 352           <requires>
 353             <itemizedlist>
 354               <listitem>C++11 compatible compiler.</listitem>
 355               <listitem>Every bounded type must fulfill the requirements of the
 356               <conceptname>MoveAssignable</conceptname>
 357               concept.</listitem>
 358             </itemizedlist>
 359           </requires>
 360
 361           <effects>
 362             <simpara>If the contained type of <code>rhs</code> is the same as
 363               the contained type of <code>*this</code>, then move assigns the
 364               content of <code>rhs</code> into the content of
 365               <code>*this</code>. Otherwise, move constructs
 366               <code>*this</code> using the content of <code>rhs</code>,
 367               destroying the previous content of <code>*this</code>.</simpara>
 368           </effects>
 369
 370           <throws>
 371             <simpara>If the contained type of <code>rhs</code> is the same as
 372               the contained type of <code>*this</code>, then may fail with any
 373               exceptions arising from the move assignment of the content of
 374               <code>rhs</code> into the content <code>*this</code>. Otherwise,
 375               may fail with any exceptions arising from the move constructor
 376               of the contained type of <code>rhs</code>. Also, in the event of
 377               insufficient memory, may fail with <code>std::bad_alloc</code>
 378               (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
 379           </throws>
 380         </method>
 381
 382         <method name="operator=">
 383           <type>variant &amp;</type>
 384
 385           <template>
 386             <template-type-parameter name="T"/>
 387           </template>
 388
 389           <parameter name="rhs">
 390             <paramtype>const T &amp;</paramtype>
 391           </parameter>
 392
 393           <requires>
 394             <itemizedlist>
 395               <listitem><code>T</code> must be unambiguously convertible to
 396                 one of the bounded types (i.e., <code>T1</code>,
 397                 <code>T2</code>, etc.).</listitem>
 398               <listitem>Every bounded type must fulfill the requirements of the
 399                 <conceptname>Assignable</conceptname>
 400                 concept.</listitem>
 401             </itemizedlist>
 402           </requires>
 403
 404           <effects>
 405             <simpara>If the contained type of <code>*this</code> is
 406               <code>T</code>, then assigns <code>rhs</code> into the content
 407               of <code>*this</code>. Otherwise, makes the content of
 408               <code>*this</code> the best conversion of <code>rhs</code> to
 409               one of the bounded types, as determined by standard overload
 410               resolution rules, destroying the previous content of
 411               <code>*this</code>.</simpara>
 412           </effects>
 413
 414           <throws>
 415             <simpara>If the contained type of <code>*this</code> is
 416               <code>T</code>, then may fail with any exceptions arising from
 417               the assignment of <code>rhs</code> into the content
 418               <code>*this</code>. Otherwise, may fail with any exceptions
 419               arising from the conversion of <code>rhs</code> to one of the
 420               bounded types. Also, in the event of insufficient memory, may
 421               fail with <code>std::bad_alloc</code>
 422               (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
 423           </throws>
 424         </method>
 425
 426         <method name="operator=">
 427           <type>variant &amp;</type>
 428
 429           <template>
 430             <template-type-parameter name="T"/>
 431           </template>
 432
 433           <parameter name="rhs">
 434             <paramtype>T &amp;&amp;</paramtype>
 435           </parameter>
 436
 437           <requires>
 438             <itemizedlist>
 439               <listitem>C++11 compatible compiler.</listitem>
 440               <listitem><code>rhs</code> is an rvalue. Otherwise previous operator will be used.</listitem>
 441               <listitem><code>T</code> must be unambiguously convertible to
 442                 one of the bounded types (i.e., <code>T1</code>,
 443                 <code>T2</code>, etc.).</listitem>
 444               <listitem>Every bounded type must fulfill the requirements of the
 445                 <conceptname>MoveAssignable</conceptname>
 446                 concept.</listitem>
 447             </itemizedlist>
 448           </requires>
 449
 450           <effects>
 451             <simpara>If the contained type of <code>*this</code> is
 452               <code>T</code>, then move assigns <code>rhs</code> into the content
 453               of <code>*this</code>. Otherwise, makes the content of
 454               <code>*this</code> the best conversion of <code>rhs</code> to
 455               one of the bounded types, as determined by standard overload
 456               resolution rules, destroying the previous content of
 457               <code>*this</code>(conversion is usually done via move construction).</simpara>
 458           </effects>
 459
 460           <throws>
 461             <simpara>If the contained type of <code>*this</code> is
 462               <code>T</code>, then may fail with any exceptions arising from
 463               the move assignment of <code>rhs</code> into the content
 464               <code>*this</code>. Otherwise, may fail with any exceptions
 465               arising from the conversion of <code>rhs</code> to one of the
 466               bounded types. Also, in the event of insufficient memory, may
 467               fail with <code>std::bad_alloc</code>
 468               (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
 469           </throws>
 470         </method>
 471
 472       </method-group>
 473
 474       <method-group name="queries">
 475
 476         <method name="which" cv="const">
 477           <type>int</type>
 478
 479           <returns>
 480             <simpara>The zero-based index into the set of bounded types
 481               of the contained type of <code>*this</code>. (For instance, if
 482               called on a <code>variant&lt;int, std::string&gt;</code> object
 483               containing a <code>std::string</code>, <code>which()</code>
 484               would return <code>1</code>.)</simpara>
 485           </returns>
 486
 487           <throws>Will not throw.</throws>
 488         </method>
 489
 490         <method name="empty" cv="const">
 491           <type>bool</type>
 492
 493           <returns>
 494             <simpara><code>false</code>: <code>variant</code> always contains
 495               exactly one of its bounded types. (See
 496               <xref linkend="variant.design.never-empty"/>
 497               for more information.)</simpara>
 498           </returns>
 499
 500           <rationale>
 501             <simpara>Facilitates generic compatibility with
 502               <classname>boost::any</classname>.</simpara>
 503           </rationale>
 504
 505           <throws>Will not throw.</throws>
 506         </method>
 507
 508         <method name="type" cv="const">
 509           <type>const std::type_info &amp;</type>
 510
 511           <notes>
 512             <simpara><code>boost::variant</code> usues Boost.TypeIndex library so actually
 513             <code>const boost::typeindex::type_info &amp;</code> is returned.
 514             This method is available even if RTTI is off.</simpara>
 515           </notes>
 516
 517           <returns>
 518             <simpara><code>typeid(x)</code>, where <code>x</code> is the the
 519               content of <code>*this</code>.</simpara>
 520           </returns>
 521
 522           <throws>Will not throw.</throws>
 523
 524         </method>
 525
 526       </method-group>
 527
 528       <method-group name="relational">
 529
 530         <overloaded-method name="operator==" cv="const">
 531           <purpose>Equality comparison.</purpose>
 532
 533           <signature cv="const">
 534             <type>bool</type>
 535             <parameter name="rhs">
 536               <paramtype>const variant &amp;</paramtype>
 537             </parameter>
 538           </signature>
 539
 540           <signature cv="const">
 541             <type>void</type>
 542             <template>
 543               <template-type-parameter name="U"/>
 544             </template>
 545             <parameter>
 546               <paramtype>const U &amp;</paramtype>
 547             </parameter>
 548           </signature>
 549
 550           <notes>
 551             <simpara>The overload returning <code>void</code> exists only to
 552               prohibit implicit conversion of the operator's right-hand side
 553               to <code>variant</code>; thus, its use will (purposefully)
 554               result in a compile-time error.</simpara>
 555           </notes>
 556
 557           <requires>
 558             <simpara>Every bounded type of the <code>variant</code> must
 559               fulfill the requirements of the
 560               <conceptname>EqualityComparable</conceptname>
 561               concept.</simpara>
 562           </requires>
 563
 564           <returns>
 565             <simpara><code>true</code> if <code>which() == rhs.which()</code>
 566               <emphasis>and</emphasis>
 567               <code>content_this == content_rhs</code>, where
 568               <code>content_this</code> is the content of <code>*this</code>
 569               and <code>content_rhs</code> is the content of
 570               <code>rhs</code>.</simpara>
 571           </returns>
 572
 573           <throws>
 574             <simpara>If <code>which() == rhs.which()</code> then may fail with
 575               any exceptions arising from <code>operator==(T,T)</code>, where
 576               <code>T</code> is the contained type of
 577               <code>*this</code>.</simpara>
 578           </throws>
 579         </overloaded-method>
 580
 581         <overloaded-method name="operator!=" cv="const">
 582           <purpose>InEquality comparison.</purpose>
 583
 584           <signature cv="const">
 585             <type>bool</type>
 586             <parameter name="rhs">
 587               <paramtype>const variant &amp;</paramtype>
 588             </parameter>
 589           </signature>
 590
 591           <signature cv="const">
 592             <type>void</type>
 593             <template>
 594               <template-type-parameter name="U"/>
 595             </template>
 596             <parameter>
 597               <paramtype>const U &amp;</paramtype>
 598             </parameter>
 599           </signature>
 600
 601           <notes>
 602             <simpara>The overload returning <code>void</code> exists only to
 603               prohibit implicit conversion of the operator's right-hand side
 604               to <code>variant</code>; thus, its use will (purposefully)
 605               result in a compile-time error.</simpara>
 606           </notes>
 607
 608           <requires>
 609             <simpara>Every bounded type of the <code>variant</code> must
 610               fulfill the requirements of the
 611               <conceptname>EqualityComparable</conceptname>
 612               concept.</simpara>
 613           </requires>
 614
 615           <returns>
 616             <simpara><code>true</code> if <code>!(*this == rhs)</code>.</simpara>
 617           </returns>
 618
 619           <throws>
 620             <simpara>If <code>which() == rhs.which()</code> then may fail with
 621               any exceptions arising from <code>operator==(T,T)</code>, where
 622               <code>T</code> is the contained type of
 623               <code>*this</code>.</simpara>
 624           </throws>
 625         </overloaded-method>
 626
 627         <overloaded-method name="operator&lt;">
 628           <purpose>LessThan comparison.</purpose>
 629
 630           <signature cv="const">
 631             <type>bool</type>
 632             <parameter name="rhs">
 633               <paramtype>const variant &amp;</paramtype>
 634             </parameter>
 635           </signature>
 636
 637           <signature cv="const">
 638             <type>void</type>
 639             <template>
 640               <template-type-parameter name="U"/>
 641             </template>
 642             <parameter>
 643               <paramtype>const U &amp;</paramtype>
 644             </parameter>
 645           </signature>
 646
 647           <notes>
 648             <simpara>The overload returning <code>void</code> exists only to
 649               prohibit implicit conversion of the operator's right-hand side
 650               to <code>variant</code>; thus, its use will (purposefully)
 651               result in a compile-time error.</simpara>
 652           </notes>
 653
 654           <requires>
 655             <simpara>Every bounded type of the <code>variant</code> must
 656               fulfill the requirements of the
 657               <conceptname>LessThanComparable</conceptname>
 658               concept.</simpara>
 659           </requires>
 660
 661           <returns>
 662             <simpara>If <code>which() == rhs.which()</code> then:
 663               <code>content_this &lt; content_rhs</code>, where
 664               <code>content_this</code> is the content of <code>*this</code>
 665               and <code>content_rhs</code> is the content of <code>rhs</code>.
 666               Otherwise: <code>which() &lt; rhs.which()</code>.</simpara>
 667           </returns>
 668
 669           <throws>
 670             <simpara>If <code>which() == rhs.which()</code> then may fail with
 671               any exceptions arising from <code>operator&lt;(T,T)</code>,
 672               where <code>T</code> is the contained type of
 673               <code>*this</code>.</simpara>
 674           </throws>
 675         </overloaded-method>
 676
 677
 678         <overloaded-method name="operator&gt;">
 679           <purpose>GreaterThan comparison.</purpose>
 680
 681           <signature cv="const">
 682             <type>bool</type>
 683             <parameter name="rhs">
 684               <paramtype>const variant &amp;</paramtype>
 685             </parameter>
 686           </signature>
 687
 688           <signature cv="const">
 689             <type>void</type>
 690             <template>
 691               <template-type-parameter name="U"/>
 692             </template>
 693             <parameter>
 694               <paramtype>const U &amp;</paramtype>
 695             </parameter>
 696           </signature>
 697
 698           <notes>
 699             <simpara>The overload returning <code>void</code> exists only to
 700               prohibit implicit conversion of the operator's right-hand side
 701               to <code>variant</code>; thus, its use will (purposefully)
 702               result in a compile-time error.</simpara>
 703           </notes>
 704
 705           <requires>
 706             <simpara>Every bounded type of the <code>variant</code> must
 707               fulfill the requirements of the
 708               <conceptname>LessThanComparable</conceptname>
 709               concept.</simpara>
 710           </requires>
 711
 712           <returns>
 713             <simpara>true if <code>rhs &lt; *this</code>.</simpara>
 714           </returns>
 715
 716           <throws>
 717             <simpara>May fail with
 718               any exceptions arising from <code>operator&lt;(T,T)</code>,
 719               where <code>T</code> is the contained type of
 720               <code>*this</code>.</simpara>
 721           </throws>
 722         </overloaded-method>
 723
 724
 725         <overloaded-method name="operator&lt;=">
 726           <purpose>LessThan or Equal comparison.</purpose>
 727
 728           <signature cv="const">
 729             <type>bool</type>
 730             <parameter name="rhs">
 731               <paramtype>const variant &amp;</paramtype>
 732             </parameter>
 733           </signature>
 734
 735           <signature cv="const">
 736             <type>void</type>
 737             <template>
 738               <template-type-parameter name="U"/>
 739             </template>
 740             <parameter>
 741               <paramtype>const U &amp;</paramtype>
 742             </parameter>
 743           </signature>
 744
 745           <notes>
 746             <simpara>The overload returning <code>void</code> exists only to
 747               prohibit implicit conversion of the operator's right-hand side
 748               to <code>variant</code>; thus, its use will (purposefully)
 749               result in a compile-time error.</simpara>
 750           </notes>
 751
 752           <requires>
 753             <simpara>Every bounded type of the <code>variant</code> must
 754               fulfill the requirements of the
 755               <conceptname>LessThanComparable</conceptname>
 756               concept.</simpara>
 757           </requires>
 758
 759           <returns>
 760             <simpara>true if <code>!(*this > rhs)</code>.</simpara>
 761           </returns>
 762
 763           <throws>
 764             <simpara>May fail with
 765               any exceptions arising from <code>operator&lt;(T,T)</code>,
 766               where <code>T</code> is the contained type of
 767               <code>*this</code>.</simpara>
 768           </throws>
 769         </overloaded-method>
 770
 771
 772         <overloaded-method name="operator&gt;=">
 773           <purpose>GreaterThan or Equal comparison.</purpose>
 774
 775           <signature cv="const">
 776             <type>bool</type>
 777             <parameter name="rhs">
 778               <paramtype>const variant &amp;</paramtype>
 779             </parameter>
 780           </signature>
 781
 782           <signature cv="const">
 783             <type>void</type>
 784             <template>
 785               <template-type-parameter name="U"/>
 786             </template>
 787             <parameter>
 788               <paramtype>const U &amp;</paramtype>
 789             </parameter>
 790           </signature>
 791
 792           <notes>
 793             <simpara>The overload returning <code>void</code> exists only to
 794               prohibit implicit conversion of the operator's right-hand side
 795               to <code>variant</code>; thus, its use will (purposefully)
 796               result in a compile-time error.</simpara>
 797           </notes>
 798
 799           <requires>
 800             <simpara>Every bounded type of the <code>variant</code> must
 801               fulfill the requirements of the
 802               <conceptname>LessThanComparable</conceptname>
 803               concept.</simpara>
 804           </requires>
 805
 806           <returns>
 807             <simpara>true if <code>!(*this &lt; lhs)</code>.</simpara>
 808           </returns>
 809
 810           <throws>
 811             <simpara>May fail with
 812               any exceptions arising from <code>operator&lt;(T,T)</code>,
 813               where <code>T</code> is the contained type of
 814               <code>*this</code>.</simpara>
 815           </throws>
 816         </overloaded-method>
 817
 818       </method-group>
 819     </class>
 820
 821     <function name="swap">
 822       <template>
 823         <template-type-parameter name="T1"/>
 824         <template-type-parameter name="T2"/>
 825         <template-varargs/>
 826         <template-type-parameter name="TN"/>
 827       </template>
 828
 829       <type>void</type>
 830
 831       <parameter name="lhs">
 832         <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</paramtype>
 833       </parameter>
 834
 835       <parameter name="rhs">
 836         <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</paramtype>
 837       </parameter>
 838
 839       <effects>
 840         <simpara>Swaps <code>lhs</code> with <code>rhs</code> by application
 841           of <code><methodname>variant::swap</methodname></code>.</simpara>
 842       </effects>
 843
 844       <throws>
 845         <simpara>May fail with any exception arising from
 846           <code><methodname>variant::swap</methodname></code>.</simpara>
 847       </throws>
 848     </function>
 849
 850     <function name="operator&lt;&lt;">
 851       <purpose>Provides streaming output for <code>variant</code> types.</purpose>
 852
 853       <template>
 854         <template-type-parameter name="ElemType"/>
 855         <template-type-parameter name="Traits"/>
 856         <template-type-parameter name="T1"/>
 857         <template-type-parameter name="T2"/>
 858         <template-varargs/>
 859         <template-type-parameter name="TN"/>
 860       </template>
 861
 862       <type>std::basic_ostream&lt;ElemType,Traits&gt; &amp;</type>
 863
 864       <parameter name="out">
 865         <paramtype>std::basic_ostream&lt;ElemType,Traits&gt; &amp;</paramtype>
 866       </parameter>
 867
 868       <parameter name="rhs">
 869         <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</paramtype>
 870       </parameter>
 871
 872       <requires>
 873         <simpara>Every bounded type of the <code>variant</code> must
 874           fulfill the requirements of the
 875           <link linkend="variant.concepts.output-streamable"><emphasis>OutputStreamable</emphasis></link>
 876           concept.</simpara>
 877       </requires>
 878
 879       <effects>
 880         <simpara>Calls <code>out &lt;&lt; x</code>, where <code>x</code> is
 881           the content of <code>rhs</code>.</simpara>
 882       </effects>
 883
 884       <notes>
 885         <simpara>Not available when <code>BOOST_NO_IOSTREAM</code> is
 886           defined.</simpara>
 887       </notes>
 888
 889     </function>
 890
 891     <function name="hash_value">
 892       <purpose>Provides hashing for <code>variant</code> types so
 893       that <code>boost::hash</code> may compute hash.</purpose>
 894
 895       <template>
 896         <template-type-parameter name="T1"/>
 897         <template-type-parameter name="T2"/>
 898         <template-varargs/>
 899         <template-type-parameter name="TN"/>
 900       </template>
 901
 902       <type>std::size_t</type>
 903
 904       <parameter name="rhs">
 905         <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</paramtype>
 906       </parameter>
 907
 908       <requires>
 909         <simpara>Every bounded type of the <code>variant</code> must
 910           fulfill the requirements of the
 911           <link linkend="variant.concepts.hashable"><emphasis>Hashable</emphasis></link>
 912           concept.</simpara>
 913       </requires>
 914
 915       <effects>
 916         <simpara>Calls <code>boost::hash&lt;T&gt;()(x)</code>, where <code>x</code> is
 917           the content of <code>rhs</code> and <code>T</code> is its type.</simpara>
 918       </effects>
 919
 920       <notes>
 921         <simpara>Actually, this function is defined in
 922           <code>&lt;boost/variant/detail/hash_variant.hpp&gt;</code>
 923           header.</simpara>
 924       </notes>
 925
 926     </function>
 927
 928     <class name="make_variant_over">
 929       <purpose>
 930         <simpara>Exposes a <code>variant</code> whose bounded types are the
 931           elements of the given type sequence.</simpara>
 932       </purpose>
 933
 934       <template>
 935         <template-type-parameter name="Sequence"/>
 936       </template>
 937
 938       <typedef name="type">
 939         <type>variant&lt; <emphasis>unspecified</emphasis> &gt;</type>
 940       </typedef>
 941
 942       <description>
 943         <simpara><code>type</code> has behavior equivalent in every respect to
 944           <code><classname>variant</classname>&lt; Sequence[0], Sequence[1], ... &gt;</code>
 945           (where <code>Sequence[<emphasis>i</emphasis>]</code> denotes the
 946           <emphasis>i</emphasis>-th element of <code>Sequence</code>), except
 947           that no upper limit is imposed on the number of types.</simpara>
 948
 949         <simpara><emphasis role="bold">Notes</emphasis>:</simpara>
 950         <itemizedlist>
 951           <listitem><code>Sequence</code> must meet the requirements of
 952             <libraryname>MPL</libraryname>'s <emphasis>Sequence</emphasis>
 953             concept.</listitem>
 954           <listitem>Due to standard conformance problems in several compilers,
 955             <code>make_variant_over</code> may not be supported on your
 956             compiler. See
 957             <code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>
 958             for more information.</listitem>
 959         </itemizedlist>
 960       </description>
 961     </class>
 962   </namespace>
 963 </header>