Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r60402 - sandbox/statistics/detail/assign/libs/assign/doc
From: erwann.rogard_at_[hidden]
Date: 2010-03-09 20:51:58

Author: e_r
Date: 2010-03-09 20:51:57 EST (Tue, 09 Mar 2010)
New Revision: 60402
URL: http://svn.boost.org/trac/boost/changeset/60402

Log:
m
Added:
sandbox/statistics/detail/assign/libs/assign/doc/index.html (contents, props changed)

Added: sandbox/statistics/detail/assign/libs/assign/doc/index.html
==============================================================================
--- (empty file)
+++ sandbox/statistics/detail/assign/libs/assign/doc/index.html 2010-03-09 20:51:57 EST (Tue, 09 Mar 2010)
@@ -0,0 +1,1982 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Boost.Assignment Documentation </title>
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+
+<body>
+
+ <table border="0" >
+ <tr>
+ <td ><img src="../../../boost.png" border="0" ></td>
+ <td >
+ <h1 align="center">Assignment Library</h1>
+ </td>
+ </tr>
+ </table>
+
+ 
+ Copyright © 2003-2006 Thorsten Ottosen
+ 
+ 
+ Use, modification and distribution is subject to the Boost Software License, Version 1.0
+ (see <a href="http://www.boost.org/LICENSE_1_0.txt">
+ http://www.boost.org/LICENSE_1_0.txt>).
+ 
+ <h3>Table of Contents</h3>
+ <ul>
+ <li>Introduction</li>
+ <li>
+ Tutorial
+ <ul>
+ <li>Function operator+=()
+ <li>Function operator()()
+ <li>Function list_of()
+ <li>Function map_list_of()
+ <li>Function tuple_list_of()
+ <li>Functions repeat(), repeat_fun() and range()
+ <li>Functions ref_list_of(), cref_list_of() and related functions
+ <li>Functions ref_csv(), cref_csv() and related functions
+ <li>A "complicated" example
+ <li>Functions ptr_push_back(), ptr_push_front(),
+ ptr_insert() and ptr_map_insert()
+ <li>Function ptr_list_of()
+ </ul>
+ <li> Design </li>
+ <li>
+ Reference for functions and operators
+ <ul>
+ <li>Headers </li>
+ <li>Functions list_of(), map_list_of() and ref_list_of<int>()</li>
+ <li>Function make_list_inserter()</li>
+ <li>Functions ref_list_of(), cref_list_of(), and related functions</li>
+ <li>Functions ref_csv(), cref_csv(), and related functions</li>
+ <li>Operator += for standard containers</li>
+ <li>Functions repeat(), repeat_fun() and
+ <a href="#ref-repeat_ref"><code>range()</code>
+ </a></li>
+ <li>Customizing argument list sizes </li>
+ </ul>
+ <li>
+ Reference for the implementation
+ <ul>
+ <li> Proxy object converter<> </li>
+ <li> Proxy object generic_list<> </li>
+ <li> Proxy object list_inserter<></li>
+ <li> Proxy object static_generic_list<> </li>
+ <li> Proxy object array_interface<> </li>
+ <li> Proxy object expr<> </li>
+ <li> Proxy object lazy_array<> </li>
+ <li> Proxy object static_array<> </li>
+ </ul>
+ <li> Exceptions and exception-safety </li>
+ <li> Extending the library
+ <li> Supported libraries
+ <li> Examples</li> <ul></ul>
+ <li>Portability</li>
+ <li>History and Acknowledgment
+ <li>References</li>
+ </ul>
+ <hr>
+
+
+
+<h2><a name="intro">Introduction</a></h2> There appear to be few
+practical uses of <code>operator,()</code>.  Bjarne
+Stroustrup, The Design and Evolution of C++ The purpose of this
+library is to make it easy to fill containers with data by overloading
+<code>operator,()</code> and <code>operator()()</code>. These two operators
+make it possible to construct lists of values that are then copied into a
+container: <ul> <li> A comma-separated list: 
+ 
+
+<pre>vector<int> v; 
+v += 1,2,3,4,5,6,7,8,9;</pre>
+ <li> A parenthesis-separated list:
+ 
+ <pre>
+map<string,int> m; 
+insert( m )( "Bar", 1 )( "Foo", 2 );</pre>
+ </ul>
+
+ These lists are particularly useful in
+ learning, testing, and prototyping situations, but can also be handy otherwise.
+ The library comes with predefined operators for the containers of the
+ standard library, but most functionality will work with any standard
+compliant container. The library also makes it possible to extend user
+ defined types so for example a member function can be called for a list of
+values instead of its normal arguments. 
+ <hr>
+
+ <a name="tutorial"></a>
+ <h2>Tutorial</h2>
+ 
+ Within two minutes you should be able to use this library. The main
+components are explained in these sections:
+ <ul>
+ <li>Function operator+=()
+ <li>Function operator()()
+ <li>Function list_of()
+ <li>Function map_list_of()
+ <li>Function tuple_list_of()
+ <li>Functions repeat(), repeat_fun() and range()
+ <li>Functions ref_list_of(), cref_list_of() and related functions
+ <li>Functions ref_csv(), cref_csv() and related functions
+ <li>A "complicated" example
+ <li>Functions ptr_push_back(), ptr_push_front(), ptr_insert() and ptr_map_insert()
+ <li>Function ptr_list_of()
+
+ </ul>
+ The two first functions are used for adding elements after a container object
+ has been created whereas the next two is used when we need to initialize an
+ object. 
+ <h3>Function <code>operator+=()</code><a name="operator+="></h3>
+ 
+ To fill a vector (or any standard container) with values using
+ <code>operator+=()</code> you write
+ <blockquote><pre>
+#include <boost/assign/std/vector.hpp> // for 'operator+=()'
+#include <boost/assert.hpp>;
+using namespace std;
+using namespace boost::assign; // bring 'operator+=()' into scope
+
+{
+ vector<int> values;
+ values += 1,2,3,4,5,6,7,8,9; // insert values at the end of the container
+ BOOST_ASSERT( values.size() == 9 );
+ BOOST_ASSERT( values[0] == 1 );
+ BOOST_ASSERT( values[8] == 9 );
+}</pre></blockquote>
+
+ Here we only stuffed constants into the container, but the list can
+ consists of arbitrary expressions as long as the result of each
+expression is convertible to the <code>value_type</code> of the container.
+ 
+
+
+ <h3>Function <code>operator()()</code> <a name="operator()"></h3>
+ 
+ We do not call <code>operator()()</code> directly, but instead we call a
+ function that returns a proxy-object that defines <code>operator()()</code>.
+ The function that returns the proxy object is always named after the member
+ function that is used to copy the values in the list into the container.
+ So to fill a map with pairs of values you write
+ <blockquote><pre>
+#include <boost/assign/list_inserter.hpp> // for 'insert()'
+#include <boost/assert.hpp>
+#include <string>
+using namespace std;
+using namespace boost::assign; // bring 'insert()' into scope
+
+{
+ map<string,int> months;
+ insert( months )
+ ( "january", 31 )( "february", 28 )
+ ( "march", 31 )( "april", 30 )
+ ( "may", 31 )( "june", 30 )
+ ( "july", 31 )( "august", 31 )
+ ( "september", 30 )( "october", 31 )
+ ( "november", 30 )( "december", 31 );
+ BOOST_ASSERT( months.size() == 12 );
+ BOOST_ASSERT( months["january"] == 31 );
+} </pre></blockquote>
+
+ Note that <code>operator()()</code> is much more handy when
+ we need to construct objects using several arguments
+ (up to five arguments are supported by default, but the limit can be customized).
+ This is also true for sequences:
+
+ <blockquote><pre>
+#include <boost/assign/list_inserter.hpp> // for 'push_front()'
+#include <boost/assert.hpp>
+#include <string>
+#include <utility>
+using namespace std;
+using namespace boost::assign; // bring 'push_front()' into scope
+
+{
+ typedef pair< string,string > str_pair;
+ deque<str_pair> deq;
+ push_front( deq )( "foo", "bar")( "boo", "far" );
+ BOOST_ASSERT( deq.size() == 2 );
+ BOOST_ASSERT( deq.front().first == "boo" );
+ BOOST_ASSERT( deq.back().second == "bar" );
+} </pre></blockquote>
+
+ Besides <code>push_front()</code> we could also have used
+ <code>push_back()</code> if the container has a corresponding member
+ function. Empty parentheses can be used to insert default-constructed
+objects, for example,
+<code>push_front( deq )()()</code> will insert two default-constructed
+<code>str_pair</code> objects. 
+
+ 
+ If <code>operator()()</code> is too cumbersome to use with eg.
+<code>push_front()</code>we can also say 
+
+<blockquote>
+ <pre>
+deque<int> di; 
+push_front( di ) = 1,2,3,4,5,6,7,8,9;
+BOOST_ASSERT( di.size() == 9 ); 
+BOOST_ASSERT( di[0] == 9 ); 
+</pre>
+</blockquote>
+
+Just to make it perfectly clear, the code above is not restricted to the
+standard containers, but will work with all standard compliant containers
+with the right member function. It is only <code>operator+=()</code> that has been restricted to
+the standard containers. 
+
+ <h3>Function <code>list_of()</code> <a name="list_of"></h3>
+ But what if we need to initialize a container? This is where
+ <code>list_of()</code> comes into play. With <code>list_of()</code>
+ we can create anonymous lists that automatically converts to
+ any container:
+ <blockquote><pre>
+#include <boost/assign/list_of.hpp> // for 'list_of()'
+#include <boost/assert.hpp>
+#include <list>
+#include <stack>
+#include <string>
+using namespace std;
+using namespace boost::assign; // bring 'list_of()' into scope
+
+{
+ const list<int> primes = list_of(2)(3)(5)(7)(11);
+ BOOST_ASSERT( primes.size() == 5 );
+ BOOST_ASSERT( primes.back() == 11 );
+ BOOST_ASSERT( primes.front() == 2 );
+
+ const stack<string> names = list_of( "Mr. Foo" )( "Mr. Bar")( "Mrs. FooBar" ).to_adapter();
+ const stack<string> names2 = (list_of( "Mr. Foo" ), "Mr. Bar", "Mrs. FooBar" ).to_adapter();
+ BOOST_ASSERT( names.size() == 3 );
+ BOOST_ASSERT( names.top() == "Mrs. FooBar" );
+} </pre></blockquote>
+ If we need to initialize a container adapter, we need to help the compiler a
+little by calling <code>to_adapter()</code>. As the second example also shows,
+we can use a comma-separated
+list with <code>list_of()</code> if we add parenthesis around the
+ entire right hand side. It is worth noticing that the first argument
+ of <code>list_of()</code> determines the type of the anonymous list.
+ In case of the stack, the anonymous list consists of
+ <code>const char*</code> objects which are then converted to
+ a stack of <code>string</code> objects. The conversion is always
+ possible as long as the conversion between the stored types is possible.
+ 
+ 
+ Please notice that <code>list_of()</code> can even convert to a
+ <code>boost::<a
+href="../../array/index.html">array</a><T,sz></code> and see also the list
+of supported libraries . 
+ 
+ Note that the type returned by
+ <code>list_of()</code> (and its variants) has overloaded comparison operators. This allows you to
+ write test code such as
+ <code>
+ BOOST_CHECK_EQUAL( my_container, list_of(2)(3)(4)(5) );.
+ </code>
+ 
+
+ <h3>Function <code>map_list_of()</code> <a name="map_list_of"></h3>
+ This function is defined for pure convenience when working with
+ maps. Its usage is simple:
+ <blockquote><pre>
+#include <boost/assign/list_of.hpp> // for 'map_list_of()'
+#include <boost/assert.hpp>
+#include <map>
+using namespace std;
+using namespace boost::assign; // bring 'map_list_of()' into scope
+
+{
+ map<int,int> next = map_list_of(1,2)(2,3)(3,4)(4,5)(5,6);
+ BOOST_ASSERT( next.size() == 5 );
+ BOOST_ASSERT( next[ 1 ] == 2 );
+ BOOST_ASSERT( next[ 5 ] == 6 );
+
+ // or we can use 'list_of()' by specifying what type
+ // the list consists of
+ next = list_of< pair<int,int> >(6,7)(7,8)(8,9);
+ BOOST_ASSERT( next.size() == 3 );
+ BOOST_ASSERT( next[ 6 ] == 7 );
+ BOOST_ASSERT( next[ 8 ] == 9 );
+} </pre></blockquote>
+
+The function <code>pair_list_of()</code> may also be used.
+
+<h3>Function <code>tuple_list_of()</code> <a name="tuple_list_of"></h3>
+
+If you are working with tuples, it might be convenient to use
+<code>tuple_list_of()</code>:
+
+
+<blockquote>
+ <pre>
+#include <boost/assign/list_of.hpp>
+#include <vector>
+
+using namespace std;
+using namespace boost::assign;
+
+{
+ typedef boost::tuple<int,std::string,int> tuple;
+
+ vector<tuple> v = tuple_list_of( 1, "foo", 2 )( 3, "bar", 4 );
+ BOOST_CHECK( v.size() == 2 );
+ BOOST_CHECK( boost::get<0>( v[1] ) == 3 );
+}
+ </pre>
+</blockquote>
+
+<h3>Functions <code>repeat()</code>, <code>repeat_fun()</code> and <code>range()</code> <a name="repeat"></h3>
+
+Sometimes it is too irritating to repeat the same value many times. This is
+where <code>repeat()</code> can be handy:
+<blockquote>
+ <pre>
+#include <boost/assign/list_of.hpp>
+#include <boost/assign/std/vector.hpp>
+#include <boost/assert.hpp>
+
+using namespace std;
+using namespace boost::assign;
+ 
+{
+ vector<int> v;
+ v += 1,2,3,repeat(10,4),5,6,7,8,9;
+ // v = [1,2,3,4,4,4,4,4,4,4,4,4,4,5,6,7,8,9]
+ BOOST_ASSERT( v.size() == 3 + 10 + 5 );
+
+ v = list_of(1).repeat(5,2)(3);
+ // v = [1,2,2,2,2,2,3]
+ BOOST_ASSERT( v.size() == 1 + 5 + 1 );
+
+ push_back( v )(1).repeat(1,2)(3);
+ // v = old v + [1,2,3]
+ BOOST_ASSERT( v.size() == 10 );
+}</pre>
+</blockquote>
+As we can see, then the first argument to <code>repeat()</code> is the number
+of times to repeat the second argument.
+
+
+A more general list can be constructed with <code>repeat_fun()</code>:
+
+<blockquote>
+ <pre>
+#include <boost/assign/std/vector.hpp>
+#include <boost/assert.hpp>
+#include <cstdlib> // for 'rand()'
+
+using namespace std;
+using namespace boost::assign;
+ 
+template< class T >
+struct next 
+{
+ T seed;
+ next( T seed ) : seed(seed)
+ { }
+
+ T operator()() 
+ {
+ return seed++;
+ }
+};
+ 
+{
+ vector<int> v;
+ v += 1,2,repeat_fun(4,&rand),4;
+ // v = [1,2,?,?,?,?,4]
+ BOOST_ASSERT( v.size() == 7 );
+
+ push_back( v ).repeat_fun(4,next<int>(0))(4).repeat_fun(4,next<int>(5));
+ // v = old v + [0,1,2,3,4,5,6,7,8]
+ BOOST_ASSERT( v.size() == 16 );
+} </pre>
+</blockquote>
+The only requirement of the second argument to <code>repeat_fun()</code> is that
+it is a nullary function. 
+
+
+
+If you just need to insert an iterator-range somewhere in the list, the member function <code>range()</code> provides just what you want.
+It is based on Boost.Range, so you can pass all the ranges supported by that library. For example
+<blockquote><pre>#include <boost/assign/list_inserter.hpp> // for 'push_back()'
+#include <boost/assign/list_of.hpp> // for 'list_of()' and 'ref_list_of()'
+#include <boost/assert.hpp>
+
+using namespace std;
+using namespace boost::assign;
+
+{
+ vector<int> v, v2;
+ v = list_of(1)(2)(3);
+ v2 = list_of(0).range(v).range(v.begin(),v.end())(4);
+ // v2 = [0,1,2,3,1,2,3,4]
+ BOOST_ASSERT( v2.size() == 8u );
+
+ push_back( v ).range(v2)(5);
+ // v = [1,2,3,0,1,2,3,1,2,3,4,5]
+ BOOST_ASSERT( v.size() == 12u );
+
+ //
+ // create a list of references, some coming from a container, others from the stack
+ //
+ int x = 0;
+ int y = 1;
+ BOOST_ASSERT( ref_list_of<10>(x).range(v2)(y).size() == 10u );
+}</pre>
+</blockquote>
+As you can see, one can also pass two iterators if that is more appropriate.
+The last example also introduces list of references. More about that below.
+
+
+
+<h3>Functions <code>ref_list_of()</code>, <code>cref_list_of()</code> <a name="ref_list_of"> and related functions</h3>
+
+When you need to create an anonymous range of values and speed is essential,
+these two functions provide what you want. <blockquote>
+ <pre>
+#include <boost/assign/auto_size/ref_list_of.hpp>
+#include <boost/range/algorithm/max_element.hpp>
+
+using namespace boost::assign;
+
+{
+ int a=1,b=5,c=3,d=4,e=2,f=9,g=0,h=7;
+ int& max = *boost::max_element( ref_list_of(a)(b)(c)(d)(e)(f)(g)(h) );
+ BOOST_CHECK_EQUAL( max, f );
+ max = 8;
+ BOOST_CHECK_EQUAL( f, 8 );
+ const int& const_max 
+ = *boost::max_element( cref_list_of(1)(5)(3)(d)(e)(f)(g)(h) );
+ BOOST_CHECK_EQUAL( max, const_max );
+}
+ </pre>
+</blockquote>
+
+You can only use lvalues with <code>ref_list_of()</code> while
+<code>cref_list_of()</code> accepts rvalues too, as exemplified by the first three arguments of the
+corresponding function call in this example.
+
+ The collection built from <code>ref_list_of()</code> and <code>cref_list_of()</code> has most of the functionality of <code>boost::array<></code>, and
+the same conversion capabilities as the collection built from <code>list_of()</code>. However, the user can design his own 'policy' and call it with the overloaded functions
+<code>ref_list_of()</code> and
+<code>cref_list_of()</code>, where <code>P</code> is an associated policy tag. See the reference for details
+
+
+
+There are overloads which predate the above functions,
+<code>ref_list_of<int>()</code> and <code>cref_list_of<int>()</code>, whose integer template parameter specifies the maximum number of arguments.
+The resulting collection builder exposes a similar interface to that above, save for the specifics of an array, and is not customizable via a policy.
+See the reference for details
+
+
+
+A variation on <code>ref_list_of()</code> and <code>cref_list_of()</code>, are <code>ref_rebind_list_of()</code> and <code>cref_rebind_list_of()</code>, respectively, that have rebind,
+rather than copy semantics, when the collection is used as the left hand side of an assignement. These are discouraged unless this specific feature is required. See the reference.
+
+
+<h3>Functions <code>ref_csv()</code>, <code>cref_csv()</code> <a name="ref_csv"> and related functions</h3>
+
+The functions ref_list_of(), cref_list_of(),
+their respective rebind analogs, and the overloads of these four whose policy is specified by a template parameter,
+have counterparts that are identified by suffix 'csv' (comma separated values) instead of 'list_of'. For example,
+<blockquote>
+ <pre>
+#include <boost/assign/auto_size/ref_csv.hpp>
+#include <boost/range/algorithm/max_element.hpp>
+
+using namespace boost::assign;
+
+{
+ int a=1,b=5,c=3,d=4,e=2,f=9,g=0,h=7;
+ int& max = *boost::max_element( ref_csv(a,b,c,d,e,f,g,h) );
+ BOOST_CHECK_EQUAL( max, f );
+}
+ </pre>
+</blockquote>
+
+ The result of a csv call has the same array and conversion capabilities as its non-csv counterpart.
+The main difference is that the the collection is not extensible. See the reference.
+
+ The maximum number of arguments to a csv function is <code>BOOST_ASSIGN_CSV_SIZE</code>. 
+
+<h3>A "complicated" example <a name="complicated"></h3>
+
+As a last example, let us assume that we need to keep track of the
+result of soccer matches. A team will get one point if it wins
+and zero otherwise. If there has been played three games in each group, the code might look
+like this:
+
+<blockquote>
+ <pre>
+#include <boost/assign/list_of.hpp>
+#include <boost/assign/list_inserter.hpp>
+#include <boost/assert.hpp>
+#include <string>
+#include <vector>
+
+using namespace std;
+using namespace boost::assign;
+ 
+{
+ typedef vector<int> score_type;
+ typedef map<string,score_type> team_score_map;
+ typedef pair<string,score_type> score_pair;
+
+ team_score_map group1, group2;
+
+ //
+ // method 1: using 'insert()'
+ //
+ insert( group1 )( "Denmark", list_of(1)(1) )
+ ( "Germany", list_of(0)(0) )
+ ( "England", list_of(0)(1) );
+ BOOST_ASSERT( group1.size() == 3 );
+ BOOST_ASSERT( group1[ "Denmark" ][1] == 1 );
+ BOOST_ASSERT( group1[ "Germany" ][0] == 0 );
+
+ //
+ // method 2: using 'list_of()'
+ //
+ group2 = list_of< score_pair >
+ ( "Norway", list_of(1)(0) )
+ ( "USA", list_of(0)(0) )
+ ( "Andorra", list_of(1)(1) );
+ BOOST_ASSERT( group2.size() == 3 );
+ BOOST_ASSERT( group2[ "Norway" ][0] == 1 );
+ BOOST_ASSERT( group2[ "USA" ][0] == 0 );
+}
+ </pre>
+</blockquote>
+
+In the first example, notice how the result of <code>list_of()</code>
+can be converted automatically to a <code>vector<int></code> because
+<code>insert()</code> knows it expects a <code>vector<int></code>.
+In the second example we can see that <code>list_of()</code> is somewhat
+less intelligent since here it needs to be told explicitly what arguments to
+expect. (In the future it might be possible to introduce a more intelligent
+conversion layer in <code>list_of()</code>.)
+
+
+<h3>Functions <code>ptr_push_back(),
+ptr_push_front()</code>, <code>ptr_insert()</code> and <code>ptr_map_insert()</code> <a name="ptr_push_back"></h3>
+
+For use with Boost.Pointer Container
+a few special exception-safe functions are provided. Using these function you
+do not need to call <code>new</code> manually:
+
+
+<blockquote>
+ <pre>
+#include <boost/assign/ptr_list_inserter.hpp> // for 'ptr_push_back()', 'ptr_insert()' and 'ptr_push_front()'
+#include <boost/assign/ptr_map_inserter.hpp> // for 'ptr_map_insert()'
+#include <boost/ptr_container/ptr_deque.hpp>
+#include <boost/ptr_container/ptr_set.hpp>
+#include <boost/ptr_container/ptr_map.hpp>
+
+//
+// Example class
+//
+struct Foo
+{
+ int i;
+
+ Foo() : i(0)
+ { }
+ Foo( int i ) : i(i)
+ { }
+ Foo( int i, int ) : i(i)
+ { }
+ Foo( const char*, int i, int ) : i(i)
+ { }
+
+ virtual ~Foo()
+ {}
+};
+
+struct Bar : Foo
+{
+ Bar()
+ { }
+
+ Bar( int i ) : Foo( 42 )
+ { }
+};
+
+//
+// Required by ptr_set<Foo>
+//
+inline bool operator<( Foo l, Foo r )
+{
+ return l.i < r.i;
+}
+
+
+using namespace boost;
+using namespace boost::assign;
+
+int main()
+{
+ ptr_deque<Foo> deq;
+ ptr_push_back( deq )()();
+ BOOST_ASSERT( deq.size() == 2u );
+ ptr_push_back<Bar>( deq )()(); // insert 'Bar' objects
+ BOOST_ASSERT( deq.size() == 4u );
+ ptr_push_front( deq )( 3 )( 42, 42 )( "foo", 42, 42 );
+ BOOST_ASSERT( deq.size() == 7u );
+
+ ptr_set<Foo> a_set;
+ ptr_insert( a_set )()( 1 )( 2, 2 )( "foo", 3, 3 );
+ BOOST_ASSERT( a_set.size() == 4u );
+ ptr_insert( a_set )()()()();
+ BOOST_ASSERT( a_set.size() == 4u ); // duplicates not inserted
+ ptr_insert<Bar>( a_set )( 42 ); // insert a 'Bar' object
+ BOOST_ASSERT( a_set.size() == 5u );
+
+ ptr_map<int,Foo> a_map;
+ ptr_map_insert( a_map )( 1 )( 2, 2 )( 3, 3, 3 )( 4, "foo", 4, 4 );
+ ptr_map_insert<Bar>( a_map )( 42, 42 ); // insert a 'Bar' object
+}
+ </pre>
+</blockquote>
+
+Notice how you may provide a template argument to these functions. This argument determines the type to allocate with <code>new</code>.
+You have to specify this argument when the container is based on an abstract type (because one cannot create objects of such a type).
+
+
+For <code>ptr_map_insert()</code> the first argument <code>arg1</code> in an argument tuple <code>(arg1,arg2,...,argN)</code> is used to
+construct a key; this means that the first argument need only be convertible to the <code>key_type</code> of the container.
+The rest of the arguments are used to construct the mapped object.
+
+
+<h3>Function <code>ptr_list_of()</code> <a name="ptr_list_of"></h3>
+
+Just like you can use <code>list_of()</code> to initialize containers, you can
+use <code>ptr_list_of()</code> to initialize a pointer container.
+Here is a small example:
+
+<blockquote>
+ <pre>
+#include <boost/assign/ptr_list_of.hpp>
+#include <boost/ptr_container/ptr_deque.hpp>
+
+using namespace boost;
+using namespace boost::assign;
+
+{
+ ptr_deque<Foo> deq;
+ deq = ptr_list_of<Foo>( 42 )()()( 3, 3 )( "foo", 2, 1 );
+ BOOST_CHECK( deq.size() == 5 );
+}
+ </pre>
+</blockquote>
+
+Notice that a trailing <code>.to_container(deq)</code> may be added to help many poor
+compilers to figure out the conversion (a few get it right).
+Notice also that pointer maps are
+not supported.
+
+
+That is all; now you are ready to use this library.
+ 
+
+ <hr>
+ <h2><a name="design">Design</a></h2>
+ 
+ This section explains the way the library is implemented.
+ A free-standing function (eg. <code>push_back()</code>
+ or <code>operator+=()</code>) returns a proxy
+ object which is responsible for the insertion or the assignment. The proxy
+object does the insertion or assignment by overloading <code>operator,()</code>
+ and <code>operator()()</code> and by calling the "insert" function from within
+ those operators. The "insert" function is typically stored in the proxy object
+ by using <code>boost::function</code>. 
+
+ 
+ Often overloading
+ of <code>operator,()</code> is discouraged because it can lead to surprising
+ results, but the approach taken in this library is safe since the
+ user never deals with objects that have overloaded <code>operator,()</code>
+ directly. However, you should be aware of this:
+ 
+
+ 
+ The
+ expressions in a comma-separated list no longer follow the rules of the
+ built-in comma-operator. This means that the order of evaluation of
+ expressions in a comma-separated list is undefined like when one specifies
+ a list of function arguments.
+ 
+
+ 
+ Most of the code in this document use <code>int</code> in the examples,
+ but of course it works for arbitrary types as long as they are
+ Copy Constructible. The inserted data need not be constant data,
+ but can be variables or data returned from functions; the only requirement
+ is that the type of the data is convertible to the type stored in the
+ container.
+ 
+
+ 
+ All forwarding is done by passing objects by <code>const</code> reference.
+Originally arguments were passed by value (and still is in
+<code>tuple_list_of()</code>). One thing to remember is that references
+ can be passed by using <code>boost::ref</code>.
+ 
+
+ 
+ Everything is put in namespace
+ <code>boost::assign</code>. 
+
+According to the above design considerations, the reference is organized into two parts:
+Functions and operators and Proxy objects.
+
+ <h2>Reference for functions and operators <a name="ref-functions"> </h3>
+
+ <h3>Contents</h3>
+
+ <ul>
+
+ <li>Headers </li>
+ <li>Functions list_of(), map_list_of() and ref_list_of<int>()</li>
+ <li>Function make_list_inserter()</li>
+ <li>Functions ref_list_of(), cref_list_of(), and related functions</li>
+ <li>Functions ref_csv(), cref_csv(), and related functions</li>
+ <li>Operator += for standard containers</li>
+ <li>Functions repeat(), repeat_fun() and
+ <a href="#ref-repeat_ref"><code>range()</code>
+ </a></li>
+ <li>Customizing argument list sizes </li>
+ </ul>
+
+ <h3>Headers <a name="ref-function-headers"></h3>
+
+ 
+ Please notice <code><boost/assign/list_inserter.hpp></code> is included for each header that defines <code>operator+=()</code>.
+
+<table cellpadding=5 border=1 > <tr>
+ <th> Header </th>
+ <th> Includes </th>
+ <tr>
+ <td> <boost/assign.hpp> </td>
+ <td> everything except support for pointer containers </td>
+ <tr>
+ <td> <boost/assign/auto_size/ref_csv.hpp> </td>
+ <td> ref_csv() and cref_csv()
+ <tr>
+ <td> <boost/assign/auto_size/ref_rebind_csv.hpp> </td>
+ <td> ref_rebind_csv() and cref_rebind_csv()
+ <tr>
+ <td> <boost/assign/auto_size/ref_list_of.hpp> </td>
+ <td> ref_list_of() and
+cref_list_of() </td>
+ <tr>
+ <td> <boost/assign/auto_size/ref_rebind_list_of.hpp> </td>
+ <td> ref_rebind_list_of() and
+cref_rebind_list_of() </td>
+ <tr>
+ <td> <boost/assign/list_of.hpp> </td>
+ <td> list_of(), <a +href="#map_list_of">map_list_of()</code></a>, + tuple_list_of(),
+ ref_list_of<int>() and
+ref_list_of<int>()
+
+
+ </td> <tr>
+ <td> <boost/assign/std.hpp> </td>
+ <td> operator+=() for all
+standard
+containers (see below)</td> <tr> <td> <boost/assign/std/deque.hpp> </td>
+ <td> <code>operator+=()</code> for
+ <code>std::deque</code>, <code><deque></code>
+ <tr>
+ <td> <boost/assign/std/list.hpp> </td>
+ <td> <code>operator+=()</code> for
+ <code>std::list</code>, <code><list></code>
+ <tr>
+ <td> <boost/assign/std/map.hpp> </td>
+ <td> <code>operator+=()</code> for
+ <code>std::map</code> and <code>std::multimap</code> ,
+<code><map></code> <tr>
+ <td> <boost/assign/std/queue.hpp> </td>
+ <td> <code>operator+=()</code> for
+ <code>std::queue</code> and <code>std::priority_queue</code>,
+<code><queue></code> <tr>
+ <td> <boost/assign/std/set.hpp> </td>
+ <td> <code>operator+=()</code> for
+ <code>std::set</code> and <code>std::multiset</code>,
+<code><set></code> <tr>
+ <td> <boost/assign/std/slist.hpp> </td>
+ <td> <code>operator+=()</code> for
+ <code>std::slist</code> if the class is available ,
+<code><slist></code> <tr>
+ <td> <boost/assign/std/stack.hpp> </td>
+ <td> <code>operator+=()</code> for
+ <code>std::stack</code>, <code><stack></code>
+ <tr>
+ <td> <boost/assign/std/vector.hpp> </td>
+ <td> <code>operator+=()</code> for
+ <code>std::vector</code>, <code><vector></code>
+ <tr>
+ <td> <boost/assign/assignment_exception.hpp> </td>
+ <td> Class <a
+href="#assignment_exception"><code>assignment_exception</code></a> which might
+be thrown by the proxy returned by <code>list_of()</code>
+ <tr>
+ <td> <boost/assign/list_inserter.hpp> </td>
+ <td>Functions <a
+ href="#ref-make_list_inserter"><code>make_list_inserter()</code></a>, <code>push_back()</code>,
+ <code>push_front()</code>,<code>insert()</code>,
+ <code>
+ push()</code> and class list_inserter
+ which is the back-bone of this entire library.
+
+ <tr>
+ <td> <boost/assign/ptr_list_inserter.hpp> </td>
+ <td>Functions ptr_push_back(),
+ <code>ptr_push_front()</code> and <code>ptr_insert()</code>
+
+ <tr>
+ <td> <boost/assign/ptr_map_inserter.hpp> </td>
+ <td>Functions ptr_map_insert()
+
+ <tr>
+ <td> <boost/assign/ptr_list_of.hpp> </td>
+ <td>Function ptr_list_of()
+
+ </table>
+
+ <h3><a name="ref-limit">Customizing argument list sizes </a></h3>
+ 
+ This library uses the boost Preprocessor Library to implement overloaded
+ versions of <code>operator()()</code> and <code>list_of()</code>. By default you
+ can call these functions with five arguments, but you can also customize this
+ number by defining a macros before including a header from this library:
+ <blockquote>
+ <pre>
+#define BOOST_ASSIGN_MAX_PARAMS 10
+#include <boost/assign.hpp>
+</pre>
+ </blockquote>
+ 
+
+
+ <h3>Functions <code>list_of()</code>,
+ <code>map_list_of()</code> and <code>ref_list_of<int>()</code> <a name=ref-list_of> </h3>
+ 
+ The first two functions are used to construct anonymous list which can be converted to any standard container
+ and <code>boost::array<T,sz>.</code> Specifically, the
+ object returned by the two functions is generic_list<>.
+ The third function can be used to construct an anonymous list of references. The corresponding collection builder is
+ static_generic_list<>. Note that the 'auto-size'
+ framework defines <a href="#ref-ref_list_of">overloads<a> for this function, that deduce the number of arguments at compile time.
+
+ <h3><a name="ref-make_list_inserter">Function <code>make_list_inserter()</code></a></h3>
+ 
+ A simple "constructor" function for <code>list_inserter</code>. A typical
+ use of this function is to call it with the result of
+<code>boost::bind()</code>
+ which in general returns some unreadable and weird class template.
+ 
+ Synopsis
+ <blockquote><pre>
+namespace boost 
+{
+namespace assign
+{
+ template< class Function >
+ list_inserter<Function> make_list_inserter( Function fun )
+ {
+ return list_inserter<Function>( fun );
+ } 
+}
+} </pre></blockquote>
+
+
+ <h3>Functions <code>ref_list_of()</code>,
+ <code>cref_list_of()</code> and related functions <a name=ref-ref_list_of> </h3>
+
+ Template parameters
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>P</tt></td><td>A policy tag</td></tr>
+ <tr><td><tt>T</tt></td><td>Element</td></tr>
+ </table>
+ </blockquote>
+
+ Usage
+ Let <code>d1</code> and <code>d2</code> denote objects of type <code>T</code> and <code>const T</code>, respectively.
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Result type</th>
+ <tr><td><tt>ref_list_of(d1)</tt></td><td> expr<top_,T,1,ref_copy,P></td></tr>
+ <tr><td><tt>cref_list_of(d2)</tt></td><td> expr<top_,const T,1,ref_copy,P></td></tr>
+ <tr><td><tt>ref_list_of(d1)</tt></td><td> expr<top_,T,1,ref_copy,default_policy></td></tr>
+ <tr><td><tt>cref_list_of(d2)</tt></td><td> expr<top_,const T,1,ref_copy,default_policy></td></tr>
+ </table>
+ </blockquote>
+
+Usage for the related functions <code>ref_rebind_list_of()</code> and <code>cref_rebind_list_of()</code> are identical to those
+above, except the fourth argument to expr<> is a reference wrapper with rebind semantics, <code>ref_rebind</code>.
+
+
+ <h3>Functions <code>ref_csv()</code>,
+ <code>cref_csv()</code> and related functions <a name=ref-ref_csv> </h3>
+
+ Template parameters
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>P</tt></td><td>A policy tag</td></tr>
+ <tr><td><tt>T</tt></td><td>Element</td></tr>
+ <tr><td><tt>U</tt></td><td><tt>T</tt> or <tt>const T</tt></td></tr>
+ <tr><td><tt>N</tt></td><td>Size</td></tr>
+ <tr><td><tt>R</tt></td><td>A Reference wrapper</td></tr>
+ </table>
+ </blockquote>
+
+ Associated types
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Description</th> <th>Alias</th>
+ <tr><td><tt>csv_policy::apply<U,N,R>::type</tt></td><td>A proxy object</td><td><tt>Impl<P,U,N,R></tt></td></tr>
+ <tr><td><tt>csv_policy<default_policy>::apply<U,N,R>::type</tt></td><td> static_array<T,N,R></td><td><tt>Impl0<U,N,R></tt></td></tr>
+ </table>
+ </blockquote>
+
+ Usage
+ Let <code>ai</code> and <code>bi</code> denote the <tt>i</tt>-th element of size-<tt>N</tt> sequences of objects of type <code>T</code> and <code>const T</code>,
+ respectively
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Result type</th>
+ <tr><td><tt>ref_csv(a1,...,aN)</tt></td><td><tt>Impl<P,T,N,ref_copy></tt></td></tr>
+ <tr><td><tt>cref_csv(b1,...,bN)</tt></td><td><tt>Impl<P,const T,N,ref_copy></tt></td></tr>
+ <tr><td><tt>ref_csv(a1,...,aN)</tt></td><td><tt>Impl0<T,N,ref_copy></tt></td></tr>
+ <tr><td><tt>cref_csv(b1,...,bN)</tt></td><td><tt>Impl0<const T,N,ref_copy></tt></td></tr>
+ </table>
+ </blockquote>
+
+Usage for the related functions <code>ref_rebind_list_of()</code> and <code>cref_rebind_list_of()</code> are identical to those
+above, except <code>R=ref_rebind</code>.
+
+
+
+The maximum number of arguments to a csv function is <code>BOOST_ASSIGN_CSV_SIZE</code>.
+
+
+ <h3><a name="ref-std">Operator <code>+=</code> for standard containers </a> </h3>
+ In the following three dots (...) will mean
+ implementation defined.
+ <code>operator+=()</code> returns a proxy that forwards calls to either
+ <code>push_back()</code>,<code>insert()</code>, or <code>push()</code>
+ depending on which operation the container supports. Synopsis
+ 
+<blockquote>
+<pre>
+namespace boost
+{
+namespace assign
+{
+ template< class V, class A, class V2 >
+ list_inserter< ... > operator+=( std::deque<V,A>& c, V2 v );
+
+ template< class V, class A, class V2 >
+ list_inserter< ... > operator+=( std::list<V,A>& c, V2 v );
+
+ template< class K, class V, class C, class A, class P >
+ list_inserter< ... > operator+=( std::map<K,V,C,A>& m, const P& p );
+
+ template< class K, class V, class C, class A, class P >
+ list_inserter< ... > operator+=( std::multimap<K,V,C,A>& m, const P& p );
+
+ template< class V, class C, class V2 >
+ list_inserter< ... > operator+=( std::queue<V,C>& c, V2 v );
+
+ template< class V, class C, class V2 >
+ list_inserter< ... > operator+=( std::priority_queue<V,C>& c, V2 v );
+
+ template< class K, class C, class A, class K2 >
+ list_inserter< ... > operator+=( std::set<K,C,A>& c, K2 k );
+
+ template< class K, class C, class A, class K2 >
+ list_inserter< ... > operator+=( std::multiset<K,C,A>& c, K2 k );
+
+ #ifdef BOOST_HAS_SLIST
+
+ template< class V, class A, class V2 >
+ list_inserter< ... > operator+=( std::slist<V,A>& c, V2 v );
+
+ #endif
+
+ template< class V, class C, class V2 >
+ list_inserter< ... > operator+=( std::stack<V,C>& c, V2 v );
+
+ template< class V, class A, class V2 >
+ list_inserter< ... > operator+=( std::vector<V,A>& c, V2 v ); 
+
+} // namespace 'assign'
+} // namespace 'boost' </pre></blockquote>
+ Note that the extra template argument <code>V2</code> etc. is
+ necessary to allow for types convertible to <code>V</code>.
+
+ <h3>Functions <code>repeat()</code>,
+ <code>repeat_fun()</code> and <code>range()</code> <a name="ref-repeat_ref"> </h3>
+ 
+ These first two function exist both as free-standing functions and as member functions of the object returned by
+ <code>list_of()</code> and of <code>list_inserter</code>.
+ The free-standing versions are used to create a
+ hook for <code>operator,()</code> so we can call the functions in the middle of a comma-list. The member functions
+ are used when we need to call the functions in the middle of a parenthesis-list. In both cases we have that
+ <ul>
+ <li> the return type is always implementation defined for both functions,
+ <li> the argument list of <code>repeat()</code> is <code>(std::size_t,T)</code>, and
+ <li> the argument list of <code>repeat_fun()</code> is <code>(std::size_t,Nullary_function)</code>
+ </ul>
+
+ 
+ 
+ The function <code>range()</code> only exists as a member function. The following two overloads are provided:
+ <blockquote>
+ <pre>template< class SinglePassIterator >
+Implementation-defined range( SinglePassIterator first, SinglePassIterator last );
+
+template< class SinglePassRange >
+Implementation-defined range( const SinglePassRange& rng );</pre>
+ </blockquote>
+ 
+
+ <h2>Reference for the implementation <a name="ref-impl"> </h2>
+ Proxy objects are those that are returned by <a name="ref-functions">functions<a>, which are
+ 'invisible' to the caller, and take care of the implementation.
+ <h3>Contents</h3>
+
+ <ul>
+ <li> Proxy object converter<> </li>
+ <li> Proxy object generic_list<> </li>
+ <li> Proxy object list_inserter<></li>
+ <li> Proxy object static_generic_list<> </li>
+ <li> Proxy object array_interface<> </li>
+ <li> Proxy object expr<> </li>
+ <li> Proxy object lazy_array<> </li>
+ <li> Proxy object static_array<> </li>
+ </ul>
+
+ <h3>Proxy object <code>converter<></code><a name=ref-converter> </h3>
+ Header <code><boost/assign/list_of.hpp></code>
+
+ 
+ Template parameters
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>D</tt></td><td> A derived class </td> </tr>
+ <tr><td><tt>I</tt></td><td> An iterator </td> </tr>
+ </table>
+ </blockquote>
+
+
+ In the tables below, let <code>d</code> and object of type <code>const D</code>.
+
+ Requirements on the derived type
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Return</th>
+ <tr><td><tt>d.begin()</tt></td> <td>An iterator of type <tt>I</tt></td></tr>
+ <tr><td><tt>d.end()</tt></td><td>An iterator of type <tt>I</tt></td> </tr>
+ </table>
+ </blockquote>
+
+ Requirements on the conversion operands
+
+ There are three concepts that allow for conversion which we call container, adapters, and arrays. Let <code>C</code>,
+ <code>A</code> and <code>R</code> denote models of the respective concepts,
+ and <code>c</code>, <code>a</code> and <code>r</code>, instances thereof. Let <code>b</code> and <code>e</code> denote the begin and end iterators of <code>d</code>,
+ and <tt>n</tt> their distance. Assume that the elements of each of these data-structures
+ are of type <code>X</code>, of which <code>x</code> is and instance, and <code>k</code> any index in the range <tt>[0,n)</tt>.
+
+ Each of <code>c</code>, <code>a</code> and <code>r</code> must be copy constructible. In addition,
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Effect</th>
+ <tr><td><tt>C c(b,e);</tt></td> <td>Constructs an object of type <tt>C</tt></td></tr>
+ <tr><td><tt>a.push(x)</tt></td><td>Adds element <tt>x</tt> to <tt>a</tt></td> </tr>
+ <tr><td><tt>r[k]=x</tt></td><td>Assigns value <tt>x</tt> to the kth element of <tt>r</tt> </tt></td> </tr>
+ </table>
+ </blockquote>
+
+
+ Synopsis
+ <blockquote>
+
+ <pre>
+namespace boost
+{
+namespace assign
+{
+
+ template< class D, class I >
+ class converter
+ {
+ public:
+ typedef I iterator;
+ typedef I const_iterator;
+
+ iterator begin() const;
+
+ iterator end() const;
+
+ template< class Container >
+ Container convert_to_container();
+
+ template< class Container >
+ Container to_container( Container& c );
+
+ adapter_converter to_adapter() const
+
+ template< class Adapter >
+ Adapter to_adapter( Adapter& a ) const
+
+ template< class Array >
+ Array to_array( Array& a ) const;
+ };
+
+ template< class D, class I, class Range >
+ bool operator==( const converter<D,I>& l, const Range& r );
+
+ template< class D, class I, class Range >
+ bool operator==( const Range& l, const converter<D,I>& r );
+
+ template< class D, class I, class Range >
+ bool operator!=( const converter<D,I>& l, const Range& r );
+
+ template< class D, class I, class Range >
+ bool operator!=( const Range& l, const converter<D,I>& r );
+
+ template< class D, class I, class Range >
+ bool operator<( const converter<D,I>& l, const Range& r );
+
+ template< class D, class I, class Range >
+ bool operator<( const Range& l, const converter<D,I>& r );
+
+ template< class D, class I, class Range >
+ bool operator>( const converter<D,I>& l, const Range& r );
+
+ template< class D, class I, class Range >
+ bool operator>( const Range& l, const converter<D,I>& r );
+
+ template< class D, class I, class Range >
+ bool operator<=( const converter<D,I>& l, const Range& r );
+
+ template< class D, class I, class Range >
+ bool operator<=( const Range& l, const converter<D,I>& r );
+
+ template< class D, class I, class Range >
+ bool operator>=( const converter<D,I>& l, const Range& r );
+
+ template< class D, class I, class Range >
+ bool operator>=( const Range& l, const converter<D,I>& r );
+
+ template< class D, class I, class Elem, class Draits >
+ std::basic_ostream<Elem,Traits>&
+ operator<<( std::basic_ostream<Elem, Traits>& Os,
+ const converter<D,I>& r );
+} // namespace 'assign'
+} // namespace 'boost'</pre></blockquote>
+
+ <h3>Proxy object <code>generic_list<></code><a name=ref-generic_list> </h3>
+ 
+ Header <code><boost/assign/list_of.hpp></code>
+ 
+
+ Template parameters
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>T</tt></td> <td>Element</td></tr>
+ </table>
+ </blockquote>
+
+ Associated types
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Description</th>
+ <tr><td><a href="#ref-converter"><tt>converter&lt&gt</tt><a></td> <td>Public base class</td></tr>
+ </table>
+ </blockquote>
+
+ Synopsis
+ <blockquote>
+ <pre>namespace boost 
+{
+namespace assign
+{
+ template< class T >
+ class Implementation-defined
+ {
+ public:
+ const_iterator begin() const;
+ const_iterator end() const;
+
+ template< class U >
+ Implementation-defined& operator,( U u );
+
+ // inserts default-constructed object
+ Implementation-defined& operator()();
+
+ template< class U >
+ Implementation-defined& operator()( U u );
+
+ template< class U, class U2 >
+ Implementation-defined& operator()( U u, U2 u2 );
+
+ //
+ // and similarly up to 5 arguments
+ //
+
+ template< class T >
+ Implementation-defined list_of();
+
+ template< class T >
+ Implementation-defined list_of( T t );
+
+ template< class T, class U, class U2 >
+ Implementation-defined list_of( U u, U2 u2 );
+
+ template< class T, class U, class U2, class U3 >
+ Implementation-defined list_of( U u, U2 u2, U3 u3 );
+
+ template< class T, class U, class U2, class U3, class U4 >
+ Implementation-defined list_of( U u, U2 u2, U3 u3, U4 u4 );
+
+ template< class T, class U, class U2, class U3, class U4, class U5 >
+ Implementation-defined list_of( U u, U2 u2, U3 u3, U4 u4, U5 u5 );
+
+ template< class Key, class T >
+ Implementation-defined map_list_of( Key k, T t )
+ {
+ return list_of< std::pair<Key,T> >()( k, t );
+ }
+} // namespace 'assign'
+} // namespace 'boost' </pre></blockquote>
+
+ <h3>Proxy object <code>static_generic_list<></code><a name=ref-static_generic_list> </h3>
+ Header <code><boost/assign/list_of.hpp></code>
+
+ 
+ Template parameters
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>T</tt></td><td> Element </td> </tr>
+ <tr><td><tt>N</tt></td><td> Size </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Associated types
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Description</th>
+ <tr><td><a href="#ref-converter"><tt>converter&lt&gt</tt><a></td><td> Public base class </td> </tr>
+ </table>
+ </blockquote>
+
+ <h3><a name="ref-list_inserter">Proxy object <code>list_inserter<></code></a></h3>
+
+
+ This class is responsible for inserting elements into containers and
+ it is the key to extending the library to support your favourite class.
+
+
+ Header <code><boost/assign/list_inserter.hpp></code>
+
+
+ 
+ Template parameters
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>Function</tt></td><td> A functor to which insertion is delegated to </td> </tr>
+ <tr><td><tt>Argument</tt></td><td> Argument to be inserted </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Synopsis
+ 
+ <blockquote><pre>
+namespace boost
+{
+namespace assign
+{
+ template< Function, Argument = void >
+ class list_inserter
+ {
+ Function fun;
+
+ public:
+ explicit list_inserter( Function fun );
+
+ // conversion constructor
+ template< class Function2, class Arg >
+ list_inserter( const list_inserter<Function2,Arg>& );
+
+ public:
+ template< class U >
+ list_inserter& operator,( U u );
+
+ template< class U >
+ list_inserter& operator=( U u );
+
+ // calls 'fun()' with default-constructed object
+ list_inserter& operator()();
+
+ template< class U >
+ list_inserter& operator()( U u );
+
+ template< class U, class U2 >
+ list_inserter& operator()( U u, U2 u2 )
+ {
+ //
+ // if 'Argument' is 'void'
+ // fun( u, u2 );
+ // else
+ // fun( Argument( u, u2 ) );
+ //
+ return *this;
+ }
+
+ //
+ // similarly up to 5 arguments
+ //
+ };
+
+ template< class C >
+ list_inserter< ... > push_back( C& );
+
+ template< class C >
+ list_inserter< ... > push_front( C& );
+
+ template< class C >
+ list_inserter< ... > insert( C& );
+
+ template< class C >
+ list_inserter< ... > push( C& );
+
+} // namespace 'assign'
+} // namespace 'boost'</pre></blockquote>
+ 
+ Notice how the arguments to <code>operator,()</code> and
+ <code>operator()()</code> are passed differently to
+ <code>fun</code> depending of the type of <code>Argument</code>.
+ So if we only pass one template argument to <code>list_inserter,</code>
+ we can forward "arbitrary" argument lists of functions. If we pass
+ two template arguments to <code>list_inserter</code> we can
+ construct types with "arbitrary" constructors.
+ 
+
+ 
+ And because
+ a reference to <code>list_inserter</code> is returned, we can
+ chain argument list together in a very space-efficient manner.
+ 
+
+ <h4><a name="ref-array_interface">Proxy object <code>array_interface<></code></a></h4>
+ Exposes most of the <code>boost::array<></code> interface.
+ Header <code><boost/assign/auto_size/array/interface.hpp></code>
+
+ 
+ Template parameters
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>T</tt></td><td> Element </td> </tr>
+ <tr><td><tt>N</tt></td><td> Size </td> </tr>
+ <tr><td><tt>R</tt></td><td> Reference wrapper around an element </td> </tr>
+ <tr><td><tt>D</tt></td><td> Derived </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Requirements
+ 
+ Let <tt>d1</tt> and <tt>d2</tt> instances of <tt>D</tt> and <tt>const D</tt>, respectively,
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Result</th>
+ <tr><td><tt>d1.ref_array_impl()</tt></td><td> array_interface::ref_array_& </td> </tr>
+ <tr><td><tt>d2.ref_array_impl()</tt></td><td> const array_interface::ref_array_& </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Associated types
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Description</th>
+ <tr><td><a href="#ref-converter"><tt>converter&lt&gt</tt><a></td><td> Public base class </td> </tr>
+ </table>
+ </blockquote>
+
+
+ <h3><a name="ref-expr">Proxy object <code>expr<></code></a></h3>
+ 
+ Header <code><boost/assign/auto_size/detail/expr.hpp></code>
+ 
+
+ 
+ Template parameters
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>E</tt></td><td> Previous collection </td> </tr>
+ <tr><td><tt>T</tt></td><td> Element </td> </tr>
+ <tr><td><tt>N</tt></td><td> Size </td> </tr>
+ <tr><td><tt>R</tt></td><td> Reference wrapper around an element </td> </tr>
+ <tr><td><tt>P</tt></td><td> Policy tag</td> </tr>
+ <tr><td><tt>F</tt></td><td> Use reference to link to the previous collection </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Associated types
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Description</th>
+ <tr><td><tt><code>policy::apply<expr,R>::type</code></tt></td><td> Public base class </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Synopsis
+ 
+
+ <blockquote><pre>
+namespace boost
+{
+namespace assign
+{
+namespace detail
+{
+namespace auto_size
+{
+ template<typename E,typename T,int N,
+ template&lttypename> class R,typename P,bool F = true>
+ class expr{
+ public:
+
+ typedef Implementation defined result_type;
+ explicit expr(const E& p,T& t);
+ template<typename E1,typename P1,bool F1>
+ explicit expr(const expr<E1,T,N,R,P1,F1>& that);
+
+ result_type operator()(T& t)const;
+
+ template<int K,typename I>
+ Implementation defined
+ range(I b,I e)const;
+
+ template<int K,typename Range>
+ Implementation defined
+ range(Range& r)const;
+
+ template<int K,typename Range>
+ Implementation defined
+ range(const Range& r)const;
+
+ template<typename Range>
+ Implementation defined
+ range(Range& r);
+
+ template<typename Range>
+ Implementation defined
+ range(const Range& r);
+
+ };
+
+ template<typename A,typename E,typename T,int N,
+ template<typename> class R,typename P,bool F>
+ void write_to_array(A& a,const expr<E,T,N,R,P,F>& e);
+
+
+} // namespace 'auto_size'
+} // namespace 'detail'
+} // namespace 'assign'
+} // namespace 'boost'</pre></blockquote>
+
+ 
+ Issues
+ 
+
+ The purpose of the 'auto-size' the framework is to be able to deduce at compile time the number of arguments in the collection,
+ which is correctly achieved for successive calls to the unary operator of <code>auto_size::expr<></code>. That is not the case, however,
+ for the member function <code>range()</code> (unless the argument has a static size). While this function is nonetheless provided to attain AMAP
+ conformity with the rest of the <a href="http://www.boost.org/doc/libs/1_42_0/libs/assign/index.html">Boost.Assign<a> library, it might be more flexible,
+ in the future, to separate the tools that create collection from individual elements, from those that concatenate collections. It would still be possible,
+ as a convenience, to have <code>auto_size::expr<></code> expose a member function <code>concat()</code>, that forwards to the relevant tool.
+
+ <h3><a name="ref-lazy_array">Proxy object <code>lazy_array<></code></a></h3>
+ Header <code><boost/assign/auto_size/array/lazy.hpp></code>
+
+ 
+ Template parameters
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>T</tt></td><td> Element </td> </tr>
+ <tr><td><tt>N</tt></td><td> Size </td> </tr>
+ <tr><td><tt>R</tt></td><td> Reference wrapper around an element </td> </tr>
+ <tr><td><tt>D</tt></td><td> Derived </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Associated types
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Description</th>
+ <tr><td><a href="#ref-array_interface"><tt>array_interface&lt&gt</tt><a></td><td> Public base class </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Requirements
+ 
+ Let <tt>d</tt> denote an instance of <tt>D</tt> and <tt>a</tt> an instance of <code>boost::array<T,N></code>,
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Effect</th>
+ <tr><td><tt>write_to_array(a,d)</tt></td><td> Assigns <tt>a</tt>'s elements </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Properties
+ 
+ 
+ Postpones allocation of its data-members (from the derived class) until the interface is used.
+ 
+
+
+ <h4><a name="ref-static_array">Proxy object <code>static_array<></code></a></h4>
+ Header <code><boost/assign/auto_size/array/static.hpp></code>
+ 
+ Template parameters
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Parameter</th> <th class="head">Description</th>
+ <tr><td><tt>T</tt></td><td> Element </td> </tr>
+ <tr><td><tt>N</tt></td><td> Size </td> </tr>
+ <tr><td><tt>R</tt></td><td> Reference wrapper around an element </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Associated types
+ 
+
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Description</th>
+ <tr><td><a href="#ref-array_interface"><tt>array_interface&lt&gt</tt><a></td><td> Public base class </td> </tr>
+ </table>
+ </blockquote>
+
+ 
+ Requirements
+ 
+ Let <tt>e</tt> denote the argument passed to the constructor, and a an instance of <code>boost::array<T,N></code>,
+ <blockquote>
+ <table cellpadding=5 border=1>
+ <tr><th class="head">Expression</th> <th class="head">Effect</th>
+ <tr><td><tt>write_to_array(a,e)</tt></td><td> Assigns <tt>a</tt>'s elements </td> </tr>
+ </table>
+ </blockquote>
+
+
+ <h2><a name="exceptions">Exceptions and exception-safety</a></h2>
+ 
+ The exception guarantees by the library is the same as guarantee as the
+ guarantee of the function that is forwarded to. For standard
+ containers this means that the
+ strong guarantee is given for a single insertions and that the basic guarantee
+ is given for many insertions (provided that the object being copied
+ gives the basic guarantee).
+ 
+ 
+ The functions may throw standard exceptions
+ like <code>std::bad_alloc</code>. Note however that, unfortunately, the standard does not guarantee allocation-failures
+ in standard containers to be reported by <code>std::bad_alloc</code> or exceptions derived from <code>std::exception</code>.
+ 
+
+ <h3><a name="assignment_exception">Class
+ <code>assignment_exception</code></a></h3>
+ 
+ The exception is thrown by the conversion operator in the proxy object
+ returned from <code>list_of()</code>.
+ 
+
+ <blockquote><pre>
+namespace boost 
+{
+namespace assign
+{
+ class assignment_exception : public std::exception
+ {
+ public:
+ explicit assignment_exception( const char* what );
+ virtual const char* what() const throw();
+ };
+} 
+} </pre></blockquote>
+
+ <hr>
+ <h2><a name="extensions">Extending the library</a></h2>
+ 
+ It is very simple to make the library work with new classes.
+ This code shows how to use <code>operator+=()</code> with
+ a container:
+ <blockquote><pre>
+template< class V, class A, class V2 >
+inline list_inserter< assign_detail::call_push_back< std::vector<V,A> >, V >
+operator+=( std::vector<V,A>& c, V2 v )
+{
+ return make_list_inserter( assign_detail::call_push_back< std::vector<V,A> >( c ) )( v );
+}
+</pre>
+</blockquote>
+
+
+where <code>call_push_back</code> is defined as
+
+<blockquote>
+<pre>
+template< class C >
+class call_push_back
+{
+ C& c_;
+public:
+
+ call_push_back( C& c ) : c_( c )
+ { }
+
+ template< class T >
+ void operator()( T r )
+ {
+ c_.push_back( r );
+ }
+};</pre>
+</blockquote>
+
+ Note that we pass
+ a second template argument to <code>list_inserter</code> so argument
+ lists will be used to construct a <code>V</code> object. Otherwise we
+ could end up trying to call <code>push_back()</code> with n arguments
+ instead of one.
+ 
+
+ 
+ An alternative way would be to use <code>boost::function</code> and
+ <code>boost::bind()</code> in combination. However, in this case one must
+ remember that it is illegal to take the address of a function in
+ the standard library.
+ 
+
+ 
+ Calling a function with more that one argument can be
+ very useful too. This small example shows how we take advantage of this
+ functionality:
+ 
+ <blockquote><pre>
+//
+// A class representing emails
+//
+class email
+{
+public:
+ enum address_option
+ {
+ check_addr_book,
+ dont_check_addr_book
+ };
+ 
+private:
+
+ typedef std::map< std::string,address_option > address_map;
+
+ //
+ // Store list of persons that must be cc'ed
+ //
+ mutable address_map cc_list;
+
+ //
+ // This extra function-object will take care of the
+ // insertion for us. It stores a reference to a
+ // map and 'operator()()' does the work.
+ //
+ struct add_to_map
+ {
+ address_map& m;
+
+ add_to_map( address_map& m ) : m(m)
+ {}
+
+ void operator()( const std::string& name, address_option ao )
+ {
+ m[ name ] = ao;
+ }
+ };
+
+public:
+
+ //
+ // This function constructs the appropriate 'list_inserter'.
+ // Again we could have use 'boost::function', but it is
+ // trivial to use a function object.
+ //
+ // Notice that we do not specify an extra template
+ // parameter to 'list_inserter'; this means we forward
+ // all parameters directly to the function without
+ // calling any constructor.
+ //
+ list_inserter< add_to_map >
+ add_cc( std::string name, address_option ao )
+ {
+ //
+ // Notice how we pass the arguments 'name' and 'ao' to
+ // the 'list_inserter'.
+ //
+ return make_list_inserter( add_to_map( cc_list ) )( name, ao );
+ }
+};
+
+//
+// Now we can use the class like this:
+//
+email e;
+e.add_cc( "Mr. Foo", email::dont_check_addr_book )
+ ( "Mr. Bar", email::check_addr_book )
+ ( "Mrs. FooBar", email::check_addr_book ); 
+</pre></blockquote>
+
+
+ The full example can be seen in email_example.cpp 
+ <hr>
+ <h2>Examples <a name="examples"></h2>
+ 
+ Additional examples can be found in the test files:
+ <ul>
+ <li> email_example.cpp
+ <li> my_vector_example.cpp
+ <li> multi_index_container.cpp
+ <li> array.cpp
+ <li> list_of.cpp
+ <li> std.cpp
+ <li> list_inserter.cpp
+ <li> list_of_work_around.cpp
+</ul> 
+
+
+ <hr>
+ <h2><a name="boost_libs">Supported libraries</a></h2>
+ Here is a list libraries has been tested with Boost.Assign:
+
+ <ol>
+ <li> <code>boost::array</code>
+ <li> <code>boost::multi_index_container</code>
+ <li> <code>Boost.<a href="../../ptr_container/index.html">Pointer Container</code> </ol> 
+
+ 
+
+
+ <hr>
+ <h2><a name="portability">Portability</a></h2>
+ 
+ Library has been successfully compiled and tested with
+ MVC++ 7.1, GCC 3.2 (under Cygwin) Comeau 4.3.3
+ 
+ 
+ There are known limitation on platforms not supporting templated
+ conversion operators. The solution is to call certain member functions on
+ the object returned by <code>list_of()</code>: 
+ <blockquote>
+ <pre>
+{
+ using namespace std;
+ using namespace boost;
+ using namespace boost::assign;
+
+ vector<int> v = list_of(1)(2)(3)(4).to_container( v );
+ set<int> s = list_of(1)(2)(3)(4).to_container( s );
+ map<int,int> m = map_list_of(1,2)(2,3).to_container( m );
+ stack<int> st = list_of(1)(2)(3)(4).to_adapter( st );
+ queue<int> q = list_of(1)(2)(3)(4).to_adapter( q );
+ array<int,4> a = list_of(1)(2)(3)(4).to_array( a );
+} </pre>
+ </blockquote>
+ 
+ Notice how one must supply the functions with an argument so the right
+ return type can be deduced.
+ 
+ Some standard libraries are also broken. One problem is that
+<code>insert()</code> might not work:
+<blockquote>
+ <pre>
+map<int,int> next;
+insert( next )(1,2)(2,3); // compile-time error </pre>
+</blockquote>
+The solution is to use <code>map_list_of()</code> instead:
+<blockquote>
+ <pre>
+map<int,int> next = map_list_of(1,2)(2,3);</pre></blockquote>
+
+ <hr>
+ <h2><a name="history">History and Acknowledgment</a></h2>
+ 
+ The idea for an assignment/initialization library is not new. The
+ functionality of this
+ library resembles Leor Zolman's STL Container Initialization Library a great
+ deal, but it does not rely on string parsing to achieve its goals.
+ 
+ 
+ The
+ library is non-intrusive and puts only a minimum of requirements
+ on its supported classes.
+ Overloading operator comma is sometimes viewed as a bad practice <a
+href="#meyers">[1]</A>. However, it has been done
+ with success in eg. the Generative Matrix Computation Library and Blitz to initialize matrices
+ (see [2]) and [3]). The
+Initialization Library overloads
+ the comma operator in a safe manner by letting free standing functions
+ return an object that is responsible for the initialization. Therefore it takes
+explicit
+ action from the programmer to begin using the overloaded <code>operator,()</CODE>.
+ 
+ 
+ There has recently been some discussion about enhancing the language to
+support better initialization (see [4]).
+ 
+
+ The auto-size framework for building a collection of references whose size is deduced from the input was added in March 2010.
+ 
+ Special thanks goes to
+ <ul>
+ <li> Leor Zolman for our many discussion that eventually led to this library.
+ <li> Tom Brinkman for being review manager.
+ <li> Joaquín Muñoz for vc6/vc7 portability.
+ <li> Pavel Vozenilek for his countless suggestions, improvements and
+ portability fixes.
+ <li> Rene Rivera for Code Warrior portability.
+ <li> Manuel Peinado Gallego for valuable discussions that led to the auto-size framework.
+ In particular, he identified the need to distinguish between copy and rebind semantics.
+
+ </ul>
+ 
+ <hr>
+ <h2><a name="ref">References</a></h2>
+ 
+ <ol>
+ <li> <a name="meyers"> Scott. Meyers, "More Effective C++", Item 7, Addison Wesley, 1996
+ <li> <a name="gmcl"> K. Czarnecki and U.W. Eisenecker, "Generative programming", Addison-Wesley, 2000
+ <li> <a name="blitz"> http://www.oonumerics.org/blitz/
+ <li> <a name="initializer">
+ Gabriel Dos Reis and Bjarne Stroustrup,
+ <a href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1509.pdf"> "Generalized Initializer
+ Lists"</a>, 2003 </a>
+ </OL>
+ 
+ <hr>
+ 
+ (C) Copyright Thorsten Ottosen 2003-2006
+ 
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+</body>
+</html>

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk