mirror of
https://github.com/boostorg/variant.git
synced 2026-01-29 08:02:18 +00:00
119 lines
6.5 KiB
HTML
119 lines
6.5 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="keywords" content="Variant, design pattern, generic programming, C++">
|
|
<link rel="stylesheet" type="text/css" href="styles.css">
|
|
<title>Boost::variant</title>
|
|
</head>
|
|
<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080">
|
|
<table summary="header" border="0" cellpadding="2" cellspacing="0" width="100%">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3>
|
|
<A HREF="../../index.htm"><img src="../../c++boost.gif" alt="C++ Boost" width="277" height="86" BORDER="0">
|
|
</A>
|
|
</h3>
|
|
</td>
|
|
<td valign="top">
|
|
<h1 align="center"><a href="index.html">boost::variant</a></h1>
|
|
<h2 align="center">
|
|
Overview</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<p>
|
|
<UL>
|
|
<LI>
|
|
<a href="#Introduction">Introduction</a></LI>
|
|
<LI>
|
|
<a href="#Motivation">Motivation</a></LI>
|
|
</UL>
|
|
<hr>
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
<p>The <code>variant</code> template class offers a simple, type-safe solution for
|
|
manipulating an object from an heterogeneous set of types in a uniform
|
|
manner. Whereas standard containers such as <code>std::vector</code> may be
|
|
thought of as "<b>multi-value, single type</b>," <code>variant</code> is "<b>multi-type,
|
|
single value</b>." This reduces code duplication and enhances
|
|
maintainability.</p>
|
|
<p>Specific features of <CODE>boost::variant</CODE> include:</p>
|
|
<UL>
|
|
<LI>
|
|
Full value semantics, including adherence to standard overload resolution
|
|
rules.</LI>
|
|
<LI>
|
|
Strong exception-safety guarantee for all operations.</LI>
|
|
<LI>
|
|
Compile-time type-safe value visitation.</LI>
|
|
<LI>
|
|
Run-time checked explicit value extraction.</LI>
|
|
<LI>
|
|
Support for incomplete types and recursive variant types.</LI>
|
|
<LI>
|
|
Efficient, stack-based implementation.</LI>
|
|
</UL>
|
|
<hr>
|
|
<h2><a name="Motivation">Motivation</a></h2>
|
|
<p>Many times, during the development of a C++ program, the programmer finds
|
|
himself in need of manipulating several distinct types in a uniform manner.
|
|
Indeed, C++ features direct language support for such types through
|
|
its <code>union</code> keyword:
|
|
</p>
|
|
<blockquote>
|
|
<pre>union { int i; double d; } u;
|
|
u.d = 3.14;
|
|
u.i = 3; // overwrites u.d (OK: u.d is a POD type)</pre>
|
|
</blockquote>
|
|
<p>C++'s <code>union</code> construct, however, is nearly useless in an
|
|
object-oriented environment. The construct entered the language primarily as a
|
|
means for preserving compatibility with C, which supports only POD types, and
|
|
so does not accept types exhibiting non-trivial construction or destruction:</p>
|
|
<blockquote>
|
|
<pre>union {
|
|
int i;
|
|
std::string s; // illegal: std::string is not a POD type!
|
|
};</pre>
|
|
</blockquote>
|
|
<p>Clearly another approach is required. Typical solutions feature the
|
|
dynamic-allocation of objects, which are subsequently manipulated through a
|
|
common base type (often a virtual base class [<a href="credits.html#bib-hen01">Hen01</a>] or,
|
|
more dangerously, a <code>void*</code>). Objects of concrete type may be then
|
|
retrieved by way of a polymorphic downcast construct (e.g., <code>dynamic_cast</code>).</p>
|
|
<p>However, solutions of this sort are highly error-prone, due to the following:</p>
|
|
<ul>
|
|
<li>
|
|
<i>Downcast errors cannot be detected at compile-time</i>. Thus, incorrect
|
|
usage of downcast constructs will lead to bugs detectable only at run-time.</li>
|
|
<li>
|
|
<i>Addition of new concrete types may be ignored</i>. If a new concrete type is
|
|
added to the hierarchy, existing downcast code will continue to work as-is,
|
|
wholly ignoring the new type. Consequently, the programmer must manually locate
|
|
and modify code at numerous locations, which often results in run-time errors
|
|
that are difficult to find.</li>
|
|
</ul>
|
|
<p>Furthermore, even when properly implemented, these solutions incur a relatively
|
|
significant abstraction penalty due to the use of the free store, virtual
|
|
function calls, and polymorphic downcasts.</p>
|
|
<p>The <code>variant</code> template class (inspired by Andrei Alexandrescu's class
|
|
of the same name described in [<a href="credits.html#bib-ale02">Ale02</a>]) is
|
|
an efficient, recursive-capable, bounded discriminated union value type capable
|
|
of containing both POD and non-POD value types. It supports direct
|
|
initialization from any type convertible to one of its bounded types or from a
|
|
source <code>variant</code> whose bounded types are each convertible to one of
|
|
the destination <code>variant</code>'s bounded types. As well, <code>variant</code>
|
|
supports both compile-time checked, type-safe <a href="reference.html#Visitation">visitation</a>
|
|
and explicit, run-time checked, type-safe <a href="reference.html#ValueExtraction">value
|
|
extraction</a>.</p>
|
|
<hr>
|
|
<p>Revised 13 February 2003</p>
|
|
<p><i>© Copyright Eric Friedman and Itay Maman 2002-2003. All rights reserved.</i></p>
|
|
<p>Permission to use, copy, modify, distribute and sell this software and its
|
|
documentation for any purpose is hereby granted without fee, provided that the
|
|
above copyright notice appear in all copies and that both that copyright notice
|
|
and this permission notice appear in supporting documentation. Eric Friedman
|
|
and Itay Maman make no representations about the suitability of this software
|
|
for any purpose. It is provided "as is" without express or implied
|
|
warranty.</p>
|