Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/variant.html @ 46

Last change on this file since 46 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 12.8 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 20. Boost.Variant</title>
5<link rel="stylesheet" href="boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="libraries.html" title="Part I. The Boost C++ Libraries (BoostBook Subset)">
9<link rel="prev" href="typeof/ackn.html" title=" Acknowledgements">
10<link rel="next" href="variant/tutorial.html" title="Tutorial">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
15<td align="center"><a href="../../index.htm">Home</a></td>
16<td align="center"><a href="../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../people/people.htm">People</a></td>
18<td align="center"><a href="../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="typeof/ackn.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="variant/tutorial.html"><img src="images/next.png" alt="Next"></a>
24</div>
25<div class="chapter" lang="en">
26<div class="titlepage"><div>
27<div><h2 class="title">
28<a name="variant"></a>Chapter 20. Boost.Variant</h2></div>
29<div><div class="author"><h3 class="author">
30<span class="firstname">Eric</span> <span class="surname">Friedman</span>
31</h3></div></div>
32<div><div class="author"><h3 class="author">
33<span class="firstname">Itay</span> <span class="surname">Maman</span>
34</h3></div></div>
35<div><p class="copyright">Copyright © 2002, 2003 Eric Friedman, Itay Maman</p></div>
36<div><div class="legalnotice">
37<a name="id1940572"></a><p>Permission to copy, use, sell and distribute this software
38    is granted provided this copyright notice appears in all copies.
39    Permission to modify the code and to distribute modified code is
40    granted provided this copyright notice appears in all copies, and
41    a notice that the code was modified is included with the copyright
42    notice.</p>
43<p> This software is provided "as is" without express or
44    implied warranty, and with no claim as to its suitability for any
45    purpose.</p>
46</div></div>
47</div></div>
48<div class="toc">
49<p><b>Table of Contents</b></p>
50<dl>
51<dt><span class="section"><a href="variant.html#variant.intro">Introduction</a></span></dt>
52<dd><dl>
53<dt><span class="section"><a href="variant.html#variant.abstract">Abstract</a></span></dt>
54<dt><span class="section"><a href="variant.html#variant.motivation">Motivation</a></span></dt>
55</dl></dd>
56<dt><span class="section"><a href="variant/tutorial.html">Tutorial</a></span></dt>
57<dd><dl>
58<dt><span class="section"><a href="variant/tutorial.html#variant.tutorial.basic">Basic Usage</a></span></dt>
59<dt><span class="section"><a href="variant/tutorial.html#variant.tutorial.advanced">Advanced Topics</a></span></dt>
60</dl></dd>
61<dt><span class="section"><a href="variant/reference.html">Reference</a></span></dt>
62<dd><dl>
63<dt><span class="section"><a href="variant/reference.html#variant.concepts">Concepts</a></span></dt>
64<dt><span class="section"><a href="variant/reference.html#header.boost.variant.hpp">Header &lt;boost/variant.hpp&gt;</a></span></dt>
65<dt><span class="section"><a href="variant/reference.html#header.boost.variant.variant_fwd.hpp">Header &lt;boost/variant/variant_fwd.hpp&gt;</a></span></dt>
66<dt><span class="section"><a href="variant/reference.html#header.boost.variant.variant.hpp">Header &lt;boost/variant/variant.hpp&gt;</a></span></dt>
67<dt><span class="section"><a href="variant/reference.html#header.boost.variant.recursive_variant.hpp">Header &lt;boost/variant/recursive_variant.hpp&gt;</a></span></dt>
68<dt><span class="section"><a href="variant/reference.html#header.boost.variant.recursive_wrapper.hpp">Header &lt;boost/variant/recursive_wrapper.hpp&gt;</a></span></dt>
69<dt><span class="section"><a href="variant/reference.html#header.boost.variant.apply_visitor.hpp">Header &lt;boost/variant/apply_visitor.hpp&gt;</a></span></dt>
70<dt><span class="section"><a href="variant/reference.html#header.boost.variant.get.hpp">Header &lt;boost/variant/get.hpp&gt;</a></span></dt>
71<dt><span class="section"><a href="variant/reference.html#header.boost.variant.bad_visit.hpp">Header &lt;boost/variant/bad_visit.hpp&gt;</a></span></dt>
72<dt><span class="section"><a href="variant/reference.html#header.boost.variant.static_visitor.hpp">Header &lt;boost/variant/static_visitor.hpp&gt;</a></span></dt>
73<dt><span class="section"><a href="variant/reference.html#header.boost.variant.visitor_ptr.hpp">Header &lt;boost/variant/visitor_ptr.hpp&gt;</a></span></dt>
74</dl></dd>
75<dt><span class="section"><a href="variant/design.html">Design Overview</a></span></dt>
76<dd><dl><dt><span class="section"><a href="variant/design.html#variant.design.never-empty">"Never-Empty" Guarantee</a></span></dt></dl></dd>
77<dt><span class="section"><a href="variant/misc.html">Miscellaneous Notes</a></span></dt>
78<dd><dl>
79<dt><span class="section"><a href="variant/misc.html#variant.versus-any">Boost.Variant vs. Boost.Any</a></span></dt>
80<dt><span class="section"><a href="variant/misc.html#id1952714">Portability</a></span></dt>
81<dt><span class="section"><a href="variant/misc.html#variant.troubleshooting">Troubleshooting</a></span></dt>
82<dt><span class="section"><a href="variant/misc.html#variant.ack">Acknowledgments</a></span></dt>
83</dl></dd>
84<dt><span class="section"><a href="variant/refs.html">References</a></span></dt>
85</dl>
86</div>
87<div class="section" lang="en">
88<div class="titlepage"><div><div><h2 class="title" style="clear: both">
89<a name="variant.intro"></a>Introduction</h2></div></div></div>
90<div class="toc"><dl>
91<dt><span class="section"><a href="variant.html#variant.abstract">Abstract</a></span></dt>
92<dt><span class="section"><a href="variant.html#variant.motivation">Motivation</a></span></dt>
93</dl></div>
94<div class="section" lang="en">
95<div class="titlepage"><div><div><h3 class="title">
96<a name="variant.abstract"></a>Abstract</h3></div></div></div>
97<p>The <code class="computeroutput">variant</code> class template is a safe, generic, stack-based
98discriminated union container, offering a simple solution for manipulating an
99object from a heterogeneous set of types in a uniform manner. Whereas
100standard containers such as <code class="computeroutput">std::vector</code> may be thought of as
101"<span class="bold"><strong>multi-value, single type</strong></span>,"
102<code class="computeroutput">variant</code> is "<span class="bold"><strong>multi-type,
103single value</strong></span>."</p>
104<p>Notable features of <code class="computeroutput"><a href="boost/variant.html" title="Class template variant">boost::variant</a></code>
105include:</p>
106<div class="itemizedlist"><ul type="disc">
107<li>Full value semantics, including adherence to standard
108    overload resolution rules for conversion operations.</li>
109<li>Compile-time type-safe value visitation via
110    <code class="computeroutput"><a href="boost/apply_visitor.html" title="Function apply_visitor">boost::apply_visitor</a></code>.</li>
111<li>Run-time checked explicit value retrieval via
112    <code class="computeroutput"><a href="boost/get.html" title="Function get">boost::get</a></code>.</li>
113<li>Support for recursive variant types via both
114    <code class="computeroutput"><a href="boost/make_recursive_variant.html" title="Class template make_recursive_variant">boost::make_recursive_variant</a></code> and
115    <code class="computeroutput"><a href="boost/recursive_wrapper.html" title="Class template recursive_wrapper">boost::recursive_wrapper</a></code>.</li>
116<li>Efficient implementation -- stack-based when possible (see
117    <a href="variant/design.html#variant.design.never-empty" title='"Never-Empty" Guarantee'>the section called &#8220;"Never-Empty" Guarantee&#8221;</a> for more details).</li>
118</ul></div>
119</div>
120<div class="section" lang="en">
121<div class="titlepage"><div><div><h3 class="title">
122<a name="variant.motivation"></a>Motivation</h3></div></div></div>
123<div class="toc"><dl>
124<dt><span class="section"><a href="variant.html#variant.motivation.problem">Problem</a></span></dt>
125<dt><span class="section"><a href="variant.html#variant.motivation.solution">Solution: A Motivating Example</a></span></dt>
126</dl></div>
127<div class="section" lang="en">
128<div class="titlepage"><div><div><h4 class="title">
129<a name="variant.motivation.problem"></a>Problem</h4></div></div></div>
130<p>Many times, during the development of a C++ program, the
131programmer finds himself in need of manipulating several distinct
132types in a uniform manner. Indeed, C++ features direct language
133support for such types through its <code class="computeroutput">union</code> 
134keyword:</p>
135<pre class="programlisting">union { int i; double d; } u;
136u.d = 3.14;
137u.i = 3; // overwrites u.d (OK: u.d is a POD type)</pre>
138<p>C++'s <code class="computeroutput">union</code> construct, however, is nearly
139useless in an object-oriented environment. The construct entered
140the language primarily as a means for preserving compatibility with
141C, which supports only POD (Plain Old Data) types, and so does not
142accept types exhibiting non-trivial construction or
143destruction:</p>
144<pre class="programlisting">union {
145  int i;
146  std::string s; // illegal: std::string is not a POD type!
147} u;</pre>
148<p>Clearly another approach is required. Typical solutions
149feature the dynamic-allocation of objects, which are subsequently
150manipulated through a common base type (often a virtual base class
151    [<a href="variant/refs.html#variant.refs.hen01">Hen01</a>]
152or, more dangerously, a <code class="computeroutput">void*</code>). Objects of
153concrete type may be then retrieved by way of a polymorphic downcast
154construct (e.g., <code class="computeroutput">dynamic_cast</code>,
155<code class="computeroutput"><a href="boost/any_cast.html" title="Function any_cast">boost::any_cast</a></code>, etc.).</p>
156<p>However, solutions of this sort are highly error-prone, due
157to the following:</p>
158<div class="itemizedlist"><ul type="disc">
159<li>
160<span class="emphasis"><em>Downcast errors cannot be detected at
161    compile-time.</em></span> Thus, incorrect usage of downcast
162    constructs will lead to bugs detectable only at run-time.</li>
163<li>
164<span class="emphasis"><em>Addition of new concrete types may be
165    ignored.</em></span> If a new concrete type is added to the
166    hierarchy, existing downcast code will continue to work as-is,
167    wholly ignoring the new type. Consequently, the programmer must
168    manually locate and modify code at numerous locations, which often
169    results in run-time errors that are difficult to find.</li>
170</ul></div>
171<p>Furthermore, even when properly implemented, these solutions tend
172to incur a relatively significant abstraction penalty due to the use of
173the heap, virtual function calls, and polymorphic downcasts.</p>
174</div>
175<div class="section" lang="en">
176<div class="titlepage"><div><div><h4 class="title">
177<a name="variant.motivation.solution"></a>Solution: A Motivating Example</h4></div></div></div>
178<p>The <code class="computeroutput"><a href="boost/variant.html" title="Class template variant">boost::variant</a></code> class template
179addresses these issues in a safe, straightforward, and efficient manner. The
180following example demonstrates how the class can be used:</p>
181<pre class="programlisting">#include "boost/variant.hpp"
182#include &lt;iostream&gt;
183
184class my_visitor : public <code class="computeroutput"><a href="boost/static_visitor.html" title="Class template static_visitor">boost::static_visitor</a></code>&lt;int&gt;
185{
186public:
187    int operator()(int i) const
188    {
189        return i;
190    }
191   
192    int operator()(const <code class="computeroutput">std::string</code> &amp; str) const
193    {
194        return str.length();
195    }
196};
197
198int main()
199{
200    <code class="computeroutput"><a href="boost/variant.html" title="Class template variant">boost::variant</a></code>&lt; int, std::string &gt; u("hello world");
201    std::cout &lt;&lt; u; // output: hello world
202
203    int result = <code class="computeroutput"><a href="boost/apply_visitor.html" title="Function apply_visitor">boost::apply_visitor</a></code>( my_visitor(), u );
204    std::cout &lt;&lt; result; // output: 11 (i.e., length of "hello world")
205}
206</pre>
207</div>
208</div>
209</div>
210</div>
211<table width="100%"><tr>
212<td align="left"></td>
213<td align="right"><small></small></td>
214</tr></table>
215<hr>
216<div class="spirit-nav">
217<a accesskey="p" href="typeof/ackn.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="variant/tutorial.html"><img src="images/next.png" alt="Next"></a>
218</div>
219</body>
220</html>
Note: See TracBrowser for help on using the repository browser.