forked from boostorg/unordered
Merged revisions 41808-41821,41823-41927,41934-41942,41944-41950,41952-41993,41998-42091,42094-42095,42104-42105,42107,42109,42111-42152,42154,42160-42171,42173-42180,42183-42196,42198-42402 via svnmerge from
https://svn.boost.org/svn/boost/branches/unordered/dev ........ r41993 | danieljames | 2007-12-13 00:23:27 +0000 (Thu, 13 Dec 2007) | 3 lines Add the hash documentation to the unordered library so that it'll be easier to link between the libraries. ........ r42104 | danieljames | 2007-12-16 13:36:50 +0000 (Sun, 16 Dec 2007) | 1 line Don't include any hash source in tarballs (although I'm including the documentation). ........ r42198 | danieljames | 2007-12-20 10:49:10 +0000 (Thu, 20 Dec 2007) | 1 line Restore the extra warnings in the unit tests. ........ r42199 | danieljames | 2007-12-20 11:25:38 +0000 (Thu, 20 Dec 2007) | 1 line Make a cast explicit in order to avoid a warning. ........ r42203 | danieljames | 2007-12-20 15:54:31 +0000 (Thu, 20 Dec 2007) | 1 line Use 'BOOST_UNORDERED' prefix for macros. ........ r42209 | danieljames | 2007-12-20 19:41:17 +0000 (Thu, 20 Dec 2007) | 1 line Initialise this branch (hopefully..) ........ r42210 | danieljames | 2007-12-20 19:51:21 +0000 (Thu, 20 Dec 2007) | 1 line Merge in changes. ........ r42215 | danieljames | 2007-12-20 21:15:42 +0000 (Thu, 20 Dec 2007) | 1 line Don't add size_type to pointers, cast to difference_type. ........ r42216 | danieljames | 2007-12-20 21:17:38 +0000 (Thu, 20 Dec 2007) | 1 line I messed up the last commit, this fixes it. ........ r42218 | danieljames | 2007-12-20 21:22:20 +0000 (Thu, 20 Dec 2007) | 1 line Get rid of last_in_group. ........ r42219 | danieljames | 2007-12-20 21:27:46 +0000 (Thu, 20 Dec 2007) | 1 line Use node_count to implement group_count. ........ r42231 | danieljames | 2007-12-21 12:04:52 +0000 (Fri, 21 Dec 2007) | 1 line Some minor changes for Visual C++. ........ r42233 | danieljames | 2007-12-21 19:41:27 +0000 (Fri, 21 Dec 2007) | 1 line Inline some more methods. ........ r42335 | danieljames | 2007-12-29 13:14:45 +0000 (Sat, 29 Dec 2007) | 3 lines Some of the changes to the introduction mention in the review. Hopefully this will make it a little clearer. ........ r42336 | danieljames | 2007-12-29 13:16:55 +0000 (Sat, 29 Dec 2007) | 3 lines Try to make the buckets explanation a little easier to read. Most of the changes were based on Jamie Allsop (same for the last commit). ........ r42339 | danieljames | 2007-12-29 16:00:32 +0000 (Sat, 29 Dec 2007) | 1 line Specify the namespace for 'std::out_of_range' in the reference documentation. ........ r42345 | danieljames | 2007-12-29 20:41:10 +0000 (Sat, 29 Dec 2007) | 8 lines Rewrite much of the 'controlling the number of buckets' section. I'm trying to make it clearer. It's a bit tricky as the standard doesn't guarantee much. Instead of diving straight into the details I have tried to give the reader a rough idea of what 'rehash' does and what the load factor is. This is hopefully enough to understand the more detailled discussion of how you can control the number of buckets. Then finally I discuss iterator invalidation. ........ r42346 | danieljames | 2007-12-29 20:52:22 +0000 (Sat, 29 Dec 2007) | 1 line Move the table summarizing methods for controlling bucket size next to the discussion of these methods. The paragraphs about insert and invalidating iterator moves on to something else. ........ r42348 | danieljames | 2007-12-29 20:55:30 +0000 (Sat, 29 Dec 2007) | 1 line Fix the badly marked up bullet points. ........ r42349 | danieljames | 2007-12-29 20:57:53 +0000 (Sat, 29 Dec 2007) | 2 lines We now have cbegin and cend for local iterators. ........ [SVN r42403]
This commit is contained in:
1 parent
184a38fee1
commit
e91f6d467b
13 files changed
+190
-171
No files matched your search
+12
-14
@@ -1,17 +1,15 @@
|
||||
project boost/doc ;
|
||||
import boostbook : boostbook ;
|
||||
|
||||
# Copyright 2005 Daniel James.
|
||||
# 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)
|
||||
boostbook doc : src/boost.xml
|
||||
:
|
||||
|
||||
using quickbook ;
|
||||
## Build the various generated docs (Doxygen and QuickBook)...
|
||||
|
||||
xml unordered : unordered.qbk ;
|
||||
boostbook standalone : unordered :
|
||||
<xsl:param>boost.root=../../../..
|
||||
<xsl:param>boost.libraries=../../../libraries.htm
|
||||
<xsl:param>html.stylesheet=../../../../doc/html/boostbook.css
|
||||
<xsl:param>chunk.first.sections=1
|
||||
<xsl:param>chunk.section.depth=2
|
||||
<xsl:param>generate.section.toc.level=2
|
||||
<xsl:param>toc.section.depth=1
|
||||
<xsl:param>toc.max.depth=1 ;
|
||||
<dependency>../libs/unordered/doc//unordered
|
||||
<implicit-dependency>../libs/unordered/doc//unordered
|
||||
<dependency>../libs/functional/hash/doc//hash
|
||||
<implicit-dependency>../libs/functional/hash/doc//hash
|
||||
|
||||
<xsl:param>boost.libraries=../../libs/libraries.htm
|
||||
;
|
||||
+51
-41
@@ -20,17 +20,16 @@ value of type `std::size_t`. `std::size_t` has a much greater range of values
|
||||
then the number of buckets, so that container applies another transformation to
|
||||
that value to choose a bucket to place the element in.
|
||||
|
||||
If at a later date the container wants to find an element in the container it
|
||||
just has to apply the same process to the element's key to discover which
|
||||
bucket it is in. If the hash function has worked well the elements will be
|
||||
evenly distributed amongst the buckets so it will only have to examine a small
|
||||
number of elements.
|
||||
Retreiving the elements for a given key is simple. The same process is applied
|
||||
to the key to find the correct bucket. Then the key is compared with the
|
||||
elements in the bucket to find any elements that match. If the hash
|
||||
function has worked well the elements will be evenly distributed amongst the
|
||||
buckets so only a small number of elements will need to be examined.
|
||||
|
||||
You can see in the diagram that `A` & `D` have been placed in the same bucket.
|
||||
This means that when looking for these elements, of another element that would
|
||||
be placed in the same bucket, up to 2 comparison have to be made, making
|
||||
searching slower. This is known as a collision. To keep things fast we try to
|
||||
keep these to a minimum.
|
||||
When looking for elements in this bucket up to 2 comparisons are made, making
|
||||
the search slower. This is known as a collision. To keep things fast we try to
|
||||
keep collisions to a minimum.
|
||||
|
||||
[table Methods for Accessing Buckets
|
||||
[[Method] [Description]]
|
||||
@@ -57,6 +56,8 @@ keep these to a minimum.
|
||||
local_iterator end(size_type n);
|
||||
const_local_iterator begin(size_type n) const;
|
||||
const_local_iterator end(size_type n) const;
|
||||
const_local_iterator cbegin(size_type n) const;
|
||||
const_local_iterator cend(size_type n) const;
|
||||
``]
|
||||
[Return begin and end iterators for bucket `n`.]
|
||||
]
|
||||
@@ -65,42 +66,31 @@ keep these to a minimum.
|
||||
[h2 Controlling the number of buckets]
|
||||
|
||||
As more elements are added to an unordered associative container, the number
|
||||
of elements in the buckets will increase causing performance to get worse. To
|
||||
combat this the containers increase the bucket count as elements are inserted.
|
||||
of elements in the buckets will increase causing performance to degrade.
|
||||
To combat this the containers increase the bucket count as elements are inserted.
|
||||
You can also tell the container to change the bucket count (if required) by
|
||||
calling `rehash`.
|
||||
|
||||
The standard gives you two methods to influence the bucket count. First you can
|
||||
specify the minimum number of buckets in the constructor, and later, by calling
|
||||
`rehash`.
|
||||
The standard leaves a lot of freedom to the implementor to decide how the
|
||||
number of buckets are chosen, but it does make some requirements based on the
|
||||
container's 'load factor', the average number of elements per bucket.
|
||||
Containers also have a 'maximum load factor' which they should try to keep the
|
||||
load factor below.
|
||||
|
||||
The other method is the `max_load_factor` member function. The 'load factor'
|
||||
is the average number of elements per bucket, `max_load_factor` can be used
|
||||
to give a /hint/ of a value that the load factor should be kept below. The
|
||||
draft standard doesn't actually require the container to pay much attention
|
||||
to this value. The only time the load factor is /required/ to be less than the
|
||||
maximum is following a call to `rehash`. But most implementations will probably
|
||||
try to keep the number of elements below the max load factor, and set the
|
||||
maximum load factor something the same or near to your hint - unless your hint
|
||||
is unreasonably small.
|
||||
You can't control the bucket count directly but there are two ways to
|
||||
influence it:
|
||||
|
||||
It is not specified anywhere how member functions other than `rehash` affect
|
||||
the bucket count, although `insert` is only allowed to invalidate iterators
|
||||
when the insertion causes the load factor to reach the maximum. Which will
|
||||
typically mean that insert will only change the number of buckets when an
|
||||
insert causes this.
|
||||
* Specify the minimum number of buckets when constructing a container or
|
||||
when calling `rehash`.
|
||||
* Suggest a maximum load factor by calling `max_load_factor`.
|
||||
|
||||
In a similar manner to using `reserve` for `vector`s, it can be a good idea
|
||||
to call `rehash` before inserting a large number of elements. This will get
|
||||
the expensive rehashing out of the way and let you store iterators, safe in
|
||||
the knowledge that they won't be invalidated. If you are inserting `n`
|
||||
elements into container `x`, you could first call:
|
||||
|
||||
x.rehash((x.size() + n) / x.max_load_factor() + 1);
|
||||
|
||||
[blurb Note: `rehash`'s argument is the number of buckets, not the number of
|
||||
elements, which is why the new size is divided by the maximum load factor. The
|
||||
+ 1 guarantees there is no invalidation; without it, reallocation could occur
|
||||
if the number of bucket exactly divides the target size, since the container is
|
||||
allowed to rehash when the load factor is equal to the maximum load factor.]
|
||||
`max_load_factor` doesn't let you set the maximum load factor yourself, it just
|
||||
lets you give a /hint/. And even then, the draft standard doesn't actually
|
||||
require the container to pay much attention to this value. The only time the
|
||||
load factor is /required/ to be less than the maximum is following a call to
|
||||
`rehash`. But most implementations will try to keep the number of elements
|
||||
below the max load factor, and set the maximum load factor to be the same as
|
||||
or close to the hint - unless your hint is unreasonably small or large.
|
||||
|
||||
[table Methods for Controlling Bucket Size
|
||||
[[Method] [Description]]
|
||||
@@ -125,4 +115,24 @@ allowed to rehash when the load factor is equal to the maximum load factor.]
|
||||
|
||||
]
|
||||
|
||||
It is not specified how member functions other than `rehash` affect
|
||||
the bucket count, although `insert` is only allowed to invalidate iterators
|
||||
when the insertion causes the load factor to be greater than or equal to the
|
||||
maximum load factor. For most implementations this means that insert will only
|
||||
change the number of buckets when this happens.
|
||||
|
||||
In a similar manner to using `reserve` for `vector`s, it can be a good idea
|
||||
to call `rehash` before inserting a large number of elements. This will get
|
||||
the expensive rehashing out of the way and let you store iterators, safe in
|
||||
the knowledge that they won't be invalidated. If you are inserting `n`
|
||||
elements into container `x`, you could first call:
|
||||
|
||||
x.rehash((x.size() + n) / x.max_load_factor() + 1);
|
||||
|
||||
[blurb Note: `rehash`'s argument is the minimum number of buckets, not the
|
||||
number of elements, which is why the new size is divided by the maximum load factor. The
|
||||
`+ 1` guarantees there is no invalidation; without it, reallocation could occur
|
||||
if the number of bucket exactly divides the target size, since the container is
|
||||
allowed to rehash when the load factor is equal to the maximum load factor.]
|
||||
|
||||
[endsect]
|
||||
+6
-4
@@ -28,11 +28,12 @@ with some care, can be avoided.
|
||||
|
||||
Also, the existing containers require a 'less than' comparison object
|
||||
to order their elements. For some data types this is impossible to implement
|
||||
or isn't practical. For a hash table you need an equality function
|
||||
or isn't practical. In contrast, a hash table only needs an equality function
|
||||
and a hash function for the key.
|
||||
|
||||
So the __tr1__ introduced the unordered associative containers, which are
|
||||
implemented using hash tables, and they have now been added to the __draft__.
|
||||
With this in mind, the __tr1__ introduced the unordered associative containers,
|
||||
which are implemented using hash tables, and they have now been added to the
|
||||
__draft__.
|
||||
|
||||
This library supplies an almost complete implementation of the specification in
|
||||
the __draft__, (it doesn't support `emplace` yet, see the [link
|
||||
@@ -110,6 +111,7 @@ can be in any order. For example, it might be:
|
||||
three,3
|
||||
missing,0
|
||||
|
||||
There are other differences, which will be detailed later.
|
||||
There are other differences, which are listed in the
|
||||
[link unordered.comparison Comparison with Associative Containers] section.
|
||||
|
||||
[endsect]
|
||||
+1
-1
@@ -1718,7 +1718,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
<para>A reference to <code>x.second</code> where <code>x</code> is the (unique) element whose key is equivalent to <code>k</code>.</para>
|
||||
</returns>
|
||||
<throws>
|
||||
<para>An exception object of type <code>out_of_range</code> if no such element is present.</para>
|
||||
<para>An exception object of type <code>std::out_of_range</code> if no such element is present.</para>
|
||||
</throws>
|
||||
<notes>
|
||||
<para>This is not specified in the draft standard, but that is probably an oversight. The issue has been raised in
|
||||
|
||||
+1
-1
@@ -5,5 +5,5 @@
|
||||
<title>The Boost C++ Unordered Containers Library Documentation</title>
|
||||
|
||||
<xi:include href="unordered.xml"/>
|
||||
<!-- <xi:include href="hash.xml"/> -->
|
||||
<xi:include href="hash.xml"/>
|
||||
</boostbook>
|
||||
Reference in new issue
Block a user