]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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>] | |
221 | and | |
222 | [<link linkend="variant.refs.ale02">Ale02</link>] | |
223 | inspired the library's design.</para> | |
224 | ||
225 | <para>Jeff Garland was the formal review manager.</para> | |
226 | ||
227 | <para>Douglas Gregor, | |
228 | Dave Abrahams, | |
229 | Anthony Williams, | |
230 | Fernando Cacciola, | |
231 | Joel de Guzman, | |
232 | Dirk Schreib, | |
233 | Brad King, | |
234 | Giovanni Bajo, | |
235 | Eugene Gladyshev, | |
236 | and others provided helpful feedback and suggestions to refine the semantics, | |
237 | interface, and implementation of the library.</para> | |
238 | ||
239 | </section> | |
240 | ||
241 | </section> |