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 - Hashed indices reference</title> <link rel="stylesheet" href="../style.css" type="text/css"> <link rel="start" href="../index.html"> <link rel="prev" href="ord_indices.html"> <link rel="up" href="index.html"> <link rel="next" href="seq_indices.html"> </head> <body> <h1><img src="../../../../boost.png" alt="boost.png (6897 bytes)" align= "middle" width="277" height="86">Boost.MultiIndex Hashed indices reference</h1> <div class="prev_link"><a href="ord_indices.html"><img src="../prev.gif" alt="ordered indices" border="0"> Ordered indices </a></div> <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.MultiIndex reference" border="0"> Boost.MultiIndex reference </a></div> <div class="next_link"><a href="seq_indices.html"><img src="../next.gif" alt="sequenced indices" border="0"> Sequenced indices </a></div> <hr> <h2>Contents</h2> <ul> <li><a href="#hash_index_fwd_synopsis">Header <code>"boost/multi_index/hashed_index_fwd.hpp"</code> synopsis</a></li> <li><a href="#synopsis">Header <code>"boost/multi_index/hashed_index.hpp"</code> synopsis</a> <ul> <li><a href="#unique_non_unique"> Index specifiers <code>hashed_unique</code> and <code>hashed_non_unique</code> </a></li> <li><a href="#hash_indices">Hashed indices</a> <ul> <li><a href="#complexity_signature">Complexity signature</a></li> <li><a href="#instantiation_types">Instantiation types</a></li> <li><a href="#types">Nested types</a></li> <li><a href="#constructors">Constructors, copy and assignment</a></li> <li><a href="#iterators">Iterators</a></li> <li><a href="#modifiers">Modifiers</a></li> <li><a href="#observers">Observers</a></li> <li><a href="#lookup">Lookup</a></li> <li><a href="#bucket_interface">Bucket interface</a></li> <li><a href="#hash_policy">Hash policy</a></li> <li><a href="#comparison">Comparison</a></li> <li><a href="#serialization">Serialization</a></li> </ul> </li> </ul> </li> </ul> <h2> <a name="hash_index_fwd_synopsis">Header <a href="../../../../boost/multi_index/hashed_index_fwd.hpp"> <code>"boost/multi_index/hashed_index_fwd.hpp"</code></a> synopsis</a></h2> <blockquote><pre> namespace boost{ namespace multi_index{ // index specifiers hashed_unique and hashed_non_unique template<consult hashed_unique reference for arguments> struct hashed_unique; template<consult hashed_non_unique reference for arguments> struct hashed_non_unique; // indices namespace detail{ template<implementation defined> class index name is implementation defined; } // namespace boost::multi_index::detail } // namespace boost::multi_index } // namespace boost </pre></blockquote> <code>hashed_index_fwd.hpp</code> provides forward declarations for index specifiers <a href="#unique_non_unique"><code>hashed_unique</code> and <code>hashed_non_unique</code></a> and their associated <a href="#hash_indices">hashed index</a> classes. <h2> <a name="synopsis">Header <a href="../../../../boost/multi_index/hashed_index.hpp"> <code>"boost/multi_index/hashed_index.hpp"</code></a> synopsis</a></h2> <blockquote><pre> #include <initializer_list> namespace boost{ namespace multi_index{ // index specifiers hashed_unique and hashed_non_unique template<consult hashed_unique reference for arguments> struct hashed_unique; template<consult hashed_non_unique reference for arguments> struct hashed_non_unique; // indices namespace detail{ template<implementation defined> class index class name implementation defined; // index comparison: // OP is any of ==,!= template<implementation defined> bool operator OP(const index class name& x,const index class name& y); // index specialized algorithms: template<implementation defined> void swap(index class name& x,index class name& y); } // namespace boost::multi_index::detail } // namespace boost::multi_index } // namespace boost </pre></blockquote> <h3><a name="unique_non_unique"> Index specifiers <code>hashed_unique</code> and <code>hashed_non_unique</code> </a></h3> These <a href="indices.html#index_specification">index specifiers</a> allow for insertion of <a href="#hash_indices">hashed indices</a> without and with allowance of duplicate elements, respectively. The syntax of <code>hashed_unique</code> and <code>hashed_non_unique</code> coincide, thus we describe them in a grouped manner. <code>hashed_unique</code> and <code>hashed_non_unique</code> can be instantiated in two different forms, according to whether a tag list for the index is provided or not: <blockquote><pre> template< typename KeyFromValue, typename Hash=boost::hash<KeyFromValue::result_type>, typename Pred=std::equal_to<KeyFromValue::result_type> > struct (hashed_unique | hashed_non_unique); template< typename TagList, typename KeyFromValue, typename Hash=boost::hash<KeyFromValue::result_type>, typename Pred=std::equal_to<KeyFromValue::result_type> > struct (hashed_unique | hashed_non_unique); </pre></blockquote> If provided, <code>TagList</code> must be an instantiation of the class template <a href="indices.html#tag"><code>tag</code></a>. The template arguments are used by the corresponding index implementation, refer to the <a href="#hash_indices">hashed indices</a> reference section for further explanations on their acceptable type values. <h3><a name="hash_indices">Hashed indices</a></h3> A hashed index provides fast retrieval of elements of a <code>multi_index_container</code> through hashing tecnhiques. A hashed index is particularized according to a given <a href="key_extraction.html#key_extractors"><code>Key Extractor</code></a> that retrieves keys from elements of <code>multi_index_container</code>, a <code>Hash</code> function object which returns hash values for the keys and a binary predicate <code>Pred</code> acting as an equivalence relation on values of <code>Key</code>. There are two variants of hashed indices: unique, which do not allow duplicate elements (with respect to its associated equality predicate) and non-unique, which accept those duplicates. The interface of these two variants is the same, so they are documented together, with minor differences explicitly stated when they exist. Except where noted or if the corresponding interface does not exist, hashed indices (both unique and non-unique) satisfy the C++ requirements for undordered associative containers at [unord.req] (supporting unique and equivalent keys, respectively.) Validity of iterators and references to elements is preserved in all cases. Occasionally, the exception safety guarantees provided are actually stronger than required by the standard. We only provide descriptions of those types and operations that do not exactly conform to or are not mandated by the standard requirements. <blockquote><pre> namespace boost{ namespace multi_index{ namespace detail{ template<implementation defined: dependent on types Value, Allocator, TagList, KeyFromValue, Hash, Pred> class name is implementation defined { public: // types: typedef typename KeyFromValue::result_type key_type; typedef Value value_type; typedef KeyFromValue key_from_value; typedef Hash hasher; typedef Pred key_equal; typedef boost::tuple< size_type,key_from_value,hasher,key_equal> ctor_args; typedef TagList tag_list; typedef Allocator allocator_type; typedef typename Allocator::pointer pointer; typedef typename Allocator::const_pointer const_pointer; typedef typename Allocator::reference reference; typedef typename Allocator::const_reference const_reference; typedef implementation defined size_type; typedef implementation defined difference_type; typedef implementation defined iterator; typedef implementation defined const_iterator; typedef implementation defined local_iterator; typedef implementation defined const_local_iterator; // construct/destroy/copy: index class name& operator=(const index class name& x); index class name& operator=(std::initializer_list<value_type> list); allocator_type get_allocator()const noexcept; // size and capacity: bool empty()const noexcept; size_type size()const noexcept; size_type max_size()const noexcept; // iterators: iterator begin()noexcept; const_iterator begin()const noexcept; iterator end()noexcept; const_iterator end()const noexcept; const_iterator cbegin()const; const_iterator cend()const; iterator iterator_to(const value_type& x); const_iterator iterator_to(const value_type& x)const; // modifiers: template<typename... Args> std::pair<iterator,bool> emplace(Args&&... args); template<typename... Args> iterator emplace_hint(iterator position,Args&&... args); std::pair<iterator,bool> insert(const value_type& x); std::pair<iterator,bool> insert(value_type&& x); iterator insert(iterator position,const value_type& x); iterator insert(iterator position,value_type&& x); template<typename InputIterator> void insert(InputIterator first,InputIterator last); void insert(std::initializer_list<value_type> list); iterator erase(iterator position); size_type erase(const key_type& x); iterator erase(iterator first,iterator last); bool replace(iterator position,const value_type& x); bool replace(iterator position,value_type&& x); template<typename Modifier> bool modify(iterator position,Modifier mod); template<typename Modifier,typename Rollback> bool modify(iterator position,Modifier mod,Rollback back); template<typename Modifier> bool modify_key(iterator position,Modifier mod); template<typename Modifier,typename Rollback> bool modify_key(iterator position,Modifier mod,Rollback back); void clear()noexcept; void swap(index class name& x); // observers: key_from_value key_extractor()const; hasher hash_function()const; key_equal key_eq()const; // lookup: template<typename CompatibleKey> iterator find(const CompatibleKey& x)const; template< typename CompatibleKey,typename CompatibleHash, typename CompatiblePred > iterator find( const CompatibleKey& x, const CompatibleHash& hash,const CompatiblePred& eq)const; template<typename CompatibleKey> size_type count(const CompatibleKey& x)const; template< typename CompatibleKey,typename CompatibleHash, typename CompatiblePred > size_type count( const CompatibleKey& x, const CompatibleHash& hash,const CompatiblePred& eq)const; template<typename CompatibleKey> std::pair<iterator,iterator> equal_range(const CompatibleKey& x)const; template< typename CompatibleKey,typename CompatibleHash, typename CompatiblePred > std::pair<iterator,iterator> equal_range( const CompatibleKey& x, const CompatibleHash& hash,const CompatiblePred& eq)const; // bucket interface: size_type bucket_count()const noexcept; size_type max_bucket_count()const noexcept; size_type bucket_size(size_type n)const; size_type bucket(const key_type& k)const; local_iterator begin(size_type n); const_local_iterator begin(size_type n)const; local_iterator end(size_type n); const_local_iterator end(size_type n)const; const_local_iterator cbegin(size_type n)const; const_local_iterator cend(size_type n)const; local_iterator local_iterator_to(const value_type& x); const_local_iterator local_iterator_to(const value_type& x)const; // hash policy: float load_factor()const noexcept; float max_load_factor()const noexcept; void max_load_factor(float z); void rehash(size_type n); void reserve(size_type n); }; // index comparison: template<implementation defined> bool operator==(const index class name& x,const index class name& y); template<implementation defined> bool operator!=(const index class name& x,const index class name& y) { return !(x==y); } // index specialized algorithms: template<implementation defined> void swap(index class name& x,index class name& y); } // namespace boost::multi_index::detail } // namespace boost::multi_index } // namespace boost </pre></blockquote> <h4><a name="complexity_signature">Complexity signature</a></h4> Here and in the descriptions of operations of hashed indices, we adopt the scheme outlined in the <a href="indices.html#complexity_signature">complexity signature section</a>. The complexity signature of hashed indices is: <ul> <li>copying: <code>c(n)=n*log(n)</code>,</li> <li>insertion: average case <code>i(n)=1</code> (amortized constant), worst case <code>i(n)=ndist</code>,</li> <li>hinted insertion: average case <code>h(n)=1</code> (amortized constant), worst case <code>h(n)=ndist</code>,</li> <li>deletion: <code>d(n)=1</code> (constant),</li> <li>replacement: <ul> <li>if the new element key is equivalent to the original, <code>r(n)=1</code> (constant),</li> <li>otherwise, average case <code>r(n)=1</code> (constant), worst case <code>r(n)=ndist</code>,</li> </ul></li> <li>modifying: average case <code>m(n)=1</code> (constant), worst case <code>m(n)=ndist</code>,</li> </ul> where <code>ndist</code> is the number of non-equivalent elements out of the total <code>n</code>. <h4><a name="instantiation_types">Instantiation types</a></h4> Hashed indices are instantiated internally to <code>multi_index_container</code> and specified by means of <a href="indices.html#indexed_by"><code>indexed_by</code></a> with <a href="#unique_non_unique"> index specifiers <code>hashed_unique</code> and <code>hashed_non_unique</code></a>. Instantiations are dependent on the following types: <ul> <li><code>Value</code> from <code>multi_index_container</code>,</li> <li><code>Allocator</code> from <code>multi_index_container</code>,</li> <li><code>TagList</code> from the index specifier (if provided, otherwise <code>tag<></code> is assumed),</li> <li><code>KeyFromValue</code> from the index specifier,</li> <li><code>Hash</code> from the index specifier,</li> <li><code>Pred</code> from the index specifier.</li> </ul> <code>TagList</code> must be an instantiation of <a href="indices.html#tag"><code>tag</code></a>. The type <code>KeyFromValue</code>, which determines the mechanism for extracting a key from <code>Value</code>, must be a model of <a href="key_extraction.html#key_extractors"> <code>Key Extractor</code></a> from <code>Value</code>. <code>Hash</code> is a <code>CopyConstructible</code>unary function object taking a single argument of type <code>KeyFromValue::result_type</code> and returning a value of type <code>std::size_t</code> in the range <code>[0, std::numeric_limits<std::size_t>::max())</code>. <code>Pred</code> is a <code>CopyConstructible</code> binary predicate inducing an equivalence relation on elements of <code>KeyFromValue::result_type</code>. It is required that the <code>Hash</code> object return the same value for keys equivalent under <code>Pred</code>. <h4><a name="types">Nested types</a></h4> <code>ctor_args</code> <blockquote> The first element of this tuple indicates the minimum number of buckets set up by the index on construction time. If the default value 0 is used, an implementation defined number is used instead. </blockquote> <code>iterator const_iterator local_iterator const_local_iterator</code> <blockquote> These types are forward iterators. </blockquote> <h4><a name="constructors">Constructors, copy and assignment</a></h4> As explained in the <a href="indices.html#index_concepts">index concepts section</a>, indices do not have public constructors or destructors. Assignment, on the other hand, is provided. Upon construction, <code>max_load_factor()</code> is 1.0. <code>index class name& operator=(const index class name& x);</code> <blockquote> Effects: <blockquote><pre> a=b; </pre></blockquote> where <code>a</code> and <code>b</code> are the <code>multi_index_container</code> objects to which <code>*this</code> and <code>x</code> belong, respectively. Returns: <code>*this</code>. </blockquote> <code>index class name& operator=(std::initializer_list<value_type> list);</code> <blockquote> Effects: <blockquote><pre> a=list; </pre></blockquote> where <code>a</code> is the <code>multi_index_container</code> object to which <code>*this</code> belongs. Returns: <code>*this</code>. </blockquote> <h4><a name="iterators">Iterators</a></h4> <code>iterator       iterator_to(const value_type& x); const_iterator iterator_to(const value_type& x)const;</code> <blockquote> Requires: <code>x</code> is a reference to an element of the container. Returns: An iterator to <code>x</code>. Complexity: Constant. Exception safety: <code>nothrow</code>. </blockquote> <h4><a name="modifiers">Modifiers</a></h4> <code>template<typename... Args> std::pair<iterator,bool> emplace(Args&&... args);</code> <blockquote> Requires: <code>value_type</code> is <code>EmplaceConstructible</code> into <code>multi_index_container</code> from <code>args</code>. Effects: Inserts a <code>value_type</code> object constructed with <code>std::forward<Args>(args)...</code> into the <code>multi_index_container</code> to which the index belongs if <ul> <li>the index is non-unique OR no other element exists with equivalent key,</li> <li>AND insertion is allowed by all other indices of the <code>multi_index_container</code>.</li> </ul> Returns: The return value is a pair <code>p</code>. <code>p.second</code> is <code>true</code> if and only if insertion took place. On successful insertion, <code>p.first</code> points to the element inserted; otherwise, <code>p.first</code> points to an element that caused the insertion to be banned. Note that more than one element can be causing insertion not to be allowed. Complexity: <code>O(I(n))</code>. Exception safety: Strong, except that rehashing may occur even if the operation fails. </blockquote> <code>template<typename... Args> iterator emplace_hint(iterator position, Args&&... args);</code> <blockquote> Requires: <code>value_type</code> is <code>EmplaceConstructible</code> into <code>multi_index_container</code> from <code>args</code>. <code>position</code> is a valid iterator of the index. Effects: Inserts a <code>value_type</code> object constructed with <code>std::forward<Args>(args)...</code> into the <code>multi_index_container</code> to which the index belongs if <ul> <li>the index is non-unique OR no other element exists with equivalent key,</li> <li>AND insertion is allowed by all other indices of the <code>multi_index_container</code>.</li> </ul> <code>position</code> is used as a hint to improve the efficiency of the operation. Returns: On successful insertion, an iterator to the newly inserted element. Otherwise, an iterator to an element that caused the insertion to be banned. Note that more than one element can be causing insertion not to be allowed. Complexity: <code>O(H(n))</code>. Exception safety: Strong, except that rehashing may occur even if the operation fails. </blockquote> <code>std::pair<iterator,bool> insert(const value_type& x);</code> <code>std::pair<iterator,bool> insert(value_type&& x);</code> <blockquote> Requires (first version): <code>value_type</code> is <code>CopyInsertable</code> into <code>multi_index_container</code>. Requires (second version): <code>value_type</code> is <code>MoveInsertable</code> into <code>multi_index_container</code>. Effects: Inserts <code>x</code> into the <code>multi_index_container</code> to which the index belongs if <ul> <li>the index is non-unique OR no other element exists with equivalent key,</li> <li>AND insertion is allowed by all other indices of the <code>multi_index_container</code>.</li> </ul> Returns: The return value is a pair <code>p</code>. <code>p.second</code> is <code>true</code> if and only if insertion took place. On successful insertion, <code>p.first</code> points to the element inserted; otherwise, <code>p.first</code> points to an element that caused the insertion to be banned. Note that more than one element can be causing insertion not to be allowed. Complexity: <code>O(I(