mirror of
https://github.com/boostorg/variant.git
synced 2026-02-11 12:22:11 +00:00
426 lines
16 KiB
XML
426 lines
16 KiB
XML
<?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.biblio.ale01a">Ale01A</link>]) is an efficient,
|
|
<classname alt="boost::recursive_variant">recursive-capable</classname>,
|
|
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>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. For instance, use of
|
|
<code>variant<int, int></code> or
|
|
<code>variant<int, const int></code> results in 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>.</listitem>
|
|
<listitem>The following syntax is also supported:
|
|
<code>variant< <emphasis>type-sequence</emphasis> ></code>,
|
|
where <emphasis>type-sequence</emphasis> must meet the requirements
|
|
of the <libraryname>MPL</libraryname>'s
|
|
<emphasis>Sequence</emphasis> concept. For instance,
|
|
<code>variant< mpl::list<int, std::string> ></code> is
|
|
functionally equivalent to
|
|
<code>variant< int, std::string ></code>. (Due to standard
|
|
conformance problems in several compilers, however, this syntax may
|
|
not be supported on your compiler. See
|
|
<code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>
|
|
for more information.)</listitem>
|
|
</itemizedlist>
|
|
</description>
|
|
|
|
<template>
|
|
<template-type-parameter name="T1">
|
|
<default><classname>boost::empty</classname></default>
|
|
</template-type-parameter>
|
|
<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>
|
|
<purpose>T1, T2, ..., TN as an <libraryname>MPL</libraryname>-compatible Sequence.</purpose>
|
|
</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
|
|
<link linkend="variant.concepts.assignable"><emphasis>Assignable</emphasis></link>
|
|
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.</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
|
|
<link linkend="variant.concepts.assignable"><emphasis>Assignable</emphasis></link>
|
|
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>.</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
|
|
<link linkend="variant.concepts.assignable"><emphasis>Assignable</emphasis></link>
|
|
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.</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>true</code> if and only if the contained type of
|
|
<code>*this</code> is
|
|
<code><classname>boost::empty</classname></code>.</simpara>
|
|
</returns>
|
|
|
|
<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>
|
|
</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<<">
|
|
<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>
|
|
</function>
|
|
</namespace>
|
|
</header> |