1<?xml version="1.0" encoding="utf-8"?> 2<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 3 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 4<!-- 5 Copyright 2003, Eric Friedman, Itay Maman. 6 7 Distributed under the Boost Software License, Version 1.0. (See accompanying 8 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 9--> 10<section id="variant.misc"> 11 <title>Miscellaneous Notes</title> 12 13<using-namespace name="boost"/> 14 15<section id="variant.versus-any"> 16 <title>Boost.Variant vs. Boost.Any</title> 17 18 <para>As a discriminated union container, the Variant library shares many 19 of the same features of the <libraryname>Any</libraryname> library. 20 However, since neither library wholly encapsulates the features of the 21 other, one library cannot be generally recommended for use over the 22 other.</para> 23 24 <para>That said, Boost.Variant has several advantages over Boost.Any, 25 such as: 26 27 <itemizedlist> 28 <listitem>Boost.Variant guarantees the type of its content is one of a 29 finite, user-specified set of types.</listitem> 30 <listitem>Boost.Variant provides <emphasis>compile-time</emphasis> 31 checked visitation of its content. (By contrast, the current version 32 of Boost.Any provides no visitation mechanism at all; but even if it 33 did, it would need to be checked at run-time.)</listitem> 34 <listitem>Boost.Variant enables generic visitation of its content. 35 (Even if Boost.Any did provide a visitation mechanism, it would enable 36 visitation only of explicitly-specified types.)</listitem> 37 <listitem>Boost.Variant offers an efficient, stack-based storage scheme 38 (avoiding the overhead of dynamic allocation).</listitem> 39 </itemizedlist> 40 41 </para> 42 43 <para>Of course, Boost.Any has several advantages over Boost.Variant, 44 such as: 45 46 <itemizedlist> 47 <listitem>Boost.Any, as its name implies, allows virtually any type for 48 its content, providing great flexibility.</listitem> 49 <listitem>Boost.Any provides the no-throw guarantee of exception safety 50 for its swap operation.</listitem> 51 <listitem>Boost.Any makes little use of template metaprogramming 52 techniques (avoiding potentially hard-to-read error messages and 53 significant compile-time processor and memory demands).</listitem> 54 </itemizedlist> 55 56 </para> 57 58</section> 59 60<section> 61 <title>Portability</title> 62 63 <para>The library aims for 100% ANSI/ISO C++ conformance. However, this is 64 strictly impossible due to the inherently non-portable nature of the 65 <libraryname>Type Traits</libraryname> library's 66 <code><classname>type_with_alignment</classname></code> facility. In 67 practice though, no compilers or platforms have been discovered where this 68 reliance on undefined behavior has been an issue.</para> 69 70 <para>Additionally, significant effort has been expended to ensure proper 71 functioning despite various compiler bugs and other conformance problems. 72 To date the library testsuite has 73 been compiled and tested successfully on at least the following compilers 74 for basic and advanced functionality: 75 76 <informaltable> 77 <tgroup cols="5"> 78 <thead> 79 <row> 80 <entry></entry> 81 <entry>Basic</entry> 82 <entry> 83 <code>variant<T&></code> 84 </entry> 85 <entry> 86 <link linkend="variant.tutorial.over-sequence"> 87 <code>make_variant_over</code> 88 </link> 89 </entry> 90 <entry> 91 <link linkend="variant.tutorial.recursive.recursive-variant"> 92 <code>make_recursive_variant</code> 93 </link> 94 </entry> 95 </row> 96 </thead> 97 <tbody> 98 <row> 99 <entry>Borland C++ 5.5.1 and 5.6.4</entry> 100 <entry>X</entry> 101 <entry>X</entry> 102 <entry></entry> 103 <entry></entry> 104 </row> 105 <row> 106 <entry>Comeau C++ 4.3.0</entry> 107 <entry>X</entry> 108 <entry>X</entry> 109 <entry>X</entry> 110 <entry>X</entry> 111 </row> 112 <row> 113 <entry>GNU GCC 3.3.1</entry> 114 <entry>X</entry> 115 <entry>X</entry> 116 <entry>X</entry> 117 <entry>X</entry> 118 </row> 119 <row> 120 <entry>GNU GCC 2.95.3</entry> 121 <entry>X</entry> 122 <entry>X</entry> 123 <entry></entry> 124 <entry>X</entry> 125 </row> 126 <row> 127 <entry>Intel C++ 7.0</entry> 128 <entry>X</entry> 129 <entry></entry> 130 <entry>X</entry> 131 <entry>X</entry> 132 </row> 133 <row> 134 <entry>Metrowerks CodeWarrior 8.3</entry> 135 <entry>X</entry> 136 <entry></entry> 137 <entry>X</entry> 138 <entry>X</entry> 139 </row> 140 <row> 141 <entry>Microsoft Visual C++ 7.1</entry> 142 <entry>X</entry> 143 <entry>X</entry> 144 <entry>X</entry> 145 <entry>X</entry> 146 </row> 147 <row> 148 <entry>Microsoft Visual C++ 6 SP5 and 7</entry> 149 <entry>X</entry> 150 <entry></entry> 151 <entry></entry> 152 <entry></entry> 153 </row> 154 </tbody> 155 </tgroup> 156 </informaltable> 157 158 </para> 159 160 <para>Finally, the current state of the testsuite in CVS may be found on the 161 <ulink url="http://boost.sourceforge.net/regression-logs">Test Summary</ulink> 162 page. Please note, however, that this page reports on day-to-day changes 163 to inter-release code found in the Boost CVS and thus likely does not 164 match the state of code found in Boost releases.</para> 165 166</section> 167 168<section id="variant.troubleshooting"> 169 <title>Troubleshooting</title> 170 171<para>Due to the heavy use of templates in the implementation of 172 <code>variant</code>, it is not uncommon when compiling to encounter 173 problems related to template instantiaton depth, compiler memory, etc. This 174 section attempts to provide advice to common problems experienced on several 175 popular compilers.</para> 176 177<para>(This section is still in progress, with additional advice/feedback 178 welcome. Please post to the Boost-Users list with any useful experiences you 179 may have.)</para> 180 181 <section id="variant.troubleshooting.template-depth"> 182 <title>"Template instantiation depth exceeds maximum"</title> 183 184 <section id="variant.troubleshooting.template-depth.gcc"> 185 <title>GNU GCC</title> 186 <para>The compiler option 187 <code>-ftemplate-depth-<emphasis>NN</emphasis></code> can increase the 188 maximum allowed instantiation depth. (Try 189 <code>-ftemplate-depth-50</code>.)</para> 190 </section> 191 </section> 192 193 <section id="variant.troubleshooting.compiler-memory"> 194 <title>"Internal heap limit reached"</title> 195 196 <section id="variant.troubleshooting.compiler-memory.msvc"> 197 <title>Microsoft Visual C++</title> 198 <para>The compiler option <code>/Zm<emphasis>NNN</emphasis></code> can 199 increase the memory allocation limit. The <code>NNN</code> is a 200 scaling percentage (i.e., <code>100</code> denotes the default limit). 201 (Try <code>/Zm200</code>.)</para> 202 </section> 203 </section> 204 205</section> 206 207<section id="variant.ack"> 208 <title>Acknowledgments</title> 209 210<para>Eric Friedman and Itay Maman designed the initial submission; Eric was 211 the primary implementer.</para> 212 213<para>Eric is also the library maintainer and has expanded upon the initial 214 submission -- adding 215 <code><classname>make_recursive_variant</classname></code>, 216 <code><classname>make_variant_over</classname></code>, support for 217 reference content, etc.</para> 218 219<para>Andrei Alexandrescu's work in 220 [<link linkend="variant.refs.ale01a">Ale01a</link>] 221and 222 [<link linkend="variant.refs.ale02">Ale02</link>] 223inspired the library's design.</para> 224 225<para>Jeff Garland was the formal review manager.</para> 226 227<para>Douglas Gregor, 228Dave Abrahams, 229Anthony Williams, 230Fernando Cacciola, 231Joel de Guzman, 232Dirk Schreib, 233Brad King, 234Giovanni Bajo, 235Eugene Gladyshev, 236and others provided helpful feedback and suggestions to refine the semantics, 237interface, and implementation of the library.</para> 238 239</section> 240 241</section> 242