Added libs/mpl

[SVN r15384]
This commit is contained in:
Dave Abrahams committed 2002-09-16 19:25:33 +00:00
1 parent 6ec072c403
commit 01d61922bc
238 files changed
+15885

No files matched your search

+18
View File
@@ -0,0 +1,18 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="acknw">
<title>Acknowledgements</>
<para>
Following is a list of people who in one or another way contributed to the library development. The list is work in progress!
</>
<para>
David Abrahams, Emily Winch, Eric Friedman, Vesa Karvonen, Peter Dimov, Mat Marcus, Fernando Cacciola, Paul Mensonides, David B. Held, John Bandela, Arnaldur Gylfason, Hamish Mackenzie.
</>
<formalpara>
<title>Copyright on this document</>
<para>Copyright © 2002 Aleksey Gurtovoy, David Abrahams and Emily Winch.</>
</>
</section>
+130
View File
@@ -0,0 +1,130 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="applyif">
<title>apply_if</>
<para>
In run-time &Cxx;, it is guaranteed that when we reach an <literal>if</> statement, only one branch will be executed. Executing the branch for which the result is not required would be unnecessary and inefficient. More importantly, frequently the non-required branch is invalid, and executing it would cause an error. For instance, the following code would be badly broken if both branches of the statement were evaluated:
</>
<programlisting>
<![CDATA[
void fun(giraffe* g)
{
if (g)
cout << g->name();
else
cout << "no giraffe";
}
]]>
</>
<para>
In compile-time world, things are different. Which parameters to <literal>if_</> template are instantiated is determined by the form of each template parameter and the corresponding language rules (<citation><xref linkend="ref.ISO98"></>, section 14.7.1), not by the value of the compile-time expression being switched on. That means that if, in attempt to process a particular <literal>if_</> construct, the compiler determines that one of its <quote>branch</> template parameters is ill-formed, it will issue a diagnostics even if the value of compile-time expression would lead to <quote>choosing</> the other, valid parameter type.
</>
<para>
To clarify what we just said, here is a broken first attempt at writing a <literal>pointed_type</> metafunction, that when instantiated for a <literal>T</> that is either a plain pointer or a smart pointer, <quote>returns</> the pointed type:
</>
<programlisting>
<![CDATA[
template< typename T >
struct pointed_type
{
typedef typename mpl::if_<
boost::is_pointer<T>
, typename boost::remove_pointer<T>::type
, typename T::element_type // #1
>::type type;
};
typedef pointed_type< std::auto_ptr<int> >::type int_ptr; // ok
typedef pointed_type<char*>::type char_ptr; // error in line #1!
]]>
</>
<para>
If we try to compile the above, we will get something like this:
</>
<programlisting>
Error: name followed by "::" must be a class or namespace name
</>
<para>
because the expression <literal>typename T::element_type</> is not valid in case of <literal>T == char*</>.
</>
<para>
Here's what we need to do to make <literal>pointed_type</> work for plain pointers:
<footnote><para>
It would be easy to implement <literal>pointed_type</> using partial specialization to distinguish the case where <literal>T</> is a pointer. <literal>if_</> is used here to avoid creating a complicated example.
</></>
instead of instantiating our two potential results before passing them to <literal>if_</>, we need to write metafunctions that can be used to instantiate the results; then we can use <literal>if_</> to choose a metafunction, and only then should we use that function to get the result.
</>
<para>
<literal>boost::remove_pointer</> already is a metafunction. We just need to write an auxiliary function to return the <literal>element_type</> of a pointer type:
</>
<programlisting>
<![CDATA[
namespace aux {
template< typename T >
struct element_type
{
typedef typename T::element_type type;
};
}
]]>
</>
<para>
Now we can select the metafunction to call based on the result of <literal>boost::is_pointer</>, and then <emphasis>apply</> it to form the result:
</>
<programlisting>
<![CDATA[
template< typename T >
struct pointed_type
{
private:
// pick a metafunction
typedef typename mpl::if_<
boost::is_pointer<T>
, boost::remove_pointer<T>
, aux::element_type<T>
>::type func_; // #1
public:
// apply the metafunction
typedef typename func_::type type;
};
]]>
</>
<para>
The key knowledge that makes the above viable is that in line #1 the compiler is <emphasis>guaranteed</> not to instantiate <literal>boost::remove_pointer&lt;T&gt;</> and <literal>aux::element_type&lt;T&gt;</> templates, - even although they are passed as actual arguments to the <literal>if_</>.
</>
<para>
The described technique is so common in template metaprograms, that it makes sense to facilitate the selection of the nested <literal>type</> member by introducing a high level equivalent to <literal>if_</> that will do <literal>func_::type</> operation as a part of its invocation. The MPL provides such a template - it's called <literal>apply_if</>. Using it, we can re-write the above code as simply as:
</>
<programlisting>
[<![CDATA[
template< typename T >
struct pointed_type
{
typedef typename mpl::apply_if<
boost::is_pointer<T>
, boost::remove_pointer<T>
, aux::element_type<T>
>::type type;
};
]]>
</>
</section>
+55
View File
@@ -0,0 +1,55 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="applyif2">
<title>apply_if, part 2</>
<para>
Besides solving the <quote>making the code compile</> problem, the <literal>apply_if</> technique we've just learned can be also used to improve metaprogram efficiency.
</>
<para>
Suppose we want to define a high-level wrapper around <literal>boost::remove_pointer</> traits template, which will strip the pointer qualification conditionally. We will call it <literal>remove_pointer_if</>:
</>
<programlisting>
<![CDATA[
template<
typename Condition
, typename T
>
struct remove_pointer_if
{
typedef typename mpl::if_<
Condition
, typename boost::remove_pointer<T>::type
, T
>::type type;
};
]]>
</>
<para>
The above works the first time, but it's not the most optimal implementation. Similar to our previous examples, <literal>boost::remove_pointer&lt;T&gt;</> gets instantiated even if its result is never used. In the metaprogramming world compilation time is an important resource <citation><xref linkend="ref.Abr01"></>, and it is wasted by unnecessary template instantiations.
</>
<para>
Let's see what we need to substitute <literal>if_</> by <literal>apply_if</> here. We already have one metafunction to pass to <literal>apply_if</> - <literal>boost::remove_pointer&lt;T&gt;</>, but we need a second one, - let's call it <literal>f</>, - such as <literal>f&lt;T&gt;::type == T</>. We could write this one ourselves, but fortunately &MPL; already provides us with a template that matches this exact definition - it's called <literal>identity</>. Applying this knowledge, we get:
</>
<programlisting>
<![CDATA[
template<
typename Condition
, typename T
>
struct remove_pointer_if
{
typedef typename mpl::apply_if<
Condition
, boost::remove_pointer<T>
, mpl::identity<T>
>::type type;
};
]]>
</>
</section>
+2
View File
@@ -0,0 +1,2 @@
<articleinfo>
</articleinfo>
+69
View File
@@ -0,0 +1,69 @@
<bibliography id="bibliography">
<title>Bibliography</>
<biblioentry id="ref.Abr01">
<abbrev>Abr01</>
<authorgroup>
<author><firstname>David</><surname>Abrahams</></>
<author><firstname>Carlos Pinto</><surname>Coelho</></>
</>
<title><ulink url="http://users.rcn.com/abrahams/instantiation_speed/index.html">Effects of Metaprogramming Style on Compilation Time</></>
<date>2001</>
</biblioentry>
<biblioentry id="ref.Ale00">
<abbrev>Ale00</>
<author><firstname>Andrei</><surname>Alexandrescu</></>
<title><ulink url="http://www.cuj.com/experts/1810/alexandr.htm">On Conversions between Types and Values</></>
<publishername>C/C++ Users Journal</>
<date>October 2000</>
</biblioentry>
<biblioentry id="ref.BBL">
<abbrev>BBL</>
<title>Boost Bind library</>
<bibliomisc><ulink url="http://www.boost.org/libs/bind/bind.html"></></>
</biblioentry>
<biblioentry id="ref.ISO98">
<abbrev>ISO98</>
<title>ISO/IEC 14882:1998(E), Programming languages — C++</>
<orgname>ISO/IEC</>
<date>1998</>
</biblioentry>
<biblioentry id="ref.PRE">
<abbrev>PRE</>
<author><firstname>Vesa</><surname>Karvonen</></>
<title>Boost Preprocessor Metaprogramming library</>
<bibliomisc><ulink url="http://www.boost.org/libs/preprocessor/doc/"></></>
</biblioentry>
<biblioentry id="ref.TTL">
<abbrev>TTL</>
<title>Boost Type Traits library</>
<bibliomisc><ulink url="http://www.boost.org/libs/type_traits/"></></>
</biblioentry>
<biblioentry id="ref.SAL">
<abbrev>SAL</>
<title>Boost Static Assert library</>
<bibliomisc><ulink url="http://www.boost.org/libs/static_assert/static_assert.htm"></></>
</biblioentry>
<biblioentry id="ref.Vel95a">
<abbrev>Vel95a</>
<author><firstname>Todd</><surname>Veldhuizen</></>
<title><ulink url="http://osl.iu.edu/~tveldhui/papers/Template-Metaprograms/meta-art.html">Using C++ template metaprograms</></>
<biblioset relation='journal'>
<title>C++ Report</>
<publishername>SIGS Publications Inc.</>
<issn>1040-6042</>
</>
<volumenum>7</>
<issuenum>4</>
<pagenums>36-43</>
<date>May 1995</>
</biblioentry>
</bibliography>
+37
View File
@@ -0,0 +1,37 @@
<!doctype article public "-//OASIS//DTD DocBook V4.1//EN"
[
<!-- abbreviations -->
<!entity Boost "<literal>Boost</>">
<!entity Cxx "C++">
<!entity C "C">
<!entity MPL "MPL">
<!entity BMPL "Boost Metaprogramming Library">
<!entity mdat "metadata">
<!entity mping "metaprogramming">
<!entity mfn "metafunction">
<!entity unspec "/*unspecified*/">
<!-- physical entities -->
<!entity articleinfo SYSTEM "articleinfo.sgml">
<!entity preface SYSTEM "preface.sgml">
<!entity tutorial SYSTEM "tutorial.sgml">
<!entity metafunctions SYSTEM "metafunctions.sgml">
<!entity if SYSTEM "if.sgml">
<!entity applyif SYSTEM "apply_if.sgml">
<!entity applyif2 SYSTEM "apply_if2.sgml">
<!entity technical SYSTEM "technical.sgml">
<!entity acknw SYSTEM "acknw.sgml">
<!entity bibliography SYSTEM "bibliography.sgml">
]>
<article>
<title>The Boost &MPL; Library</>
&articleinfo;
&preface;
&tutorial;
&technical;
&acknw;
&bibliography;
</article>
+58
View File
@@ -0,0 +1,58 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="howtos">
<title>How-to's</>
<!-- ||||||||||||||||||||||||||||| subsection -->
<section id="howtos.search">
<title>How to find something in a sequence?</>
<para>
If you just want to make an enquiry if a sequence contains a type with certain properties, you can do it like that:
</>
<programlisting>
<![CDATA[
typedef mpl::list5<> types;
typedef mpl::contains<types,int>::type res; // res::value == true
]]>
</>
<para>
A predicate version of <literal>contains</> algorithm is spelled <literal>any</>:
</>
<programlisting>
<![CDATA[
// find if any type in 'types' is derived from 'my'
typedef mpl::any<types, mpl::is_convertible<_1,my> >::type res;
]]>
</>
<para>
Now, if you really want to find type in a sequence - that is, to obtain an iterator on its position, when the should-be-known-from-STL <literal>find</> and <literal>find_if</> algorithms are most probably exactly what you need:
</>
<programlisting>
<![CDATA[
// find if any type in 'types' is derived from 'my'
typedef mpl::find<types, int >::type iterator;
typedef mpl::find_if<types, mpl::is_convertible<_1,my> >::type iterator;
]]>
</>
<para>
Unless, of course, the sequence is sorted. If it is, then the other known names come into the play - <literal>lower_bound</>, <literal>upper_bound</>, or <literal>binary_search</>:
</>
<programlisting>
<![CDATA[
// find if any type in 'types' is derived from 'my'
typedef mpl::lower_bound<types, mpl::int_c<5>, mpl::less<_1,_2> >::type iterator;
typedef mpl::upper_bound<types, mpl::int_c<5>, mpl::less<_1,_2> >::type iterator;
typedef mpl::binary_search<types, mpl::int_c<5>, mpl::less<_1,_2> >::type iterator;
]]>
</>
</section>
</section>
+66
View File
@@ -0,0 +1,66 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="if">
<title>Compile-time if</>
<para>
The most interesting template metaprograms often contain a lot of decision-making code. Some of conditional decisions/behavior can be handled directly by (partial) class template specialization or function overloading <citation><xref linkend="ref.Vel95a"></>, <citation><xref linkend="ref.Ale00"></>, but in general there is a need for a standalone library primitive that would allow one to choose between two types basing on a compile-time expression. In <literal>boost::mpl</> such primitive is called <literal>if_</>:
</>
<programlisting>
<![CDATA[
template< typename T >
struct heap_holder
{
// ...
private:
boost::scoped_ptr<T> m_object;
};
template< typename T >
struct stack_holder
{
// ...
private:
T m_object;
};
template< typename T >
struct can_be_on_stack
: mpl::bool_c< (sizeof(T) <= sizeof(double)) >
{
};
// use 'if_' to choose where to store 'T' member
template< typename T >
struct lightweight
: private mpl::if_<
can_be_on_stack<T>
, stack_holder<T>
, heap_holder<T>
>::type
{
// ...
};
]]>
</>
<para>
Note that the first template parameter of the <literal>if_</> template is a type that should be a model of Integral Constant concept. The library also provides a less generic but sometimes more convenient form that accepts a condition in form of non-type <literal>bool</> template parameter:
</>
<programlisting>
<![CDATA[
template< typename T >
struct lightweight
: private mpl::if_c<
(sizeof(T) <= sizeof(double))
, stack_holder<T>
, heap_holder<T>
>::type
{
// ...
};
]]>
</>
</section>
+30
View File
@@ -0,0 +1,30 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="lambda">
<title>Lambda facility</>
<para>
<firstterm>Lambda expressions</> is a way of inline meta-function composition.
building more complex, more interesting functions from the existing ones. The simplest case of function composition is an operation of taking the result from one function (<literal>g</>) and using that as the argument to another function (<literal>f</>) - <literal>f(g(x))</>. [Talk about run-time &Cxx; facilities to do function composition in &Cxx; - SGI STL <literal>compose1</>/<literal>compose2</>, Boost Compose library, Boost Bind library]
</>
<para>
The library provide support for several styles of function composition. The facilities differ in portability, implementation complexity, readability, and performance characteristics.
</>
<!-- ||||||||||||||||||||||||||||| subsection -->
<section id="bind.compose">
<title>compose</>
<programlisting>
<![CDATA[
using mpl::placeholders;
typedef mpl::bind< mpl::make_f2<boost::is_same>,int,_2 > is_int;
typedef mpl::bind< add_pointer,mpl::bind<add_const,_1> > add_const_pointer;
]]>
</>
</section>
</section>
+37
View File
@@ -0,0 +1,37 @@
<section id="metafunctions">
<title>Metafunctions</>
<para>
In &MPL;, the metaprogramming equivalent of a function is a <firstterm>class template</> containing a nested <literal>typedef</> member aptly named <quote>type</>:
</>
<programlisting>
<![CDATA[
// on the face of it, not very useful
template< typename T >
struct identity
{
typedef T type;
};
// perhaps more useful
template< typename T >
struct result_type
{
typedef typename T::result_type type;
};
]]>
</>
<para>
<quote>Invoking</> a metafunction is as simple as instantiating the class template with particular template parameters (metafunction <quote>arguments</>) and accessing the result through the nested <literal>type</> member:
</>
<programlisting>
<![CDATA[
typedef identity<int>::type t1; // t1 == int
typedef result_type< std::unary_function<int,bool> >::type t2; // t2 == bool
]]>
</>
</section>
+49
View File
@@ -0,0 +1,49 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="preface">
<title>Preface</>
<para>The &MPL; library is a &Cxx; template metaprogramming framework of compile-time algorithms, sequences and metafunction classes. The two main documentation sources for the library is <quote>the MPL paper</>, and the library's reference documentation. If you haven't heard about the MPL before, we suggest you to start with the paper, and then move on to the reference documentation and the information in this document.
</>
<itemizedlist mark="box">
<listitem><simpara>
A. Gurtovoy, D. Abrahams, <ulink url="./paper/html/index.html">The Boost C++ Metaprogramming Library</>, March 2002 | [<ulink url="./paper/mpl_paper.html">as single .html</>]</></listitem>
<listitem>
<ulink url="./ref/Table_of_Content.html">Reference documentation</>
<orderedlist>
<listitem><simpara><ulink url="./ref/Sequences.html">Sequences</></></>
<listitem><simpara><ulink url="./ref/Iterators.html">Iterators</></></>
<listitem><simpara><ulink url="./ref/Algorithms.html">Algorithms</></></>
<listitem><simpara><ulink url="./ref/Metafunctions.html">Metafunctions</></></>
<listitem><simpara><ulink url="./ref/Categorized_index.html">Categorized index</></></>
</orderedlist>
</listitem>
</itemizedlist>
</section>
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="source">
<title>Sources</>
<para>
The latest library sources are available from:
</>
<itemizedlist mark="box">
<listitem><simpara>The <ulink url="http://www.boost.org/more/download.html#CVS">boost CVS</>, <literal>mpl_v2</> branch (<literal>cvs update -P -rmpl_v2 boost/mpl boost/type_traits libs/mpl</>)</></>
<listitem><simpara>From here - <ulink url="http://www.mywikinet.com/mpl/mpl_23_jul_02.zip"></></></>
</itemizedlist>
<para>
The library also requires the latest version of Boost Preprocessor library, that can be also obtained from <ulink url="http://www.boost.org/more/download.html#CVS">boost CVS</> or from here - <ulink url="http://www.mywikinet.com/mpl/preprocessor_19_jul_02.zip"></>.
</>
<para>A full archive that contains the library itself + all its dependencies - and therefore can be installed over a clean <ulink url="http://boost.sourceforge.net/release/boost_1_28_0.zip">Boost 1.28 distribution</> - is available from here - <ulink url="http://www.mywikinet.com/mpl/mpl_23_jul_02_full.zip"></>.
</>
</section>
+30
View File
@@ -0,0 +1,30 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="sequences">
<title>Working with type sequences</>
<para>
If we were to design a generative container library, our first attempt could be something like this:
</>
<programlisting>
<![CDATA[
namespace ctl { // Container Template Library
template<
typename T
, typename Features
>
class container
{
// ...
};
} // namespace ctl
]]>
</>
<para>
Here, <literal>container</> template is a single generative interface to all the , and we would like to pass to a possibly numerous features of a container as a single type.
</>
</section>
+52
View File
@@ -0,0 +1,52 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="technical">
<title>Technical details</>
<!-- ||||||||||||||||||||||||||||| subsection -->
<section id="details.headers">
<title>Physical structure</>
<para>
The library provides you with a fine-grained header structure with one header per public component (class/function template), with the header named after the component; for example, <literal>boost::mpl::apply&lt;&gt;</> template is defined in the header <literal>boost/mpl/apply.hpp</>. This scheme both ensures that you don't pay for what you don't use in terms of compilation time/header dependencies, and frees you from memorizing/looking up header/component correspondence. Several composite headers for the entities that are likely to be used together (e.g. logical operations - <literal>logical_or</>, <literal>logical_and</>, etc.) are also provided. It allows one to avoid the burden of spelling many <literal>#include</> directives in programs that make an intensive use of the library facilities.
<footnote id="note.headers"><para>The Boost Preprocessor library <citation><xref linkend="ref.PRE"></> exposes a very similar physical organization; in fact, the libraries even share the common subdirectory naming (<literal>mpl/arithmetic</> <-> <literal>preprocessor/arithmetic</>, <literal>mpl/comparison</> <-> <literal>preprocessor/comparison</>, etc.).</></>
</>
</section>
<!-- ||||||||||||||||||||||||||||| subsection -->
<section id="details.depend">
<title>Dependencies</>
<para>
Besides <literal>boost/config.hpp</> header, the MPL heavily depends on two other Boost libraries - the Boost Preprocessor library <citation><xref linkend="ref.PRE"></>, and the Type Traits library <citation><xref linkend="ref.TTL"></>. These dependencies are essential and cannot be eliminated. In addition to those, the <literal>boost/mpl/assert_is_same.hpp</> header depends on Boost Static Assert library <citation><xref linkend="ref.SAL"></>. The library tests and examples may depend on some additional Boost libraries, e.g. Boost Bind <citation><xref linkend="ref.BBL"></>; you don't have to have those unless you are interested in actually compiling the tests/examples (probably you are, though).
</>
</section>
<!-- ||||||||||||||||||||||||||||| subsection -->
<section id="details.portability">
<title>Portability</>
<para>
Below is the list of compilers the library has been tested with:
</>
<itemizedlist mark="box">
<listitem><simpara>Microsoft Visual C++ 6.0, SP 5</></>
<listitem><simpara>Microsoft Visual C++ .NET (7.0)</></>
<listitem><simpara>Metrowerks CodeWariror 7.2/8.1</></>
<listitem><simpara>Intel C++ Compiler 5.0, 6.0</></>
<listitem><simpara>GCC 2.95.3-5</></>
<listitem><simpara>GCC 3.1</></>
<listitem><simpara>Comeau C/C++ 4.2.45/4.3.0</></>
<listitem><simpara>Borland C++ 5.5.1</></>
</>
<para>An incomplete matrix of recent test compilation results is available from here - <ulink url="http://www.mywikinet.com/mpl/log.html"></>.
</>
</section>
</section>
+29
View File
@@ -0,0 +1,29 @@
<!-- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| section -->
<section id="tutorial">
<title>Mini-tutorial</>
<!-- ||||||||||||||||||||||||||||| subsection -->
<section id="tutorial.conventions">
<title>Conventions used</>
<para>
The examples used through this tutorial use fully qualified names, e.g. <literal>std::vector</> instead of plain <literal>vector</>. Any unqualified name refers to a local entity defined in the example itself. The names from <literal>boost::mpl</> namespace are referred to using <literal>mpl</> namespace alias (e.g. <literal>mpl::apply</> instead of <literal>boost::mpl::apply</>), as if the following namespace alias definition were in effect:
</>
<programlisting>
<![CDATA[
namespace mpl = boost::mpl;
]]>
</>
<para>Note that the library offers a special header, <literal>boost/mpl/alias.hpp</>, including which gives you a rough equivalent of the above. Alternatively, you can always spell the namespace alias definition manually in each translation unit as needed (if you choose to use the shorter namespace notation at all).
</>
</section>
&metafunctions;
&if;
&applyif;
&applyif2;
</section>