123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326 |
- <?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 2013-2019 Antony Polukhin.
- 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/polymorphic_get.hpp">
- <namespace name="boost">
- <class name="bad_polymorphic_get">
- <inherit access="public">
- <classname>boost::bad_get</classname>
- </inherit>
- <purpose>
- <simpara>The exception thrown in the event of a failed application of
- <code><functionname>boost::polymorphic_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="polymorphic_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>
- <purpose>
- <simpara>Retrieves a value of a specified type from a given
- <code><classname>variant</classname></code>.</simpara>
- <simpara>Unlike <functionname>polymorphic_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>polymorphic_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> or of type
- derived from type <code>U</code>, with
- failure indicated as described below.</simpara>
- <simpara><emphasis role="bold">Recomendation</emphasis>: Use
- <functionname>polymorphic_get</functionname> or <functionname>polymorphic_strict_get</functionname>
- in new code.
- <functionname>polymorphic_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>polymorphic_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>polymorphic_get</code> returns a pointer to
- the value content if it is of the specified type <code>U</code> or of type
- derived from type <code>U</code>;
- otherwise, a null pointer is returned. If passed a reference,
- <code>polymorphic_get</code> returns a reference to the value content if it is of
- the specified type <code>U</code> or of type
- derived from 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_polymorphic_get</classname></code> if the content is not of
- the specified type <code>U</code>or of type
- derived from 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>polymorphic_get</code> may
- may be more convenient in some cases due to its straightforward
- usage.</simpara>
- </rationale>
- </overloaded-function>
- <overloaded-function name="polymorphic_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>
- <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>polymorphic_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="polymorphic_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>
- <purpose>
- <simpara>Retrieves a value of a specified type from a given
- <code><classname>variant</classname></code>.</simpara>
- </purpose>
- <description>
- <simpara>Evaluates to <functionname>polymorphic_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>polymorphic_relaxed_get</functionname>. </simpara>
- <simpara><emphasis role="bold">Recomendation</emphasis>: Use
- <functionname>polymorphic_get</functionname> in new code without defining
- <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>. In that way
- <functionname>polymorphic_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>
|