| <?xml version="1.0" encoding="utf-8"?> |
| <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" |
| "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> |
| <header name="boost/variant/variant.hpp"> |
| <namespace name="boost"> |
| <class name="variant"> |
| <purpose>Safe, generic, stack-based discriminated union container.</purpose> |
| <description> |
| <simpara>The <code>variant</code> class template (inspired by Andrei |
| Alexandrescu's class of the same name |
| [<link linkend="variant.refs.ale01a">Ale01A</link>]) is an efficient, |
| <link linkend="variant.tutorial.recursive">recursive-capable</link>, |
| bounded discriminated union value type capable of containing any value |
| type (either POD or non-POD). It supports construction from any type |
| convertible to one of its bounded types or from a source |
| <code>variant</code> whose bounded types are each convertible to one |
| of the destination <code>variant</code>'s bounded types. As well, |
| through <code><functionname>apply_visitor</functionname></code>, |
| <code>variant</code> supports compile-time checked, type-safe |
| visitation; and through <code><functionname>get</functionname></code>, |
| <code>variant</code> supports run-time checked, type-safe value |
| retrieval.</simpara> |
| |
| <simpara><emphasis role="bold">Notes</emphasis>:</simpara> |
| <itemizedlist> |
| <listitem>The bounded types of the <code>variant</code> are exposed |
| via the nested typedef <code>types</code>, which is an |
| <libraryname>MPL</libraryname>-compatible Sequence containing the |
| set of types that must be handled by any |
| <link linkend="variant.concepts.static-visitor">visitor</link> to |
| the <code>variant</code>.</listitem> |
| <listitem>All members of <code>variant</code> satisfy at least the |
| basic guarantee of exception-safety. That is, all operations on |
| a <code>variant</code> remain defined even after previous |
| operations have failed.</listitem> |
| <listitem>Each type specified as a template argument to |
| <code>variant</code> must meet the requirements of the |
| <emphasis><link linkend="variant.concepts.bounded-type">BoundedType</link></emphasis> |
| concept.</listitem> |
| <listitem>Each type specified as a template argument to |
| <code>variant</code> must be distinct after removal of qualifiers. |
| Thus, for instance, both <code>variant<int, int></code> and |
| <code>variant<int, const int></code> have undefined |
| behavior.</listitem> |
| <listitem>Conforming implementations of <code>variant</code> must |
| allow at least ten types as template arguments. The exact number |
| of allowed arguments is exposed by the preprocessor macro |
| <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>. |
| (See <code><classname>make_variant_over</classname></code> for a |
| means to specify the bounded types of a <code>variant</code> by |
| the elements of an <libraryname>MPL</libraryname> or compatible |
| Sequence, thus overcoming this limitation.)</listitem> |
| </itemizedlist> |
| </description> |
| |
| <template> |
| <template-type-parameter name="T1"/> |
| <template-type-parameter name="T2"> |
| <default><emphasis>unspecified</emphasis></default> |
| </template-type-parameter> |
| <template-varargs/> |
| <template-type-parameter name="TN"> |
| <default><emphasis>unspecified</emphasis></default> |
| </template-type-parameter> |
| </template> |
| |
| <typedef name="types"> |
| <type><emphasis>unspecified</emphasis></type> |
| </typedef> |
| |
| <destructor> |
| <effects> |
| <simpara>Destroys the content of <code>*this</code>.</simpara> |
| </effects> |
| |
| <throws>Will not throw.</throws> |
| </destructor> |
| |
| <constructor> |
| <requires> |
| <simpara>The first bounded type of the <code>variant</code> (i.e., |
| <code>T1</code>) must fulfill the requirements of the |
| <emphasis>DefaultConstructible</emphasis> [20.1.4] |
| concept.</simpara> |
| </requires> |
| |
| <postconditions> |
| <simpara>Content of <code>*this</code> is the default value of the |
| first bounded type (i.e, <code>T1</code>).</simpara> |
| </postconditions> |
| |
| <throws> |
| <simpara>May fail with any exceptions arising from the default |
| constructor of <code>T1</code>.</simpara> |
| </throws> |
| </constructor> |
| |
| <constructor> |
| <parameter name="other"> |
| <paramtype>const variant &</paramtype> |
| </parameter> |
| |
| <postconditions> |
| <simpara>Content of <code>*this</code> is a copy of the content of |
| <code>other</code>.</simpara> |
| </postconditions> |
| |
| <throws> |
| <simpara>May fail with any exceptions arising from the |
| copy constructor of <code>other</code>'s contained type.</simpara> |
| </throws> |
| </constructor> |
| |
| <constructor> |
| <template> |
| <template-type-parameter name="T"/> |
| </template> |
| |
| <parameter name="operand"> |
| <paramtype>T &</paramtype> |
| </parameter> |
| |
| <requires> |
| <simpara><code>T</code> must be unambiguously convertible to one of |
| the bounded types (i.e., <code>T1</code>, <code>T2</code>, |
| etc.).</simpara> |
| </requires> |
| |
| <postconditions> |
| <simpara>Content of <code>*this</code> is the best conversion of |
| <code>operand</code> to one of the bounded types, as determined |
| by standard overload resolution rules.</simpara> |
| </postconditions> |
| |
| <throws> |
| <simpara>May fail with any exceptions arising from the conversion of |
| <code>operand</code> to one of the bounded types.</simpara> |
| </throws> |
| </constructor> |
| |
| <constructor> |
| <template> |
| <template-type-parameter name="T"/> |
| </template> |
| |
| <parameter name="operand"> |
| <paramtype>const T &</paramtype> |
| </parameter> |
| |
| <notes> |
| <simpara>Same semantics as previous constructor, but allows |
| construction from temporaries.</simpara> |
| </notes> |
| </constructor> |
| |
| <constructor> |
| <template> |
| <template-type-parameter name="U1"/> |
| <template-type-parameter name="U2"/> |
| <template-varargs/> |
| <template-type-parameter name="UN"/> |
| </template> |
| |
| <parameter name="operand"> |
| <paramtype>variant<U1, U2, ..., UN> &</paramtype> |
| </parameter> |
| |
| <requires> |
| <simpara><emphasis>Every</emphasis> one of <code>U1</code>, |
| <code>U2</code>, ..., <code>UN</code> must have an unambiguous |
| conversion to one of the bounded types (i.e., <code>T1</code>, |
| <code>T2</code>, ..., <code>TN</code>).</simpara> |
| </requires> |
| |
| <postconditions> |
| <simpara>If <code>variant<U1, U2, ..., UN></code> is itself |
| one of the bounded types, then content of <code>*this</code> is a |
| copy of <code>operand</code>. Otherwise, content of |
| <code>*this</code> is the best conversion of the content of |
| <code>operand</code> to one of the bounded types, as determined |
| by standard overload resolution rules.</simpara> |
| </postconditions> |
| |
| <throws> |
| <simpara>If <code>variant<U1, U2, ..., UN></code> is itself |
| one of the bounded types, then may fail with any exceptions arising |
| from the copy constructor of |
| <code>variant<U1, U2, ..., UN></code>. Otherwise, may fail |
| with any exceptions arising from the conversion of the content of |
| <code>operand</code> to one of the bounded types.</simpara> |
| </throws> |
| </constructor> |
| |
| <constructor> |
| <template> |
| <template-type-parameter name="U1"/> |
| <template-type-parameter name="U2"/> |
| <template-varargs/> |
| <template-type-parameter name="UN"/> |
| </template> |
| |
| <parameter name="operand"> |
| <paramtype>const variant<U1, U2, ..., UN> &</paramtype> |
| </parameter> |
| |
| <notes> |
| <simpara>Same semantics as previous constructor, but allows |
| construction from temporaries.</simpara> |
| </notes> |
| </constructor> |
| |
| <method-group name="modifiers"> |
| |
| <method name="swap"> |
| <type>void</type> |
| |
| <parameter name="other"> |
| <paramtype>variant &</paramtype> |
| </parameter> |
| |
| <requires> |
| <simpara>Every bounded type must fulfill the requirements of the |
| <conceptname>Assignable</conceptname> |
| concept.</simpara> |
| </requires> |
| |
| <effects> |
| <simpara>Interchanges the content of <code>*this</code> and |
| <code>other</code>.</simpara> |
| </effects> |
| |
| <throws> |
| <simpara>If the contained type of <code>other</code> is the same as |
| the contained type of <code>*this</code>, then may fail with any |
| exceptions arising from the <code>swap</code> of the contents of |
| <code>*this</code> and <code>other</code>. Otherwise, may fail |
| with any exceptions arising from either of the copy constructors |
| of the contained types. Also, in the event of insufficient |
| memory, may fail with <code>std::bad_alloc</code> |
| (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara> |
| </throws> |
| </method> |
| |
| <method name="operator="> |
| <type>variant &</type> |
| |
| <parameter name="rhs"> |
| <paramtype>const variant &</paramtype> |
| </parameter> |
| |
| <requires> |
| <simpara>Every bounded type must fulfill the requirements of the |
| <conceptname>Assignable</conceptname> |
| concept.</simpara> |
| </requires> |
| |
| <effects> |
| <simpara>If the contained type of <code>rhs</code> is the same as |
| the contained type of <code>*this</code>, then assigns the |
| content of <code>rhs</code> into the content of |
| <code>*this</code>. Otherwise, makes the content of |
| <code>*this</code> a copy of the content of <code>rhs</code>, |
| destroying the previous content of <code>*this</code>.</simpara> |
| </effects> |
| |
| <throws> |
| <simpara>If the contained type of <code>rhs</code> is the same as |
| the contained type of <code>*this</code>, then may fail with any |
| exceptions arising from the assignment of the content of |
| <code>rhs</code> into the content <code>*this</code>. Otherwise, |
| may fail with any exceptions arising from the copy constructor |
| of the contained type of <code>rhs</code>. Also, in the event of |
| insufficient memory, may fail with <code>std::bad_alloc</code> |
| (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara> |
| </throws> |
| </method> |
| |
| <method name="operator="> |
| <type>variant &</type> |
| |
| <template> |
| <template-type-parameter name="T"/> |
| </template> |
| |
| <parameter name="rhs"> |
| <paramtype>const T &</paramtype> |
| </parameter> |
| |
| <requires> |
| <itemizedlist> |
| <listitem><code>T</code> must be unambiguously convertible to |
| one of the bounded types (i.e., <code>T1</code>, |
| <code>T2</code>, etc.).</listitem> |
| <listitem>Every bounded type must fulfill the requirements of the |
| <conceptname>Assignable</conceptname> |
| concept.</listitem> |
| </itemizedlist> |
| </requires> |
| |
| <effects> |
| <simpara>If the contained type of <code>*this</code> is |
| <code>T</code>, then assigns <code>rhs</code> into the content |
| of <code>*this</code>. Otherwise, makes the content of |
| <code>*this</code> the best conversion of <code>rhs</code> to |
| one of the bounded types, as determined by standard overload |
| resolution rules, destroying the previous content of |
| <code>*this</code>.</simpara> |
| </effects> |
| |
| <throws> |
| <simpara>If the contained type of <code>*this</code> is |
| <code>T</code>, then may fail with any exceptions arising from |
| the assignment of <code>rhs</code> into the content |
| <code>*this</code>. Otherwise, may fail with any exceptions |
| arising from the conversion of <code>rhs</code> to one of the |
| bounded types. Also, in the event of insufficient memory, may |
| fail with <code>std::bad_alloc</code> |
| (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara> |
| </throws> |
| </method> |
| |
| </method-group> |
| |
| <method-group name="queries"> |
| |
| <method name="which" cv="const"> |
| <type>int</type> |
| |
| <returns> |
| <simpara>The zero-based index into the set of bounded types |
| of the contained type of <code>*this</code>. (For instance, if |
| called on a <code>variant<int, std::string></code> object |
| containing a <code>std::string</code>, <code>which()</code> |
| would return <code>1</code>.)</simpara> |
| </returns> |
| |
| <throws>Will not throw.</throws> |
| </method> |
| |
| <method name="empty" cv="const"> |
| <type>bool</type> |
| |
| <returns> |
| <simpara><code>false</code>: <code>variant</code> always contains |
| exactly one of its bounded types. (See |
| <xref linkend="variant.design.never-empty"/> |
| for more information.)</simpara> |
| </returns> |
| |
| <rationale> |
| <simpara>Facilitates generic compatibility with |
| <classname>boost::any</classname>.</simpara> |
| </rationale> |
| |
| <throws>Will not throw.</throws> |
| </method> |
| |
| <method name="type" cv="const"> |
| <type>const std::type_info &</type> |
| |
| <returns> |
| <simpara><code>typeid(x)</code>, where <code>x</code> is the the |
| content of <code>*this</code>.</simpara> |
| </returns> |
| |
| <throws>Will not throw.</throws> |
| |
| <notes> |
| <simpara>Not available when <code>BOOST_NO_TYPEID</code> is |
| defined.</simpara> |
| </notes> |
| </method> |
| |
| </method-group> |
| |
| <method-group name="relational"> |
| |
| <overloaded-method name="operator==" cv="const"> |
| <purpose>Equality comparison.</purpose> |
| |
| <signature cv="const"> |
| <type>bool</type> |
| <parameter name="rhs"> |
| <paramtype>const variant &</paramtype> |
| </parameter> |
| </signature> |
| |
| <signature cv="const"> |
| <type>void</type> |
| <template> |
| <template-type-parameter name="U"/> |
| </template> |
| <parameter> |
| <paramtype>const U &</paramtype> |
| </parameter> |
| </signature> |
| |
| <notes> |
| <simpara>The overload returning <code>void</code> exists only to |
| prohibit implicit conversion of the operator's right-hand side |
| to <code>variant</code>; thus, its use will (purposefully) |
| result in a compile-time error.</simpara> |
| </notes> |
| |
| <requires> |
| <simpara>Every bounded type of the <code>variant</code> must |
| fulfill the requirements of the |
| <conceptname>EqualityComparable</conceptname> |
| concept.</simpara> |
| </requires> |
| |
| <returns> |
| <simpara><code>true</code> iff <code>which() == rhs.which()</code> |
| <emphasis>and</emphasis> |
| <code>content_this == content_rhs</code>, where |
| <code>content_this</code> is the content of <code>*this</code> |
| and <code>content_rhs</code> is the content of |
| <code>rhs</code>.</simpara> |
| </returns> |
| |
| <throws> |
| <simpara>If <code>which() == rhs.which()</code> then may fail with |
| any exceptions arising from <code>operator==(T,T)</code>, where |
| <code>T</code> is the contained type of |
| <code>*this</code>.</simpara> |
| </throws> |
| </overloaded-method> |
| |
| <overloaded-method name="operator<"> |
| <purpose>LessThan comparison.</purpose> |
| |
| <signature cv="const"> |
| <type>bool</type> |
| <parameter name="rhs"> |
| <paramtype>const variant &</paramtype> |
| </parameter> |
| </signature> |
| |
| <signature cv="const"> |
| <type>void</type> |
| <template> |
| <template-type-parameter name="U"/> |
| </template> |
| <parameter> |
| <paramtype>const U &</paramtype> |
| </parameter> |
| </signature> |
| |
| <notes> |
| <simpara>The overload returning <code>void</code> exists only to |
| prohibit implicit conversion of the operator's right-hand side |
| to <code>variant</code>; thus, its use will (purposefully) |
| result in a compile-time error.</simpara> |
| </notes> |
| |
| <requires> |
| <simpara>Every bounded type of the <code>variant</code> must |
| fulfill the requirements of the |
| <conceptname>LessThanComparable</conceptname> |
| concept.</simpara> |
| </requires> |
| |
| <returns> |
| <simpara>If <code>which() == rhs.which()</code> then: |
| <code>content_this < content_rhs</code>, where |
| <code>content_this</code> is the content of <code>*this</code> |
| and <code>content_rhs</code> is the content of <code>rhs</code>. |
| Otherwise: <code>which() < rhs.which()</code>.</simpara> |
| </returns> |
| |
| <throws> |
| <simpara>If <code>which() == rhs.which()</code> then may fail with |
| any exceptions arising from <code>operator<(T,T)</code>, |
| where <code>T</code> is the contained type of |
| <code>*this</code>.</simpara> |
| </throws> |
| </overloaded-method> |
| |
| </method-group> |
| </class> |
| |
| <function name="swap"> |
| <template> |
| <template-type-parameter name="T1"/> |
| <template-type-parameter name="T2"/> |
| <template-varargs/> |
| <template-type-parameter name="TN"/> |
| </template> |
| |
| <type>void</type> |
| |
| <parameter name="lhs"> |
| <paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype> |
| </parameter> |
| |
| <parameter name="rhs"> |
| <paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype> |
| </parameter> |
| |
| <effects> |
| <simpara>Swaps <code>lhs</code> with <code>rhs</code> by application |
| of <code><methodname>variant::swap</methodname></code>.</simpara> |
| </effects> |
| |
| <throws> |
| <simpara>May fail with any exception arising from |
| <code><methodname>variant::swap</methodname></code>.</simpara> |
| </throws> |
| </function> |
| |
| <function name="operator<<"> |
| <purpose>Provides streaming output for <code>variant</code> types.</purpose> |
| |
| <template> |
| <template-type-parameter name="ElemType"/> |
| <template-type-parameter name="Traits"/> |
| <template-type-parameter name="T1"/> |
| <template-type-parameter name="T2"/> |
| <template-varargs/> |
| <template-type-parameter name="TN"/> |
| </template> |
| |
| <type>std::basic_ostream<ElemType,Traits> &</type> |
| |
| <parameter name="out"> |
| <paramtype>std::basic_ostream<ElemType,Traits> &</paramtype> |
| </parameter> |
| |
| <parameter name="rhs"> |
| <paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype> |
| </parameter> |
| |
| <requires> |
| <simpara>Every bounded type of the <code>variant</code> must |
| fulfill the requirements of the |
| <link linkend="variant.concepts.output-streamable"><emphasis>OutputStreamable</emphasis></link> |
| concept.</simpara> |
| </requires> |
| |
| <effects> |
| <simpara>Calls <code>out << x</code>, where <code>x</code> is |
| the content of <code>rhs</code>.</simpara> |
| </effects> |
| |
| <notes> |
| <simpara>Not available when <code>BOOST_NO_IOSTREAM</code> is |
| defined.</simpara> |
| </notes> |
| |
| </function> |
| |
| <class name="make_variant_over"> |
| <purpose> |
| <simpara>Exposes a <code>variant</code> whose bounded types are the |
| elements of the given type sequence.</simpara> |
| </purpose> |
| |
| <template> |
| <template-type-parameter name="Sequence"/> |
| </template> |
| |
| <typedef name="type"> |
| <type>variant< <emphasis>unspecified</emphasis> ></type> |
| </typedef> |
| |
| <description> |
| <simpara><code>type</code> has behavior equivalent in every respect to |
| <code><classname>variant</classname>< Sequence[0], Sequence[1], ... ></code> |
| (where <code>Sequence[<emphasis>i</emphasis>]</code> denotes the |
| <emphasis>i</emphasis>-th element of <code>Sequence</code>), except |
| that no upper limit is imposed on the number of types.</simpara> |
| |
| <simpara><emphasis role="bold">Notes</emphasis>:</simpara> |
| <itemizedlist> |
| <listitem><code>Sequence</code> must meet the requirements of |
| <libraryname>MPL</libraryname>'s <emphasis>Sequence</emphasis> |
| concept.</listitem> |
| <listitem>Due to standard conformance problems in several compilers, |
| <code>make_variant_over</code> may not be supported on your |
| compiler. See |
| <code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code> |
| for more information.</listitem> |
| </itemizedlist> |
| </description> |
| </class> |
| </namespace> |
| </header> |