boost-react-native-bundle

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0.1 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>Boost.MultiIndex Documentation - Tutorial - Basics</title> <link rel="stylesheet" href="../style.css" type="text/css"> <link rel="start" href="../index.html"> <link rel="prev" href="index.html"> <link rel="up" href="index.html"> <link rel="next" href="indices.html"> </head> <body> <h1><img src="../../../../boost.png" alt="boost.png (6897 bytes)" align= "middle" width="277" height="86">Boost.MultiIndex Tutorial: Basics</h1> <div class="prev_link"><a href="index.html"><img src="../prev.gif" alt="Boost.MultiIndex tutorial" border="0"> Boost.MultiIndex tutorial </a></div> <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.MultiIndex tutorial" border="0"> Boost.MultiIndex tutorial </a></div> <div class="next_link"><a href="indices.html"><img src="../next.gif" alt="index types" border="0"> Index types </a></div> <hr> <h2>Contents</h2> <ul> <li><a href="#intro">Introduction</a> <ul> <li><a href="#multiple_sort">Multiple sorts on a single set</a></li> <li><a href="#list_fast_lookup">A bidirectional list with fast lookup</a></li> </ul> </li> <li><a href="#index_spec">Index specification</a></li> <li><a href="#tagging">Tagging</a></li> <li><a href="#iterator_access">Iterator access</a></li> <li><a href="#index_types">Index types</a> <ul> <li><a href="#ord_indices">Ordered indices</a> <ul> <li><a href="#unique_non_unique">Unique and non-unique variants</a></li> <li><a href="#ord_spec">Specification</a></li> <li><a href="#key_extraction">Key extraction</a></li> <li><a href="#comparison_predicates">Comparison predicates</a></li> <li><a href="#special_lookup">Special lookup operations</a></li> <li><a href="#range">Retrieval of ranges</a></li> <li><a href="#ord_updating">Updating</a></li> </ul> </li> <li><a href="#seq_indices">Sequenced indices</a> <ul> <li><a href="#seq_spec">Specification</a></li> <li><a href="#list_ops">List operations</a></li> <li><a href="#seq_updating">Updating</a></li> </ul> </li> </ul> </li> <li><a href="#projection">Projection of iterators</a></li> <li><a href="#complexity">Complexity and exception safety</a></li> </ul> <h2><a name="intro">Introduction</a></h2> We introduce the main concepts of Boost.MultiIndex through the study of two typical use cases. <h3><a name="multiple_sort">Multiple sorts on a single set</a></h3> STL sets and multisets are varying-length containers where elements are efficiently sorted according to a given comparison predicate. These container classes fall short of functionality when the programmer wishes to efficiently sort and look up the elements following a different sorting criterion. Consider for instance: <blockquote><pre> struct employee { int id; std::string name; employee(int id,const std::string& name):id(id),name(name){} bool operator<(const employee& e)const{return id<e.id;} }; </pre></blockquote> The fact that IDs are unique to each employee is reflected by the way <code>operator<</code> is defined, so a natural data structure for storing of <code>employee</code>s is just a <code>std::set<employee></code>. Now, if one wishes to print out a listing of all employees in alphabetical order, available solutions may have disadvantages either in terms of storage space, complexity or ease of maintenance: <ul> <li>Copy the employee set into a vector or similar and sort this by a comparison functor dependent upon <code>employee::name</code>. <li>Keep a secondary data structure of pointers to the elements of the set, appropriately sorted by name. </ul> Of these, probably the second solution will be the one adopted by most programmers concerned about efficiency, but it imposes the annoying burden of keeping the two structures in sync. If the code is additionally required to be exception-safe, this construct easily becomes unmaintainable. Boost.MultiIndex features <a href="#ord_indices">ordered indices</a>, which sort the elements according to a particular key, and are designed to help programmers in need of sequences of elements for which more than one sorting criteria are relevant. We do so by defining a <code>multi_index_container</code> instantiation composed of several ordered indices: each index, viewed in isolation, behaves much as an ordered <code>std::set</code> (or <code>std::multiset</code>), whilst the overall integrity of the entire data structure is preserved. Our example problem thus can be solved with Boost.MultiIndex as follows: <blockquote><pre> #include <boost/multi_index_container.hpp> #include <boost/multi_index/ordered_index.hpp> #include <boost/multi_index/identity.hpp> #include <boost/multi_index/member.hpp> // define a multiply indexed set with indices by id and name typedef multi_index_container< employee, indexed_by< // sort by employee::operator< ordered_unique<identity<employee> >, // sort by less<string> on name ordered_non_unique<member<employee,std::string,&employee::name> > > > employee_set; void print_out_by_name(const employee_set& es) { // get a view to index #1 (name) const employee_set::nth_index<1>::type& name_index=es.get<1>(); // use name_index as a regular std::set std::copy( name_index.begin(),name_index.end(), std::ostream_iterator<employee>(std::cout)); } </pre></blockquote> Instead of a single comparison predicate type, as it happens for STL associative containers, <code>multi_index_container</code> is passed a <a href="../reference/multi_index_container.html#multi_index_container">list</a> of index specifications (<code>indexed_by</code>), each one inducing the corresponding index. Indices are accessed via <a href="../reference/multi_index_container.html#index_retrieval"><code>get</code></a><code><N>()</code> where N ranges between 0 and the number of comparison predicates minus one. The functionality of index #0 can be accessed directly from a <code>multi_index_container</code> object without using <code>get<0>()</code>: for instance, <code>es.begin()</code> is equivalent to <code>es.get<0>().begin()</code>. Note that <code>get</code> returns a reference to the index, and not an index object. Indices cannot be constructed as separate objects from the container they belong to, so the following <blockquote><pre> // Wrong: we forgot the & after employee_set::nth_index<1>::type const employee_set::nth_index<1>::type name_index=es.get<1>(); </pre></blockquote> does not compile, since it is trying to construct the index object <code>name_index</code>. This is a common source of errors in user code. <h3><a name="list_fast_lookup">A bidirectional list with fast lookup</a></h3> This study case allows us to introduce so-called <a href="#seq_indices">sequenced indices</a>, and how they interact with ordered indices to construct powerful containers. Suppose we have a text parsed into words and stored in a list like this: <blockquote><pre> typedef std::list<std::string> text_container; std::string text= "Alice was beginning to get very tired of sitting by her sister on the " "bank, and of having nothing to do: once or twice she had peeped into the " "book her sister was reading, but it had no pictures or conversations in " "it, 'and what is the use of a book,' thought Alice 'without pictures or " "conversation?'"; // feed the text into the list text_container tc; boost::tokenizer<boost::char_separator<char> > tok (text,boost::char_separator<char>(" \t\n.,;:!?'\"-")); std::copy(tok.begin(),tok.end(),std::back_inserter(tc)); </pre></blockquote> If we want to count the occurrences of a given word into the text we will resort to <code>std::count</code>: <blockquote><pre> std::size_t occurrences(const std::string& word) { return std::count(tc.begin(),tc.end(),word); } </pre></blockquote> But this implementation of <code>occurrences</code> performs in linear time, which could be unacceptable for large quantities of text. Similarly, other operations like deletion of selected words are just too costly to carry out on a <code>std::list</code>: <blockquote><pre> void delete_word(const std::string& word) { tc.remove(word); // scans the entire list looking for word } </pre></blockquote> When performance is a concern, we will need an additional data structure that indexes the elements in <code>tc</code>, presumably in alphabetical order. Boost.MultiIndex does precisely this through the combination of sequenced and ordered indices: <blockquote><pre> #include <boost/multi_index_container.hpp> #include <boost/multi_index/sequenced_index.hpp> #include <boost/multi_index/ordered_index.hpp> #include <boost/multi_index/identity.hpp> // define a multi_index_container with a list-like index and an ordered index typedef multi_index_container< std::string, indexed_by< sequenced<>, // list-like index ordered_non_unique<identity<std::string> > // words by alphabetical order > > text_container; std::string text=... // feed the text into the list text_container tc; boost::tokenizer<boost::char_separator<char> > tok (text,boost::char_separator<char>(" \t\n.,;:!?'\"-")); std::copy(tok.begin(),tok.end(),std::back_inserter(tc)); </pre></blockquote> So far, the substitution of <code>multi_index_container</code> for <code>std::list</code> does not show any advantage. The code for inserting the text into the container does not change as sequenced indices provide an interface similar to that of <code>std::list</code> (no explicit access to this index through <code>get<0>()</code> is needed as <code>multi_index_container</code> inherits the functionality of index #0.) But the specification of an additional ordered index allows us to implement <code>occurrences</code> and <code>delete_word</code> in a much more efficient manner: <blockquote><pre> std::size_t occurrences(const std::string& word) { // get a view to index #1 text_container::nth_index<1>::type& sorted_index=tc.get<1>(); // use sorted_index as a regular std::set return sorted_index.count(word); } void delete_word(const std::string& word) { // get a view to index #1 text_container::nth_index<1>::type& sorted_index=tc.get<1>(); // use sorted_index as a regular std::set sorted_index.erase(word); } </pre></blockquote> Now, <code>occurrences</code> and <code>delete_word</code> have logarithmic complexity. The programmer can use index #0 for accessing the text as with <code>std::list</code>, and use index #1 when logarithmic lookup is needed. <h2> <a name="index_spec">Index specification</a> </h2> The indices of a <code>multi_index_container</code> instantiation are specified by means of the <a href="../reference/indices.html#indexed_by"> <code>indexed_by</code></a> construct. For instance, the instantiation <blockquote><pre> typedef multi_index_container< employee, indexed_by< ordered_unique<identity<employee> >, ordered_non_unique<member<employee,std::string,&employee::name> > > > employee_set; </pre></blockquote> is comprised of a <a href="#unique_non_unique">unique ordered index</a> and a <a href="#unique_non_unique">non-unique ordered index</a>, while in <blockquote><pre> typedef multi_index_container< std::string, indexed_by< sequenced<>, ordered_non_unique<identity<std::string> > > > text_container; </pre></blockquote> we specifiy two indices, the first of <a href="#seq_indices">sequenced type</a>, the second a non-unique <a href="#ord_indices">ordered index</a>. In general, we can specify an arbitrary number of indices: each of the arguments of <code>indexed_by</code> is called an <a href="../reference/indices.html#index_specification">index specifier</a>. Depending on the type of index being specified, the corresponding specifier will need additional information: for instance, the specifiers <code>ordered_unique</code> and <code>ordered_non_unique</code> are provided with a <a href="#key_extraction">key extractor</a> and an optional <a href="#comparison_predicates">comparison predicate</a> which jointly indicate how the sorting of elements will be performed. A <code>multi_index_container</code> instantiation can be declared without supplying the <code>indexed_by</code> part: in this case, default index values are taken so that the resulting type is equivalent to a regular <code>std::set</code>. Concretely, the instantiation <blockquote><pre> multi_index_container<(element)> </pre></blockquote> is equivalent to <blockquote><pre> multi_index_container< (element), indexed_by< ordered_unique<identity<(element)> > > > </pre></blockquote> <h2><a name="tagging">Tagging</a></h2> In order to retrieve (a reference to) an index of a given <code>multi_index_container</code>, the programmer must provide its order number, which is cumbersome and not very self-descriptive. Optionally, indices can be assigned tags (C++ types) that act as more convenient mnemonics. If provided, tags must be passed as the first parameter of the corresponding index specifier. The following is a revised version of <code>employee_set</code> with inclusion of tags: <blockquote><pre> // tags struct name{}; typedef multi_index_container< employee, indexed_by< ordered_unique<identity<employee> >, ordered_non_unique<tag<name>,member<employee,std::string,&employee::name> > > > employee_set; </pre></blockquote> Tags have to be passed inside the <a href="../reference/indices.html#tag"><code>tag</code></a> construct. Any type can be used as a tag for an index, although in general one will choose names that are descriptive of the index they are associated with. The tagging mechanism allows us to write expressions like <blockquote><pre> typedef employee_set::index<name>::type employee_set_by_name; employee_set_by_name::iterator it=es.get<name>().begin(); </pre></blockquote> If no tag is provided for an index (as is the case for index #0 of the previous example), access to that index can only be performed by number. Note the existence of two different <code>typedef</code>s <code>nth_index</code> and <code>index</code> for referring to an index by number and by tag, respectively; for instance, <ul> <li><code>employee_set::nth_index<1>::type</code> is the type of index #1,</li> <li><code>employee_set::index<name>::type</code> is the type of the index tagged with <code>name</code> (the same index #1 in this case.)</li> </ul> <code>get()</code>, on the other hand, is overloaded to serve both styles of access: <blockquote><pre> employee_set::index<name>::type& name_index=es.get<name>(); employee_set::nth_index<1>::type& name_index2=es.get<1>(); // same index </pre></blockquote> Additionally, the <code>tag</code> class template accepts several tags for one index, that we can use interchangeably: for instance, the specification of index #1 in the previous example can be rewritten to hold two different tags <code>name</code> and <code>by_name</code>: <blockquote><pre> // tags struct name{}; struct by_name{}; typedef multi_index_container< ... ordered_non_unique< tag<name,by_name>, member<employee,std::string,&employee::name> > ... > employee_set; </pre></blockquote> <h2><a name="iterator_access">Iterator access</a></h2> Each index of a <code>multi_index_container</code> uses its own iterator types, which are different from those of another indices. As is the rule with STL containers, these iterators are defined as nested types of the index: <blockquote><pre> employee_set::nth_index<1>::type::iterator it= es.get<1>().find("Judy Smith"); </pre></blockquote> This kind of expressions can be rendered more readable by means of user-defined <code>typedef</code>s: <blockquote><pre> typedef employee_set::nth_index<1>::type employee_set_by_name; employee_set_by_name::iterator it= es.get<1>().find("Judy Smith"); </pre></blockquote> <h2> <a name="index_types">Index types</a> </h2> Currently, Boost.MultiIndex provides the following index types: <ul> <li>Ordered indices sort the elements like <code>std::set</code>s do and provide a similar interface. There are unique and non-unique variants: the former do not allow for duplicates, while the latter permit them (like <code>std::multiset</code>.)</li> <li>Sequenced indices are modeled after the semantics and interface of <code>std::list</code>: they arrange the elements as if in a bidirectional list.</li> <li>Hashed indices provide fast access to the elements through hashing tecnhiques, in a similar way as non-standard <code>hash_set</code>s provided by some vendors. Recently, unordered associative containers have been proposed as part of an extension of the C++ standard library known in the standardization commitee as TR1. Hashed indices closely model this proposal.</li> <li>Random access indices provide an interface similar to that of sequenced indices, and additionally feature random access iterators and positional access to the elements.</li> </ul> The examples in the <a href="#intro">introduction</a> exercise ordered and sequenced indices, which are the most commonly used; the other kinds of indices are presented in the <a href="indices.html">index types</a> section of the tutorial. <h3> <a name="ord_indices">Ordered indices</a> </h3> Ordered indices sort the elements in a <code>multi_index_container</code> according to a specified key and an associated comparison predicate. These indices can be viewed as analogues of the standard container <code>std::set</code>, and in fact they do replicate its interface, albeit with some minor differences dictated by the general constraints of Boost.MultiIndex. <h4> <a name="unique_non_unique">Unique and non-unique variants</a> </h4> Ordered indices are classified into unique, which prohibit two elements to have the same key value, and non-unique indices, which allow for duplicates. Consider again the definition <blockquote><pre> typedef multi_index_container< employee, indexed_by< ordered_unique<identity<employee> >, ordered_non_unique<member<employee,std::string,&employee::name> > > > employee_set; </pre></blockquote> In this instantiation of <code>multi_index_container</code>, the first index is to be treated as unique (since IDs are exclusive to each employee) and thus is declared using <code>ordered_unique</code>, whereas the second index is non-unique (as the possibility exists that say two John Smiths are hired in the same company), which is specified by the use of <code>ordered_non_unique</code>. The classification of ordered indices in unique and non-unique has an impact on which elements are allowed to be inserted into a given <code>multi_index_container</code>; briefly put, unique ordered indices mimic the behavior of <code>std::set</code>s while non-unique ordered indices are similar to <code>std::multiset</code>s. For instance, an <code>employee_set</code> can hold the objects <code>employee(0,"George Brown")</code> and <code>employee(1,"George Brown")</code>, but will not accept the insertion of an <code>employee</code> object whose ID coincides with that of some previously inserted employee. More than one unique index can be specified. For instance, if we augment <code>employee</code> to include an additional member for the Social Security number, which is reasonably treated as unique, the following captures this design: <blockquote><pre> struct employee { int id; std::string name; int ssnumber; employee(int id,const std::string& name,int ssnumber): id(id),name(name),ssnumber(ssnumber){} bool operator<(const employee& e)const{return id<e.id;} }; typedef multi_index_container< employee, indexed_by< // sort by employee::operator< ordered_unique<identity<employee> >, // sort by less<string> on name ordered_non_unique<member<employee,std::string,&employee::name> >, // sort by less<int> on ssnumber ordered_unique<member<employee,int,&employee::ssnumber> > > > employee_set; </pre></blockquote> <h4> <a name="ord_spec">Specification</a> </h4> Ordered index specifiers in <code>indexed_by</code> must conform to one of the following syntaxes: <blockquote><pre> (ordered_unique | ordered_non_unique) <[(tag)[,(key extractor)[,(comparison predicate)]]]> (ordered_unique | ordered_non_unique) <[(key extractor)[,(comparison predicate)]]> </pre></blockquote> The first optional argument is used if <a href="#tagging">tags</a> are associated with the index. We now proceed to briefly discuss the remaining arguments of an ordered index specifier. <h4> <a name="key_extraction">Key extraction</a> </h4> The first template parameter (or the second, if tags are supplied) in the specification of an ordered index provides a key extraction predicate. This predicate takes a whole element (in our example, a reference to an <code>employee</code> object) and returns the piece of information by which the sorting is performed. In most cases, one of the following two situations arises: <ul> <li>The whole element serves as the key, as is the case of the first index in <code>employee_set</code>. The predefined <a href="key_extraction.html#identity"><code>identity</code></a> predicate can be used here as a key extractor; <code>identity</code> returns as the key the same object passed as argument.</li> <li>The comparison is performed on a particular data member of the element; this closely follows the specification of indices on a column of a table in relational databases. Boost.MultiIndex provides <a href="key_extraction.html#member"><code>member</code></a>, which returns as the key a member of the element specified by a given pointer.</li> </ul> As an example, consider again the definition of <code>employee_set</code>. The definition of the first index: <blockquote><pre> ordered_unique<identity<employee> > </pre></blockquote> specifies by means of <code>identity</code> that <code>element</code> objects themselves serve as key for this index. On the other ha