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 - Key extraction</title> <link rel="stylesheet" href="../style.css" type="text/css"> <link rel="start" href="../index.html"> <link rel="prev" href="indices.html"> <link rel="up" href="index.html"> <link rel="next" href="creation.html"> </head> <body> <h1><img src="../../../../boost.png" alt="boost.png (6897 bytes)" align= "middle" width="277" height="86">Boost.MultiIndex Tutorial: Key extraction</h1> <div class="prev_link"><a href="indices.html"><img src="../prev.gif" alt="index types" border="0"> Index types </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="creation.html"><img src="../next.gif" alt="container creation" border="0"> Container creation </a></div> <hr> <h2>Contents</h2> <ul> <li><a href="#intro">Introduction</a> <ul> <li><a href="#read_write_key_extractors">Read/write key extractors</a></li> </ul> </li> <li><a href="#predefined_key_extractors">Predefined key extractors</a> <ul> <li><a href="#identity"><code>identity</code></a></li> <li><a href="#member"><code>member</code></a></li> <li><a href="#const_mem_fun"><code>const_mem_fun</code> and <code>mem_fun</code></a></li> <li><a href="#global_fun"><code>global_fun</code></a></li> </ul> </li> <li><a href="#user_defined_key_extractors">User-defined key extractors</a></li> <li><a href="#composite_keys">Composite keys</a> <ul> <li><a href="#composite_keys_hash">Composite keys and hashed indices</a></li> </ul> </li> <li><a href="#advanced_key_extractors">Advanced features of Boost.MultiIndex key extractors</a></li> </ul> <h2><a name="intro">Introduction</a></h2> STL associative containers have a notion of key, albeit in a somewhat incipient form. So, the keys of such containers are identified by a nested type <code>key_type</code>; for <code>std::set</code>s and <code>std::multiset</code>s, <code>key_type</code> coincides with <code>value_type</code>, i.e. the key is the element itself. <code>std::map</code> and <code>std::multimap</code> manage elements of type <code>std::pair<const Key,T></code>, where the first member is the key. In either case, the process of obtaining the key from a given element is implicitly fixed and cannot be customized by the user. Fixed key extraction mechanisms like those performed by STL associative containers do not scale well in the context of Boost.MultiIndex, where several indices share their <code>value_type</code> definition but might feature completely different lookup semantics. For this reason, Boost.MultiIndex formalizes the concept of a <a href="../reference/key_extraction.html#key_extractors"><code>Key Extractor</code></a> in order to make it explicit and controllable in the definition of key-based indices. Intuitively speaking, a key extractor is a function object that accepts a reference to an element and returns its associated key. The formal concept also imposes some reasonable constraints about the stability of the process, in the sense that extractors are assumed to return the same key when passed the same element: this is in consonance with the informal understanding that keys are actually some "part" of the element and do not depend on external data. <h3><a name="read_write_key_extractors">Read/write key extractors</a></h3> A key extractor is called read/write if it returns a non-constant reference to the key when passed a non-constant element, and it is called read-only otherwise. Boost.MultiIndex requires that the key extractor be read/write when using the <code>modify_key</code> member function of ordered and hashed indices. In all other situations, read-only extractors suffice. The section on <a href="#advanced_key_extractors">advanced features of Boost.MultiIndex key extractors</a> details which of the predefined key extractors are read/write. <h2><a name="predefined_key_extractors">Predefined key extractors</a></h2> <h3><a name="identity"><code>identity</code></a></h3> The <a href="../reference/key_extraction.html#identity"><code>identity</code></a> key extractor returns the entire base object as the associated key: <blockquote><pre> #include <boost/multi_index_container.hpp> #include <boost/multi_index/ordered_index.hpp> #include <boost/multi_index/identity.hpp> multi_index_container< int, indexed_by< ordered_unique< identity<int> // the key is the entire element > > > cont; </pre></blockquote> <h3><a name="member"><code>member</code></a></h3> <a href="../reference/key_extraction.html#member"><code>member</code></a> key extractors return a reference to a specified data field of the base object. For instance, in the following version of our familiar employee container: <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> typedef multi_index_container< employee, indexed_by< ordered_unique<identity<employee> >, ordered_non_unique<member<employee,std::string,&employee::name> >, ordered_unique<member<employee,int,&employee::ssnumber> > > > employee_set; </pre></blockquote> the second and third indices use <code>member</code> extractors on <code>employee::name</code> and <code>employee::ssnumber</code>, respectively. The specification of an instantiation of <code>member</code> is simple yet a little contrived: <blockquote><pre> member<(base type),(key type),(pointer to member)> </pre></blockquote> It might seem that the first and second parameters are superfluous, since the type of the base object and of the associated data field are already implicit in the pointer to member argument: unfortunately, it is not possible to extract this information with current C++ mechanisms, which makes the syntax of <code>member</code> a little too verbose. <h3><a name="const_mem_fun"><code>const_mem_fun</code> and <code>mem_fun</code></a></h3> Sometimes, the key of an index is not a concrete data member of the element, but rather it is a value returned by a particular member function. This resembles the notion of calculated indices supported by some relational databases. Boost.MultiIndex supports this kind of key extraction through <a href="../reference/key_extraction.html#const_mem_fun"><code>const_mem_fun</code></a>. Consider the following container where sorting on the third index is based upon the length of the name field: <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> #include <boost/multi_index/mem_fun.hpp> 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;} // returns the length of the name field std::size_t name_length()const{return name.size();} }; 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 name_length() ordered_non_unique< const_mem_fun<employee,std::size_t,&employee::name_length> > > > employee_set; </pre></blockquote> <code>const_mem_fun</code> usage syntax is similar to that of <a href="#member"><code>member</code></a>: <blockquote><pre> const_mem_fun<(base type),(key type),(pointer to member function)> </pre></blockquote> The member function referred to must be <code>const</code>, take no arguments and return a value of the specified key type. Almost always you will want to use a <code>const</code> member function, since elements in a <code>multi_index_container</code> are treated as constant, much as elements of an <code>std::set</code>. However, a <a href="../reference/key_extraction.html#mem_fun"><code>mem_fun</code></a> counterpart is provided for use with non-constant member functions, whose applicability is discussed on the paragraph on <a href="#advanced_key_extractors">advanced features of Boost.MultiIndex key extractors</a>. <a href="../examples.html#example2">Example 2</a> in the examples section provides a complete program showing how to use <code>const_mem_fun</code>. <h3><a name="global_fun"><code>global_fun</code></a></h3> Whereas <code>const_mem_fun</code> and <code>mem_fun</code> are based on a given member function of the base type from where the key is extracted, <a href="../reference/key_extraction.html#global_fun"><code>global_fun</code></a> takes a global function (or static member function) accepting the base type as its parameter and returning the key: <blockquote><pre> #include <boost/multi_index_container.hpp> #include <boost/multi_index/ordered_index.hpp> #include <boost/multi_index/global_fun.hpp> struct rectangle { int x0,y0; int x1,y1; }; unsigned long area(const rectangle& r) { return (unsigned long)(r.x1-r.x0)*(r.x1-r.x0)+ (unsigned long)(r.y1-r.y0)*(r.y1-r.y0); } typedef multi_index_container< rectangle, indexed_by< // sort by increasing area ordered_non_unique<global_fun<const rectangle&,unsigned long,&area> > > > rectangle_container; </pre></blockquote> The specification of <code>global_fun</code> obeys the following syntax: <blockquote><pre> global_fun<(argument type),(key type),(pointer to function)> </pre></blockquote> where the argument type and key type must match exactly those in the signature of the function used; for instance, in the example above the argument type is <code>const rectangle&</code>, without omitting the "<code>const</code>" and "<code>&</code>" parts. So, although most of the time the base type will be accepted by constant reference, <code>global_fun</code> is also prepared to take functions accepting their argument by value or by non-constant reference: this latter case cannot generally be used directly in the specification of <code>multi_index_container</code>s as their elements are treated as constant, but the section on <a href="#advanced_key_extractors">advanced features of Boost.MultiIndex key extractors</a> describes valid use cases of key extraction based on such functions with a non-constant reference argument. <a href="../examples.html#example2">Example 2</a> in the examples section uses <code>gobal_fun</code>. <h2><a name="user_defined_key_extractors">User-defined key extractors</a></h2> Although the <a href="#predefined_key_extractors">predefined key extractors</a> provided by Boost.MultiIndex are intended to serve most cases, the user can also provide her own key extractors in more exotic situations, as long as these conform to the <a href="../reference/key_extraction.html#key_extractors"><code>Key Extractor</code></a> concept. <blockquote><pre> // some record class struct record { boost::gregorian::date d; std::string str; }; // extracts a record's year struct record_year { // result_type typedef required by Key Extractor concept typedef boost::gregorian::greg_year result_type; result_type operator()(const record& r)const // operator() must be const { return r.d.year(); } }; // example of use of the previous key extractor typedef multi_index_container< record, indexed_by< ordered_non_unique<record_year> // sorted by record's year > > record_log; </pre></blockquote> <a href="../examples.html#example6">Example 6</a> in the examples section applies some user-defined key extractors in a complex scenario where keys are accessed via pointers. <h2><a name="composite_keys">Composite keys</a></h2> In relational databases, composite keys depend on two or more fields of a given table. The analogous concept in Boost.MultiIndex is modeled by means of <a href="../reference/key_extraction.html#composite_key"> <code>composite_key</code></a>, as shown in the example: <blockquote><pre> #include <boost/multi_index_container.hpp> #include <boost/multi_index/ordered_index.hpp> #include <boost/multi_index/member.hpp> #include <boost/multi_index/composite_key.hpp> struct phonebook_entry { std::string family_name; std::string given_name; std::string phone_number; phonebook_entry( std::string family_name, std::string given_name, std::string phone_number): family_name(family_name),given_name(given_name),phone_number(phone_number) {} }; // define a multi_index_container with a composite key on // (family_name,given_name) typedef multi_index_container< phonebook_entry, indexed_by< //non-unique as some subscribers might have more than one number ordered_non_unique< composite_key< phonebook_entry, member<phonebook_entry,std::string,&phonebook_entry::family_name>, member<phonebook_entry,std::string,&phonebook_entry::given_name> > >, ordered_unique< // unique as numbers belong to only one subscriber member<phonebook_entry,std::string,&phonebook_entry::phone_number> > > > phonebook; </pre></blockquote> <code>composite_key</code> accepts two or more key extractors on the same value (here, <code>phonebook_entry</code>). Lookup operations on a composite key are accomplished by passing tuples with the values searched: <blockquote><pre> phonebook pb; ... // search for Dorothea White's number phonebook::iterator it=pb.find(std::make_tuple("White","Dorothea")); std::string number=it->phone_number; </pre></blockquote> Composite keys are sorted by lexicographical order, i.e. sorting is performed by the first key, then the second key if the first one is equal, etc. This order allows for partial searches where only the first keys are specified: <blockquote><pre> phonebook pb; ... // look for all Whites std::pair<phonebook::iterator,phonebook::iterator> p= pb.equal_range(std::make_tuple("White")); </pre></blockquote> As a notational convenience, when only the first key is specified it is possible to pass the argument directly without including it into a tuple: <blockquote><pre> phonebook pb; ... // look for all Whites std::pair<phonebook::iterator,phonebook::iterator> p=pb.equal_range("White"); </pre></blockquote> On the other hand, partial searches without specifying the first keys are not allowed. By default, the corresponding <code>std::less</code> predicate is used for each subkey of a composite key. Alternate comparison predicates can be specified with <a href="../reference/key_extraction.html#composite_key_compare"> <code>composite_key_compare</code></a>: <blockquote><pre> // phonebook with given names in reverse order typedef multi_index_container< phonebook_entry, indexed_by< ordered_non_unique< composite_key< phonebook_entry, member<phonebook_entry,std::string,&phonebook_entry::family_name>, member<phonebook_entry,std::string,&phonebook_entry::given_name> >, composite_key_compare< std::less<std::string>, // family names sorted as by default std::greater<std::string> // given names reversed > >, ordered_unique< member<phonebook_entry,std::string,&phonebook_entry::phone_number> > > > phonebook; </pre></blockquote> See <a href="../examples.html#example7">example 7</a> in the examples section for an application of <code>composite_key</code>. <h3><a name="composite_keys_hash">Composite keys and hashed indices</a></h3> Composite keys can also be used with hashed indices in a straightforward manner: <blockquote><pre> struct street_entry { // quadrant coordinates int x; int y; std::string name; street_entry(int x,int y,const std::string& name):x(x),y(y),name(name){} }; typedef multi_index_container< street_entry, indexed_by< hashed_non_unique< // indexed by quadrant coordinates composite_key< street_entry, member<street_entry,int,&street_entry::x>, member<street_entry,int,&street_entry::y> > >, hashed_non_unique< // indexed by street name member<street_entry,std::string,&street_entry::name> > > > street_locator; street_locator sl; ... void streets_in_quadrant(int x,int y) { std::pair<street_locator::iterator,street_locator::iterator> p= sl.equal_range(std::make_tuple(x,y)); while(p.first!=p.second){ std::cout<<p.first->name<<std::endl; ++p.first; } } </pre></blockquote> Note that hashing is automatically taken care of: <code>boost::hash</code> is specialized to hash a composite key as a function of the <code>boost::hash</code> values of its elements. Should we need to specify different hash functions for the elements of a composite key, we can explicitly do so by using the <a href="../reference/key_extraction.html#composite_key_hash"><code>composite_key_hash</code></a> utility: <blockquote><pre> struct tuned_int_hash { int operator()(int x)const { // specially tuned hash for this application } }; typedef multi_index_container< street_entry, indexed_by< hashed_non_unique< // indexed by quadrant coordinates composite_key< street_entry, member<street_entry,int,&street_entry::x>, member<street_entry,int,&street_entry::y> >, composite_key_hash< tuned_int_hash, tuned_int_hash > >, hashed_non_unique< // indexed by street name member<street_entry,std::string,&street_entry::name> > > > street_locator; </pre></blockquote> Also, equality of composite keys can be tuned with <a href="../reference/key_extraction.html#composite_key_equal_to"><code>composite_key_equal_to</code></a>, though in most cases the default equality predicate (relying on the <code>std::equal_to</code> instantiations for the element types) will be the right choice. Unlike with ordered indices, we cannot perform partial searches specifying only the first elements of a composite key: <blockquote><pre> <span class=commen