boost-react-native-bundle

<!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</a>). <h3>Table of Contents</h3> <ul> <li><a href="#intro">Introduction</a></li> <li> <a href="#tutorial" >Tutorial</a> <ul> <li>Function <a href="#operator+="><code>operator+=()</code></a> <li>Function <a href="#operator()"><code>operator()()</code></a> <li>Function <a href="#list_of"><code>list_of()</code></a> <li>Function <a href="#map_list_of"><code>map_list_of()</code></a> <li>Function <a href="#tuple_list_of"><code>tuple_list_of()</code></a> <li>Functions <a href="#repeat"><code>repeat()</code>, <code>repeat_fun()</code> and <code>range()</code> </a> <li>Functions <a href="#ref_list_of"><code>ref_list_of()</code> and <code>cref_list_of()</code></a> <li>A <a href="#complicated">"complicated"</a> example <li>Functions <a href="#ptr_push_back"><code>ptr_push_back(), ptr_push_front()</code>, <code>ptr_insert()</code> and <code>ptr_map_insert()</code></a> <li>Function <a href="#ptr_list_of"><code>ptr_list_of()</code></a> </ul> <li> <a href="#reference">Reference</a> <ul> <li><a href="#headers">Headers</a> </li> <li><a href="#std">Standard containers</a> </li> <li>Functions <a href="#list_of_ref"><code>list_of()</code> and <code>map_list_of()</code></a></li> <li>Functions <a href="#repeat_ref"><code>repeat()</code>, <code>repeat_fun()</code> and <code>range()</code> </a> </li> <li>Class <a href="#list_inserter"><code>list_inserter</code></a></li> <li>Function <a href="#make_list_inserter"><code>make_list_inserter()</code></a></li> <li><a href="#limit"> Customizing</a> argument list sizes</li> </ul> <li> <a href="#exceptions">Exceptions and exception-safety </a></li> <li> <a href="#extensions">Extending the library</a> <li> <a href="#boost_libs">Supported libraries </a> <li> <a href="#examples">Examples</a></li> <ul></ul> <li><a href="#portability">Portability</a></li> <li><a href="#history">History and Acknowledgment</a> <li><a href="#ref">References</a></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 <a href="#operator+="><code>operator+=()</code></a> <li>Function <a href="#operator()"><code>operator()()</code></a> <li>Function <a href="#list_of"><code>list_of()</code></a> <li>Function <a href="#map_list_of"><code>map_list_of()</code></a> <li>Function <a href="#tuple_list_of"><code>tuple_list_of()</code></a> <li>Functions <a href="#repeat"><code>repeat()</code>, <code>repeat_fun()</code> and <code>range()</code> </a> <li>Functions <a href="#ref_list_of"><code>ref_list_of()</code> and <code>cref_list_of()</code></a> <li>A <a href="#complicated">"complicated"</a> example <li>Functions <a href="#ptr_push_back"><code>ptr_push_back(), ptr_push_front()</code>, <code>ptr_insert()</code> and <code>ptr_map_insert()</code></a> <li>Function <a href="#ptr_list_of"><code>ptr_list_of()</code></a> </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 <a href="#limit">customized</a>). 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 <a href="#boost_libs">supported libraries </a>. 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 <a href="../../range/index.html">Boost.Range</a>, 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 l