123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241 |
- <?xml version="1.0" encoding="utf-8"?>
- <!DOCTYPE section 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)
- -->
- <section id="variant.misc">
- <title>Miscellaneous Notes</title>
- <using-namespace name="boost"/>
- <section id="variant.versus-any">
- <title>Boost.Variant vs. Boost.Any</title>
- <para>As a discriminated union container, the Variant library shares many
- of the same features of the <libraryname>Any</libraryname> library.
- However, since neither library wholly encapsulates the features of the
- other, one library cannot be generally recommended for use over the
- other.</para>
- <para>That said, Boost.Variant has several advantages over Boost.Any,
- such as:
- <itemizedlist>
- <listitem>Boost.Variant guarantees the type of its content is one of a
- finite, user-specified set of types.</listitem>
- <listitem>Boost.Variant provides <emphasis>compile-time</emphasis>
- checked visitation of its content. (By contrast, the current version
- of Boost.Any provides no visitation mechanism at all; but even if it
- did, it would need to be checked at run-time.)</listitem>
- <listitem>Boost.Variant enables generic visitation of its content.
- (Even if Boost.Any did provide a visitation mechanism, it would enable
- visitation only of explicitly-specified types.)</listitem>
- <listitem>Boost.Variant offers an efficient, stack-based storage scheme
- (avoiding the overhead of dynamic allocation).</listitem>
- </itemizedlist>
- </para>
- <para>Of course, Boost.Any has several advantages over Boost.Variant,
- such as:
- <itemizedlist>
- <listitem>Boost.Any, as its name implies, allows virtually any type for
- its content, providing great flexibility.</listitem>
- <listitem>Boost.Any provides the no-throw guarantee of exception safety
- for its swap operation.</listitem>
- <listitem>Boost.Any makes little use of template metaprogramming
- techniques (avoiding potentially hard-to-read error messages and
- significant compile-time processor and memory demands).</listitem>
- </itemizedlist>
- </para>
- </section>
- <section>
- <title>Portability</title>
- <para>The library aims for 100% ANSI/ISO C++ conformance. However, this is
- strictly impossible due to the inherently non-portable nature of the
- <libraryname>Type Traits</libraryname> library's
- <code><classname>type_with_alignment</classname></code> facility. In
- practice though, no compilers or platforms have been discovered where this
- reliance on undefined behavior has been an issue.</para>
- <para>Additionally, significant effort has been expended to ensure proper
- functioning despite various compiler bugs and other conformance problems.
- To date the library testsuite has
- been compiled and tested successfully on at least the following compilers
- for basic and advanced functionality:
- <informaltable>
- <tgroup cols="5">
- <thead>
- <row>
- <entry></entry>
- <entry>Basic</entry>
- <entry>
- <code>variant<T&></code>
- </entry>
- <entry>
- <link linkend="variant.tutorial.over-sequence">
- <code>make_variant_over</code>
- </link>
- </entry>
- <entry>
- <link linkend="variant.tutorial.recursive.recursive-variant">
- <code>make_recursive_variant</code>
- </link>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Borland C++ 5.5.1 and 5.6.4</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry>Comeau C++ 4.3.0</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- </row>
- <row>
- <entry>GNU GCC 3.3.1</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- </row>
- <row>
- <entry>GNU GCC 2.95.3</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry></entry>
- <entry>X</entry>
- </row>
- <row>
- <entry>Intel C++ 7.0</entry>
- <entry>X</entry>
- <entry></entry>
- <entry>X</entry>
- <entry>X</entry>
- </row>
- <row>
- <entry>Metrowerks CodeWarrior 8.3</entry>
- <entry>X</entry>
- <entry></entry>
- <entry>X</entry>
- <entry>X</entry>
- </row>
- <row>
- <entry>Microsoft Visual C++ 7.1</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- </row>
- <row>
- <entry>Microsoft Visual C++ 6 SP5 and 7</entry>
- <entry>X</entry>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>Finally, the current state of the testsuite in CVS may be found on the
- <ulink url="http://boost.sourceforge.net/regression-logs">Test Summary</ulink>
- page. Please note, however, that this page reports on day-to-day changes
- to inter-release code found in the Boost CVS and thus likely does not
- match the state of code found in Boost releases.</para>
- </section>
- <section id="variant.troubleshooting">
- <title>Troubleshooting</title>
- <para>Due to the heavy use of templates in the implementation of
- <code>variant</code>, it is not uncommon when compiling to encounter
- problems related to template instantiaton depth, compiler memory, etc. This
- section attempts to provide advice to common problems experienced on several
- popular compilers.</para>
-
- <para>(This section is still in progress, with additional advice/feedback
- welcome. Please post to the Boost-Users list with any useful experiences you
- may have.)</para>
- <section id="variant.troubleshooting.template-depth">
- <title>"Template instantiation depth exceeds maximum"</title>
-
- <section id="variant.troubleshooting.template-depth.gcc">
- <title>GNU GCC</title>
- <para>The compiler option
- <code>-ftemplate-depth-<emphasis>NN</emphasis></code> can increase the
- maximum allowed instantiation depth. (Try
- <code>-ftemplate-depth-50</code>.)</para>
- </section>
- </section>
-
- <section id="variant.troubleshooting.compiler-memory">
- <title>"Internal heap limit reached"</title>
-
- <section id="variant.troubleshooting.compiler-memory.msvc">
- <title>Microsoft Visual C++</title>
- <para>The compiler option <code>/Zm<emphasis>NNN</emphasis></code> can
- increase the memory allocation limit. The <code>NNN</code> is a
- scaling percentage (i.e., <code>100</code> denotes the default limit).
- (Try <code>/Zm200</code>.)</para>
- </section>
- </section>
- </section>
- <section id="variant.ack">
- <title>Acknowledgments</title>
- <para>Eric Friedman and Itay Maman designed the initial submission; Eric was
- the primary implementer.</para>
- <para>Eric is also the library maintainer and has expanded upon the initial
- submission -- adding
- <code><classname>make_recursive_variant</classname></code>,
- <code><classname>make_variant_over</classname></code>, support for
- reference content, etc.</para>
- <para>Andrei Alexandrescu's work in
- [<link linkend="variant.refs.ale01a">Ale01a</link>]
- and
- [<link linkend="variant.refs.ale02">Ale02</link>]
- inspired the library's design.</para>
- <para>Jeff Garland was the formal review manager.</para>
- <para>Douglas Gregor,
- Dave Abrahams,
- Anthony Williams,
- Fernando Cacciola,
- Joel de Guzman,
- Dirk Schreib,
- Brad King,
- Giovanni Bajo,
- Eugene Gladyshev,
- and others provided helpful feedback and suggestions to refine the semantics,
- interface, and implementation of the library.</para>
- </section>
- </section>
|