diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100644 index 00000000..4ae69db4 --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,9 @@ + +# Copyright Daniel James 2005. Use, modification, and distribution are +# subject to the Boost Software License, Version 1.0. (See accompanying +# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +using quickbook ; + +xml unordered : unordered.qbk ; +boostbook standalone : unordered ; diff --git a/doc/comparison.qbk b/doc/comparison.qbk new file mode 100644 index 00000000..b60c5ada --- /dev/null +++ b/doc/comparison.qbk @@ -0,0 +1,67 @@ +[section:comparison Comparison to Associative Containers] + +The unordered associative containers have a very similar interface to the +associative containers. For example: + + #include + + ... + + typedef ``[classref boost::unordered_map]`` map; + map x; + x["one"] = 1; + x["two"] = 2; + x["three"] = 3; + + std::cout<, + typename Pred = std::equal_to, + typename Alloc = std::allocator > + class ``[classref boost::unordered_set unordered_set]``; + +The hash function comes first as you might want to change the hash function +but not the equality predicate, while if you were to change the behaviour +of the equality predicate you would have to change the hash function to match +it. + +For example, if you wanted to use + +[endsect] + +[endsect] diff --git a/doc/intro.qbk b/doc/intro.qbk new file mode 100644 index 00000000..8457b2ff --- /dev/null +++ b/doc/intro.qbk @@ -0,0 +1,34 @@ +[def __tr1__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1745.pdf + C++ Standard Library Technical Report]] +[def __hash-function__ [@http://en.wikipedia.org/wiki/Hash_function + hash function]] + +[section:intro Introduction] + +For accessing data based on keys, the C++ standard library offers `std::set`, +`std::map`, `std::multiset` and `std::multimap`. These are generally +implemented using balanced binary trees so accessing data by key is +consistently of logarithmic complexity. Which is generally okay, but not great. + +Also, they require their elements to be ordered, and to supply a 'less than' +comparison object. For some data types this is impractacle, It might be slow +to calculate, or even impossible. + +So the __tr1__ provides unordered associative containers. These will store data +with no ordering, and typically allow for fast constant time access. Their +worst case complexity is linear, but this is generally rare, and with +care can be avoided. There are four containers to match the existing +associate containers: +[classref boost::unordered_set unordered_set], +[classref boost::unordered_map unordered_map], +[classref boost::unordered_multiset unordered_multiset] and +[classref boost::unordered_multimap unordered_multimap]. + +The fast lookup speeds are acheived using a __hash-function__. The basic idea +is that a function is called for the key value, which is used to index the +data. If this hash function is carefully chosen the different keys will usually +get different indicies, so there will only be a very small number of keys for +each index, so a key lookup won't have to look at many keys to find the correct +one. + +[endsect] diff --git a/doc/ref.xml b/doc/ref.xml new file mode 100644 index 00000000..eb6653ab --- /dev/null +++ b/doc/ref.xml @@ -0,0 +1,3022 @@ + + +
+ + +
+ + + + + + + An unordered associative container that stores unique values. + + + For the normative reference see section 6.3 of + TR1 [n1836]. + + + + Template Parameters + + + + + + Value + + Value must be Assignable and CopyConstructible + + + + + Hash + + A unary function object type that acts a hash function for a + Value. It takes a single argument of type + Value and returns a value of type std::size_t. + + + + + Pred + + A binary function object that implements an equivalence relation on values of type + Value. A binary function object that induces an equivalence relation on values of type Key. It takes two arguments of type Key and returns a value of type bool. + + + + + Alloc + + An allocator whose value type is the same as the container's value type. + + + + + + + The elements are organized into buckets. Keys with the same hash code are stored in the same bucket. + + The number of buckets is automatically increased whenever an insert will make the load factor greater than the maximum load factor. It can also change as result of calling rehash. + + When the number of buckets change: iterators are invalidated, the elements can change order, and move to different buckets, but pointers and references to elements remain valid. + + + + Value + + + Value + + + Hash + + + Pred + + + Alloc + + + typename allocator_type::pointer + + + typename allocator_type::const_pointer + + + typename allocator_type::reference + + lvalue of + value_type. + + + + + typename allocator_type::const_reference + + const lvalue of + value_type. + + + + + implementation-defined + unsigned integral type + + size_type can represent any non-negative value of + difference_type. + + + + + implementation-defined + signed integral type + Is identical to the difference type of + iterator and + const_iterator. + + + + + implementation-defined + + A constant iterator whose value type is + value_type. + + + Any iterator category except output iterator. + + Convertible to + const_iterator. + + + + + + implementation-defined + A constant iterator whose value type is + value_type. + + Any iterator category except output iterator. + + + + + + implementation-defined + An iterator with the same value type, difference type and pointer and reference type as + iterator. + + A local_iterator object can be used to iterate through a single bucket. + + + + implementation-defined + A constant iterator with the same value type, difference type and pointer and reference type as + const_iterator. + + A const_local_iterator object can be used to iterate through a single bucket. + + + + + size_type + implementation-defined + + + hasher const& + hasher() + + + key_equal const& + key_equal() + + + allocator_type const& + allocator_type() + + + size() == 0 + + + Constructs an empty container with at least n buckets, using hf as the hash function, eq as the key equality predicate, a as the allocatorand a maximum load factor of 1.0. + + + + + + + InputIterator + + + InputIterator + + + size_type + implementation-defined + + + hasher const& + hasher() + + + key_equal const& + key_equal() + + + allocator_type const& + allocator_type() + + + Constructs an empty container with at least n buckets, using hf as the hash function, eq as the key equality predicate, a as the allocator and a maximum load factor of 1.0 and inserts the elements from [f, l) into it. + + + + + + unordered_set const& + + + The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + + + + + + + + unordered_set const& + + unordered_set&The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + + + allocator_type + + + + bool + + size() == 0 + + + + size_type + + std::distance(begin(), end()) + + + + size_type + + size() of the largest possible container. + + + + + + iterator + const_iterator + An iterator referring to the first element of the container, or if the container is empty the past-the-end value for the container. + + + + + iterator + + + const_iterator + + An iterator which refers to the past-the-end value for the container. + + + + + + size_type + + std::distance(begin(), end()) + + + + + value_type const& + + std::pair<iterator, bool> + + Inserts obj in the container if and only if there is no element in the container with an equivalent value. + + + + The bool component of the return type is true if an insert took place. + + If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the elment with equivalent value. + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + iterator + + + value_type const& + + iterator + + + + const_iterator + + + value_type const& + + const_iterator + + + Inserts obj in the container if and only if there is no element in the container with an equivalent value. + + hint is a suggestion to where the element should be inserted. + + + + If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the elment with equivalent value. + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same value. + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + InputIterator + + + InputIterator + + void + + Inserts a range of elements into the container. Elements are inserted if and only if there is no element in the container with an equivalent value. + + + + When inserting a single element, if an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + iterator + + iterator + + + + const_iterator + + const_iterator + + + Erase the element pointed to by + position. + + + + The iterator following + position before the erasure. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + They don't get called by the current implementation Boost.Unordered but other implementations may call them. + + + + + + + key_type const& + + size_type + + + Erase all elements with key equivalent to + k. + + + + The number of elements erased. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + + + + + + iterator + + + iterator + + iterator + + + + const_iterator + + + const_iterator + + const_iterator + + + Erases the elements in the range from + first to + last. + + + + The iterator following the erased elements - i.e. + last. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + They don't get called by the current implementation Boost.Unordered but other implementations may call them. + + + + + void + + Erases all elements in the container. + + + + + size() == 0 + + + + Never throws an exception. + + + + + + unordered_set& + + void + + Doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of + key_equal or + hasher. + + + + + + + hasher + The container's hash function. + + + + key_equal + The container's key equality predicate. + + + + + + + + key_type const& + + iterator + + + + key_type const& + + iterator + + + An iterator pointing to an element with key equivalent to + k, or + b.end() if no such element exists. + + + + + + key_type const& + + size_type + + The number of elements with key equivalent to + k. + + + + + + + key_type const& + + std::pair<iterator, iterator> + + + + key_type const& + + std::pair<iterator, iterator> + + + A range with containing all elements with key equivalent to + k. If the container doesn't container any such elements, returns + std::make_pair(b.end(),b.end()). + + + + + + + size_type + + The number of buckets. + + + + + size_type + + An upper bound on the number of buckets. + + + + + + size_type + + size_type + + + n < bucket_count() + + + + + + key_type const& + + size_type + + The index of the bucket which would contain an element with key + k. + + + + The return value is less than + bucket_count() + + + + + + + size_type + + local_iterator + + + + size_type + + const_local_iterator + + + + n shall be in the range + [0, bucket_count()). + + + + A local iterator pointing the first element in the bucket with index + n. + + + + + + + size_type + + local_iterator + + + + size_type + + const_local_iterator + + + + n shall be in the range + [0, bucket_count()). + + + + A local iterator pointing the 'one past the end' element in the bucket with index + n. + + + + + + + float + + The average number of elements per bucket. + + + + + float + + Returns the current maximum load factor. + + + + + + float + + float + + Changes the container's maximum load factor,using + z as a hint. + + + + + + size_type + + void + + Changes the number of buckets so that there at least + n buckets, and so that the load factor is less thanthe maximum load factor. + + Invalidates iterators, and changes the order of elements + + + + The function has no effect if an exception is throw, unless it is thrown by the container’s hash function or comparison function. + + + + + + + + + unordered_set<Key, T, Hash, Pred, Alloc>& + + + unordered_set<Key, T, Hash, Pred, Alloc>& + + void + + x.swap(y) + + + + Doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of + Hash or + Pred. + + + + + + + + + An unordered associative container that stores values. The same key can be stored multiple times. + + + For the normative reference see section 6.3 of + TR1 [n1836]. + + + + Template Parameters + + + + + + Value + + Value must be Assignable and CopyConstructible + + + + + Hash + + A unary function object type that acts a hash function for a + Value. It takes a single argument of type + Value and returns a value of type std::size_t. + + + + + Pred + + A binary function object that implements an equivalence relation on values of type + Value. A binary function object that induces an equivalence relation on values of type Key. It takes two arguments of type Key and returns a value of type bool. + + + + + Alloc + + An allocator whose value type is the same as the container's value type. + + + + + + + The elements are organized into buckets. Keys with the same hash code are stored in the same bucket and elements with equivalent keys are stored next to each other. + + The number of buckets is automatically increased whenever an insert will make the load factor greater than the maximum load factor. It can also change as result of calling rehash. + + When the number of buckets change: iterators are invalidated, the elements can change order, and move to different buckets, but pointers and references to elements remain valid. + + + + Value + + + Value + + + Hash + + + Pred + + + Alloc + + + typename allocator_type::pointer + + + typename allocator_type::const_pointer + + + typename allocator_type::reference + + lvalue of + value_type. + + + + + typename allocator_type::const_reference + + const lvalue of + value_type. + + + + + implementation-defined + unsigned integral type + + size_type can represent any non-negative value of + difference_type. + + + + + implementation-defined + signed integral type + Is identical to the difference type of + iterator and + const_iterator. + + + + + implementation-defined + + A constant iterator whose value type is + value_type. + + + Any iterator category except output iterator. + + Convertible to + const_iterator. + + + + + + implementation-defined + A constant iterator whose value type is + value_type. + + Any iterator category except output iterator. + + + + + + implementation-defined + An iterator with the same value type, difference type and pointer and reference type as + iterator. + + A local_iterator object can be used to iterate through a single bucket. + + + + implementation-defined + A constant iterator with the same value type, difference type and pointer and reference type as + const_iterator. + + A const_local_iterator object can be used to iterate through a single bucket. + + + + + size_type + implementation-defined + + + hasher const& + hasher() + + + key_equal const& + key_equal() + + + allocator_type const& + allocator_type() + + + size() == 0 + + + Constructs an empty container with at least n buckets, using hf as the hash function, eq as the key equality predicate, a as the allocatorand a maximum load factor of 1.0. + + + + + + + InputIterator + + + InputIterator + + + size_type + implementation-defined + + + hasher const& + hasher() + + + key_equal const& + key_equal() + + + allocator_type const& + allocator_type() + + + Constructs an empty container with at least n buckets, using hf as the hash function, eq as the key equality predicate, a as the allocator and a maximum load factor of 1.0 and inserts the elements from [f, l) into it. + + + + + + unordered_multiset const& + + + The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + + + + + + + + unordered_multiset const& + + unordered_multiset&The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + + + allocator_type + + + + bool + + size() == 0 + + + + size_type + + std::distance(begin(), end()) + + + + size_type + + size() of the largest possible container. + + + + + + iterator + const_iterator + An iterator referring to the first element of the container, or if the container is empty the past-the-end value for the container. + + + + + iterator + + + const_iterator + + An iterator which refers to the past-the-end value for the container. + + + + + + size_type + + std::distance(begin(), end()) + + + + + value_type const& + + iterator + + Inserts obj in the container. + + + + An iterator pointing to the inserted element. + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + iterator + + + value_type const& + + iterator + + + + const_iterator + + + value_type const& + + const_iterator + + + Inserts obj in the container. + + hint is a suggestion to where the element should be inserted. + + + + An iterator pointing to the inserted element. + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same value. + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + InputIterator + + + InputIterator + + void + + Inserts a range of elements into the container. + + + + When inserting a single element, if an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + iterator + + iterator + + + + const_iterator + + const_iterator + + + Erase the element pointed to by + position. + + + + The iterator following + position before the erasure. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + They don't get called by the current implementation Boost.Unordered but other implementations may call them. + + + + + + + key_type const& + + size_type + + + Erase all elements with key equivalent to + k. + + + + The number of elements erased. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + + + + + + iterator + + + iterator + + iterator + + + + const_iterator + + + const_iterator + + const_iterator + + + Erases the elements in the range from + first to + last. + + + + The iterator following the erased elements - i.e. + last. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + They don't get called by the current implementation Boost.Unordered but other implementations may call them. + + + + + void + + Erases all elements in the container. + + + + + size() == 0 + + + + Never throws an exception. + + + + + + unordered_multiset& + + void + + Doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of + key_equal or + hasher. + + + + + + + hasher + The container's hash function. + + + + key_equal + The container's key equality predicate. + + + + + + + + key_type const& + + iterator + + + + key_type const& + + iterator + + + An iterator pointing to an element with key equivalent to + k, or + b.end() if no such element exists. + + + + + + key_type const& + + size_type + + The number of elements with key equivalent to + k. + + + + + + + key_type const& + + std::pair<iterator, iterator> + + + + key_type const& + + std::pair<iterator, iterator> + + + A range with containing all elements with key equivalent to + k. If the container doesn't container any such elements, returns + std::make_pair(b.end(),b.end()). + + + + + + + size_type + + The number of buckets. + + + + + size_type + + An upper bound on the number of buckets. + + + + + + size_type + + size_type + + + n < bucket_count() + + + + + + key_type const& + + size_type + + The index of the bucket which would contain an element with key + k. + + + + The return value is less than + bucket_count() + + + + + + + size_type + + local_iterator + + + + size_type + + const_local_iterator + + + + n shall be in the range + [0, bucket_count()). + + + + A local iterator pointing the first element in the bucket with index + n. + + + + + + + size_type + + local_iterator + + + + size_type + + const_local_iterator + + + + n shall be in the range + [0, bucket_count()). + + + + A local iterator pointing the 'one past the end' element in the bucket with index + n. + + + + + + + float + + The average number of elements per bucket. + + + + + float + + Returns the current maximum load factor. + + + + + + float + + float + + Changes the container's maximum load factor,using + z as a hint. + + + + + + size_type + + void + + Changes the number of buckets so that there at least + n buckets, and so that the load factor is less thanthe maximum load factor. + + Invalidates iterators, and changes the order of elements + + + + The function has no effect if an exception is throw, unless it is thrown by the container’s hash function or comparison function. + + + + + + + + + unordered_multiset<Key, T, Hash, Pred, Alloc>& + + + unordered_multiset<Key, T, Hash, Pred, Alloc>& + + void + + x.swap(y) + + + + Doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of + Hash or + Pred. + + + + +
+ + +
+ + + + + + + An unordered associative container that associates unique keys with another value. + + + For the normative reference see section 6.3 of + TR1 [n1836]. + + + + Template Parameters + + + + + + Key + + Key must be Assignable and CopyConstructible. + + + + + T + + T must be CopyConstructible + + + + + Hash + + A unary function object type that acts a hash function for a + Key. It takes a single argument of type + Key and returns a value of type std::size_t. + + + + + Pred + + A binary function object that implements an equivalence relation on values of type + Key. A binary function object that induces an equivalence relation on values of type Key. It takes two arguments of type Key and returns a value of type bool. + + + + + Alloc + + An allocator whose value type is the same as the container's value type. + + + + + + + The elements are organized into buckets. Keys with the same hash code are stored in the same bucket. + + The number of buckets is automatically increased whenever an insert will make the load factor greater than the maximum load factor. It can also change as result of calling rehash. + + When the number of buckets change: iterators are invalidated, the elements can change order, and move to different buckets, but pointers and references to elements remain valid. + + + + Key + + + std::pair<Key const, Value> + + + T + + + Hash + + + Pred + + + Alloc + + + typename allocator_type::pointer + + + typename allocator_type::const_pointer + + + typename allocator_type::reference + + lvalue of + value_type. + + + + + typename allocator_type::const_reference + + const lvalue of + value_type. + + + + + implementation-defined + unsigned integral type + + size_type can represent any non-negative value of + difference_type. + + + + + implementation-defined + signed integral type + Is identical to the difference type of + iterator and + const_iterator. + + + + + implementation-defined + + A iterator whose value type is + value_type. + + + Any iterator category except output iterator. + + Convertible to + const_iterator. + + + + + + implementation-defined + A constant iterator whose value type is + value_type. + + Any iterator category except output iterator. + + + + + + implementation-defined + An iterator with the same value type, difference type and pointer and reference type as + iterator. + + A local_iterator object can be used to iterate through a single bucket. + + + + implementation-defined + A constant iterator with the same value type, difference type and pointer and reference type as + const_iterator. + + A const_local_iterator object can be used to iterate through a single bucket. + + + + + size_type + implementation-defined + + + hasher const& + hasher() + + + key_equal const& + key_equal() + + + allocator_type const& + allocator_type() + + + size() == 0 + + + Constructs an empty container with at least n buckets, using hf as the hash function, eq as the key equality predicate, a as the allocatorand a maximum load factor of 1.0. + + + + + + + InputIterator + + + InputIterator + + + size_type + implementation-defined + + + hasher const& + hasher() + + + key_equal const& + key_equal() + + + allocator_type const& + allocator_type() + + + Constructs an empty container with at least n buckets, using hf as the hash function, eq as the key equality predicate, a as the allocator and a maximum load factor of 1.0 and inserts the elements from [f, l) into it. + + + + + + unordered_map const& + + + The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + + + + + + + + unordered_map const& + + unordered_map&The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + + + allocator_type + + + + bool + + size() == 0 + + + + size_type + + std::distance(begin(), end()) + + + + size_type + + size() of the largest possible container. + + + + + + iterator + const_iterator + An iterator referring to the first element of the container, or if the container is empty the past-the-end value for the container. + + + + + iterator + + + const_iterator + + An iterator which refers to the past-the-end value for the container. + + + + + + size_type + + std::distance(begin(), end()) + + + + + value_type const& + + std::pair<iterator, bool> + + Inserts obj in the container if and only if there is no element in the container with an equivalent key. + + + + The bool component of the return type is true if an insert took place. + + If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the elment with equivalent key. + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + iterator + + + value_type const& + + iterator + + + + const_iterator + + + value_type const& + + const_iterator + + + Inserts obj in the container if and only if there is no element in the container with an equivalent key. + + hint is a suggestion to where the element should be inserted. + + + + If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the elment with equivalent key. + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + InputIterator + + + InputIterator + + void + + Inserts a range of elements into the container. Elements are inserted if and only if there is no element in the container with an equivalent key. + + + + When inserting a single element, if an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + iterator + + iterator + + + + const_iterator + + const_iterator + + + Erase the element pointed to by + position. + + + + The iterator following + position before the erasure. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + They don't get called by the current implementation Boost.Unordered but other implementations may call them. + + + + + + + key_type const& + + size_type + + + Erase all elements with key equivalent to + k. + + + + The number of elements erased. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + + + + + + iterator + + + iterator + + iterator + + + + const_iterator + + + const_iterator + + const_iterator + + + Erases the elements in the range from + first to + last. + + + + The iterator following the erased elements - i.e. + last. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + They don't get called by the current implementation Boost.Unordered but other implementations may call them. + + + + + void + + Erases all elements in the container. + + + + + size() == 0 + + + + Never throws an exception. + + + + + + unordered_map& + + void + + Doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of + key_equal or + hasher. + + + + + + + hasher + The container's hash function. + + + + key_equal + The container's key equality predicate. + + + + + + + + key_type const& + + iterator + + + + key_type const& + + iterator + + + An iterator pointing to an element with key equivalent to + k, or + b.end() if no such element exists. + + + + + + key_type const& + + size_type + + The number of elements with key equivalent to + k. + + + + + + + key_type const& + + std::pair<iterator, iterator> + + + + key_type const& + + std::pair<iterator, iterator> + + + A range with containing all elements with key equivalent to + k. If the container doesn't container any such elements, returns + std::make_pair(b.end(),b.end()). + + + + + + key_type const& + + mapped_type& + + If the container does not already contain an elements with a key equivalent to + k, inserts the value std::pair<key_type const, mapped_type>(k, mapped_type()) + + + + A reference to x.second where x is the element already in the container, or the newly inserted element with a key equivalent to + k + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + size_type + + The number of buckets. + + + + + size_type + + An upper bound on the number of buckets. + + + + + + size_type + + size_type + + + n < bucket_count() + + + + + + key_type const& + + size_type + + The index of the bucket which would contain an element with key + k. + + + + The return value is less than + bucket_count() + + + + + + + size_type + + local_iterator + + + + size_type + + const_local_iterator + + + + n shall be in the range + [0, bucket_count()). + + + + A local iterator pointing the first element in the bucket with index + n. + + + + + + + size_type + + local_iterator + + + + size_type + + const_local_iterator + + + + n shall be in the range + [0, bucket_count()). + + + + A local iterator pointing the 'one past the end' element in the bucket with index + n. + + + + + + + float + + The average number of elements per bucket. + + + + + float + + Returns the current maximum load factor. + + + + + + float + + float + + Changes the container's maximum load factor,using + z as a hint. + + + + + + size_type + + void + + Changes the number of buckets so that there at least + n buckets, and so that the load factor is less thanthe maximum load factor. + + Invalidates iterators, and changes the order of elements + + + + The function has no effect if an exception is throw, unless it is thrown by the container’s hash function or comparison function. + + + + + + + + + unordered_map<Key, T, Hash, Pred, Alloc>& + + + unordered_map<Key, T, Hash, Pred, Alloc>& + + void + + x.swap(y) + + + + Doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of + Hash or + Pred. + + + + + + + + + An unordered associative container that associates keys with another value. The same key can be stored multiple times. + + + For the normative reference see section 6.3 of + TR1 [n1836]. + + + + Template Parameters + + + + + + Key + + Key must be Assignable and CopyConstructible. + + + + + T + + T must be CopyConstructible + + + + + Hash + + A unary function object type that acts a hash function for a + Key. It takes a single argument of type + Key and returns a value of type std::size_t. + + + + + Pred + + A binary function object that implements an equivalence relation on values of type + Key. A binary function object that induces an equivalence relation on values of type Key. It takes two arguments of type Key and returns a value of type bool. + + + + + Alloc + + An allocator whose value type is the same as the container's value type. + + + + + + + The elements are organized into buckets. Keys with the same hash code are stored in the same bucket and elements with equivalent keys are stored next to each other. + + The number of buckets is automatically increased whenever an insert will make the load factor greater than the maximum load factor. It can also change as result of calling rehash. + + When the number of buckets change: iterators are invalidated, the elements can change order, and move to different buckets, but pointers and references to elements remain valid. + + + + Key + + + std::pair<Key const, Value> + + + T + + + Hash + + + Pred + + + Alloc + + + typename allocator_type::pointer + + + typename allocator_type::const_pointer + + + typename allocator_type::reference + + lvalue of + value_type. + + + + + typename allocator_type::const_reference + + const lvalue of + value_type. + + + + + implementation-defined + unsigned integral type + + size_type can represent any non-negative value of + difference_type. + + + + + implementation-defined + signed integral type + Is identical to the difference type of + iterator and + const_iterator. + + + + + implementation-defined + + A iterator whose value type is + value_type. + + + Any iterator category except output iterator. + + Convertible to + const_iterator. + + + + + + implementation-defined + A constant iterator whose value type is + value_type. + + Any iterator category except output iterator. + + + + + + implementation-defined + An iterator with the same value type, difference type and pointer and reference type as + iterator. + + A local_iterator object can be used to iterate through a single bucket. + + + + implementation-defined + A constant iterator with the same value type, difference type and pointer and reference type as + const_iterator. + + A const_local_iterator object can be used to iterate through a single bucket. + + + + + size_type + implementation-defined + + + hasher const& + hasher() + + + key_equal const& + key_equal() + + + allocator_type const& + allocator_type() + + + size() == 0 + + + Constructs an empty container with at least n buckets, using hf as the hash function, eq as the key equality predicate, a as the allocatorand a maximum load factor of 1.0. + + + + + + + InputIterator + + + InputIterator + + + size_type + implementation-defined + + + hasher const& + hasher() + + + key_equal const& + key_equal() + + + allocator_type const& + allocator_type() + + + Constructs an empty container with at least n buckets, using hf as the hash function, eq as the key equality predicate, a as the allocator and a maximum load factor of 1.0 and inserts the elements from [f, l) into it. + + + + + + unordered_multimap const& + + + The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + + + + + + + + unordered_multimap const& + + unordered_multimap&The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + + + allocator_type + + + + bool + + size() == 0 + + + + size_type + + std::distance(begin(), end()) + + + + size_type + + size() of the largest possible container. + + + + + + iterator + const_iterator + An iterator referring to the first element of the container, or if the container is empty the past-the-end value for the container. + + + + + iterator + + + const_iterator + + An iterator which refers to the past-the-end value for the container. + + + + + + size_type + + std::distance(begin(), end()) + + + + + value_type const& + + iterator + + Inserts obj in the container. + + + + An iterator pointing to the inserted element. + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + iterator + + + value_type const& + + iterator + + + + const_iterator + + + value_type const& + + const_iterator + + + Inserts obj in the container. + + hint is a suggestion to where the element should be inserted. + + + + An iterator pointing to the inserted element. + + + + If an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + InputIterator + + + InputIterator + + void + + Inserts a range of elements into the container. + + + + When inserting a single element, if an exception is thrown by an operation other than a call to + hasher the function has no effect. + + + + Will only rehash if the insert causes the load factor to be greater to or equal to the maximum load factor. + + + + + + + iterator + + iterator + + + + const_iterator + + const_iterator + + + Erase the element pointed to by + position. + + + + The iterator following + position before the erasure. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + They don't get called by the current implementation Boost.Unordered but other implementations may call them. + + + + + + + key_type const& + + size_type + + + Erase all elements with key equivalent to + k. + + + + The number of elements erased. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + + + + + + iterator + + + iterator + + iterator + + + + const_iterator + + + const_iterator + + const_iterator + + + Erases the elements in the range from + first to + last. + + + + The iterator following the erased elements - i.e. + last. + + + + Only throws an exception, if it is thrown by a call to + hasher or + key_equal. + + They don't get called by the current implementation Boost.Unordered but other implementations may call them. + + + + + void + + Erases all elements in the container. + + + + + size() == 0 + + + + Never throws an exception. + + + + + + unordered_multimap& + + void + + Doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of + key_equal or + hasher. + + + + + + + hasher + The container's hash function. + + + + key_equal + The container's key equality predicate. + + + + + + + + key_type const& + + iterator + + + + key_type const& + + iterator + + + An iterator pointing to an element with key equivalent to + k, or + b.end() if no such element exists. + + + + + + key_type const& + + size_type + + The number of elements with key equivalent to + k. + + + + + + + key_type const& + + std::pair<iterator, iterator> + + + + key_type const& + + std::pair<iterator, iterator> + + + A range with containing all elements with key equivalent to + k. If the container doesn't container any such elements, returns + std::make_pair(b.end(),b.end()). + + + + + + + size_type + + The number of buckets. + + + + + size_type + + An upper bound on the number of buckets. + + + + + + size_type + + size_type + + + n < bucket_count() + + + + + + key_type const& + + size_type + + The index of the bucket which would contain an element with key + k. + + + + The return value is less than + bucket_count() + + + + + + + size_type + + local_iterator + + + + size_type + + const_local_iterator + + + + n shall be in the range + [0, bucket_count()). + + + + A local iterator pointing the first element in the bucket with index + n. + + + + + + + size_type + + local_iterator + + + + size_type + + const_local_iterator + + + + n shall be in the range + [0, bucket_count()). + + + + A local iterator pointing the 'one past the end' element in the bucket with index + n. + + + + + + + float + + The average number of elements per bucket. + + + + + float + + Returns the current maximum load factor. + + + + + + float + + float + + Changes the container's maximum load factor,using + z as a hint. + + + + + + size_type + + void + + Changes the number of buckets so that there at least + n buckets, and so that the load factor is less thanthe maximum load factor. + + Invalidates iterators, and changes the order of elements + + + + The function has no effect if an exception is throw, unless it is thrown by the container’s hash function or comparison function. + + + + + + + + + unordered_multimap<Key, T, Hash, Pred, Alloc>& + + + unordered_multimap<Key, T, Hash, Pred, Alloc>& + + void + + x.swap(y) + + + + Doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of + Hash or + Pred. + + + + +
+
+ diff --git a/doc/unordered.qbk b/doc/unordered.qbk new file mode 100644 index 00000000..5470b07d --- /dev/null +++ b/doc/unordered.qbk @@ -0,0 +1,18 @@ +[library Unordered Associative Containers + [quickbook 1.3] + [authors [Maitin-Shepard, Jeremy B.], [James, Daniel]] + [copyright 2005 Daniel James] + [purpose std::tr1 compliant hash containers] + [id unordered] + [dirname unordered] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt] + ] +] + +[include:unordered intro.qbk] +[include:unordered comparison.qbk] + +[xinclude ref.xml]