unordered/doc/buckets.qbk

[section:buckets The Data Structure]

The containers are made up of a number of 'buckets', each of which can contain
any number of elements. For example, the following diagram shows an [classref
boost::unordered_set unordered_set] with 7 buckets containing 5 elements, `A`,
`B`, `C`, `D` and `E` (this is just for illustration, in practise containers
will have more buckets).

[$../diagrams/buckets.png]

In order to decide which bucket to place an element in, the container applies
`Hash` to the element's key (for `unordered_set` and `unordered_multiset` the
key is the whole element, but this refered to as the key so that the same
terminology can be used for sets and maps). This gives a `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 to find it in. This means that you only have to look at the elements
within a single bucket. If the hash function has worked well the elements will
be evenly distributed amongst the buckets.

You can see in the diagram that `A` & `D` have been placed in the same bucket.
This means that when looking in this 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.

[table Methods for Accessing Buckets
    [[Method] [Description]]

    [
        [``size_type bucket_count() const``]
        [The number of buckets.]
    ]
    [
        [``size_type max_bucket_count() const``]
        [An upper bound on the number of buckets.]
    ]
    [
        [``size_type bucket_size(size_type n) const``]
        [The number of elements in bucket `n`.]
    ]
    [
        [``size_type bucket(key_type const& k) const``]
        [Returns the index of the bucket which would contain k]
    ]
    [
        [``
            local_iterator begin(size_type n);
            local_iterator end(size_type n);
            const_local_iterator begin(size_type n) const;
            const_local_iterator end(size_type n) const;
        ``]
        [Return begin and end iterators for bucket `n`.]
    ]
]

[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.

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 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.

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.

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` is required because the container is allowed to resize when the load
factor is equal to the maximum load factor.]

[table Methods for Controlling Bucket Size
    [[Method] [Description]]

    [
        [``float load_factor() const``]
        [The average number of elements per bucket.]
    ]
    [
        [``float max_load_factor() const``]
        [Returns the current maximum load factor.]
    ]
    [
        [``float max_load_factor(float z)``]
        [Changes the container's maximum load factor, using `z` as a hint.]
    ]
    [
        [``void rehash(size_type n)``]
        [Changes the number of buckets so that there at least n buckets, and
        so that the load factor is less than the maximum load factor.]
    ]

]

[/ I'm not at all happy with this section. So I've commented it out.]

[/ h2 Rehash Techniques]

[/If the container has a load factor much smaller than the maximum, `rehash`
might decrease the number of buckets, reducing the memory usage. This isn't
guaranteed by the standard but this implementation will do it.

If you want to stop the table from ever rehashing due to an insert, you can
set the maximum load factor to infinity (or perhaps a load factor that it'll
never reach - say `x.max_size()`. As you can only give a 'hint' for the maximum
load factor, this isn't guaranteed to work. But again, it'll work in this
implementation. (TODO: If an unordered container with infinite load factor
is copied, bad things could happen. So maybe this advice should be removed. Or
maybe the implementation should cope with that).

If you do this and want to make the container rehash, `rehash` will still work.
But be careful that you only ever call it with a sufficient number of buckets
- otherwise it's very likely that the container will decrease the bucket
count to an overly small amount.]

[endsect]