mirror of
https://github.com/boostorg/variant.git
synced 2025-05-12 13:51:46 +00:00
367 lines
12 KiB
XML
367 lines
12 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">
|
|
<!--
|
|
Copyright 2003, Eric Friedman, Itay Maman.
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
-->
|
|
<header name="boost/variant/get.hpp">
|
|
<namespace name="boost">
|
|
|
|
<class name="bad_get">
|
|
<inherit access="public">
|
|
<classname>std::exception</classname>
|
|
</inherit>
|
|
|
|
<purpose>
|
|
<simpara>The exception thrown in the event of a failed application of
|
|
<code><functionname>boost::get</functionname></code> on the given
|
|
operand value.</simpara>
|
|
</purpose>
|
|
|
|
<method name="what" specifiers="virtual" cv="const">
|
|
<type>const char *</type>
|
|
</method>
|
|
</class>
|
|
|
|
<overloaded-function name="relaxed_get">
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U *</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> *</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>const U *</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype>const <classname>variant</classname><T1, T2, ..., TN> *</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U &</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>const U &</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U &&</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> &&</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<purpose>
|
|
<simpara>Retrieves a value of a specified type from a given
|
|
<code><classname>variant</classname></code>. </simpara>
|
|
<simpara>Unlike <functionname>strict_get</functionname> does not assert at compile time
|
|
that type <code>U</code> is one of the types that can be stored in variant.</simpara>
|
|
</purpose>
|
|
|
|
<description>
|
|
<simpara>The <code>get</code> function allows run-time checked,
|
|
type-safe retrieval of the content of the given
|
|
<code><classname>variant</classname></code>. The function succeeds
|
|
only if the content is of the specified type <code>U</code>, with
|
|
failure indicated as described below.</simpara>
|
|
<simpara><emphasis role="bold">Recomendation</emphasis>: Use
|
|
<functionname>get</functionname> or <functionname>strict_get</functionname> in new code.
|
|
<functionname>strict_get</functionname>
|
|
provides more compile time checks and its behavior is closer to <code>std::get</code>
|
|
from C++ Standard Library.</simpara>
|
|
<simpara><emphasis role="bold">Warning</emphasis>: After either
|
|
<code>operand</code> or its content is destroyed (e.g., when the
|
|
given <code><classname>variant</classname></code> is assigned a
|
|
value of different type), the returned reference is invalidated.
|
|
Thus, significant care and caution must be extended when handling
|
|
the returned reference.</simpara>
|
|
</description>
|
|
|
|
<notes>
|
|
<simpara>As part of its guarantee of type-safety, <code>get</code>
|
|
enforces <code>const</code>-correctness. Thus, the specified type
|
|
<code>U</code> must be <code>const</code>-qualified whenever
|
|
<code>operand</code> or its content is likewise
|
|
<code>const</code>-qualified. The converse, however, is not required:
|
|
that is, the specified type <code>U</code> may be
|
|
<code>const</code>-qualified even when <code>operand</code> and its
|
|
content are not.</simpara>
|
|
</notes>
|
|
|
|
<returns>
|
|
<simpara>If passed a pointer, <code>get</code> returns a pointer to
|
|
the value content if it is of the specified type <code>U</code>;
|
|
otherwise, a null pointer is returned. If passed a reference,
|
|
<code>get</code> returns a reference to the value content if it is of
|
|
the specified type <code>U</code>; otherwise, an exception is thrown
|
|
(see below).</simpara>
|
|
</returns>
|
|
|
|
<throws>
|
|
<simpara>Overloads taking a
|
|
<code><classname>variant</classname></code> pointer will not
|
|
throw; the overloads taking a
|
|
<code><classname>variant</classname></code> reference throw
|
|
<code><classname>bad_get</classname></code> if the content is not of
|
|
the specified type <code>U</code>.</simpara>
|
|
</throws>
|
|
|
|
<rationale>
|
|
<simpara>While visitation via
|
|
<code><functionname>apply_visitor</functionname></code>
|
|
is generally preferred due to its greater safety, <code>get</code> may
|
|
may be more convenient in some cases due to its straightforward
|
|
usage.</simpara>
|
|
</rationale>
|
|
</overloaded-function>
|
|
|
|
<overloaded-function name="strict_get">
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U *</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> *</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>const U *</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype>const <classname>variant</classname><T1, T2, ..., TN> *</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U &</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>const U &</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U &&</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> &&</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<purpose>
|
|
<simpara>Retrieves a value of a specified type from a given
|
|
<code><classname>variant</classname></code>.</simpara>
|
|
</purpose>
|
|
|
|
<description>
|
|
<simpara>Acts exactly like <functionname>relaxed_get</functionname> but does a compile time check
|
|
that type <code>U</code> is one of the types that can be stored in variant.</simpara>
|
|
</description>
|
|
</overloaded-function>
|
|
|
|
<overloaded-function name="get">
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U *</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> *</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>const U *</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype>const <classname>variant</classname><T1, T2, ..., TN> *</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U &</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>const U &</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="U"/>
|
|
<template-type-parameter name="T1"/>
|
|
<template-type-parameter name="T2"/>
|
|
<template-varargs/>
|
|
<template-type-parameter name="TN"/>
|
|
</template>
|
|
|
|
<type>U &&</type>
|
|
|
|
<parameter name="operand">
|
|
<paramtype><classname>variant</classname><T1, T2, ..., TN> &&</paramtype>
|
|
</parameter>
|
|
</signature>
|
|
|
|
<purpose>
|
|
<simpara>Retrieves a value of a specified type from a given
|
|
<code><classname>variant</classname></code>.</simpara>
|
|
</purpose>
|
|
|
|
<description>
|
|
<simpara>Evaluates to <functionname>strict_get</functionname> if <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>
|
|
is not defined. If <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>
|
|
is defined then evaluates to <functionname>relaxed_get</functionname>. </simpara>
|
|
|
|
<simpara><emphasis role="bold">Recomendation</emphasis>: Use
|
|
<functionname>get</functionname> in new code without defining
|
|
<code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>. In that way <functionname>get</functionname>
|
|
provides more compile time checks and its behavior is closer to <code>std::get</code>
|
|
from C++ Standard Library.</simpara>
|
|
</description>
|
|
</overloaded-function>
|
|
|
|
</namespace>
|
|
</header>
|