STL教程(十): 关联容器--unordered

template<
    class Key,
    class T,
    class Hash = std::hash,
    class KeyEqual = std::equal_to,
    class Allocator = std::allocator< std::pair >
> class unordered_multimap;

参数介绍：

Key：元素的键类型，即类型为unordered_multimap::key_typeT：元素的值类型，即类型为unordered_multimap::mapped_typeHash：一元函数对象类型，它将与元素类型相同的对象作为参数，并基于它返回一个size_t类型的唯一值。默认为hash ，它返回一个哈希值，容器对象使用此函数返回 的哈希值在内部组织其元素，从而加快定位单个元素的过程，其碰撞概率接近1.0/std::numeric_limits::max()。类型为unordered_multimap::hasherKeyEqual：一个二元谓词，它接受两个与元素类型相同的参数并返回一个bool。容器使用此表达式来确定两个元素键是否等效。类型为unordered_multimap::key_equalAllocator：用于定义存储分配模型的分配器对象的类型。默认使用分配器类模板，它定义了最简单的内存分配模型，并且与值无关。类型为unordered_multimap::allocator_type

unordered_multimap是由键值对组成的关联容器，键值用于标识元素，而映射的值则是该键关联的内容的对象，键和映射值的数据类型可能，unordered_multimap和unordered_map唯一不同的的地方就是unordered_multimap允许容器中存在键相同的元素，而unordered_map却不可以。

在内部，unordered_multimap中的元素没有按照任何特定顺序进行排序，而是根据其哈希值组织成桶，直接通过键值快速访问各个元素（平均具有恒定的平均时间复杂度），元素放入哪个桶完全取决于其键的哈希值。

unordered_map的成员函数与unordered_multimap完全相同，下面以unordered_multimap为例进行介绍：

（1）构造一个空的unordered_multimap容器，不包含任何元素且大小为零，也是默认构造函数

explicit unordered_multimap( size_type n = ,
                              const hasher& hf = hasher(),
                              const key_equal& eql = key_equal(),
                              const allocator_type& alloc = allocator_type() );
explicit unordered_multimap( const allocator_type& alloc );

（2）构造一个包含了范围[first,last)元素的unordered_multimap容器，每个元素都从该范围内的相应元素以相同的顺序就地构造。

template 
    unordered_multimap( InputIterator first, InputIterator last,
        size_type n = ,
        const hasher& hf = hasher(),
        const key_equal& eql = key_equal(),
        const allocator_type& alloc = allocator_type() );

（3） 以unordered_multimap容器x作为数据源，构造一个新unordered_multimap容器，其中新unordered_multimap容器中的元素来自于x中元素拷贝的副本。

unordered_multimap( const unordered_multimap& ums ); 
unordered_multimap ( const unordered_multimap& ums, const allocator_type& alloc );

（4）该对象获取右值ums的内容

unordered_multimap(unordered_multimap&& ums); 
unordered_multimap(unordered_multimap&& ums, const allocator_type& alloc);

（5）用列表的内容初始化容器

unordered_multimap ( initializer_list il, 
                     size_type n = , 
                     const hasher& hf = hasher(), 
                     const key_equal& eql = key_equal(), 
                     const allocator_type& alloc = allocator_type() );

注：上述函数中的变量n表示的是：容器初始存储桶的最小数量。这不是容器中元素的数量，而是构建时内部哈希表所需的最小槽数。如果未指定此参数，则构造函数会自动确定（以取决于特定库实现的方式）。类型为size_type是无符号整数类型。

（1）使用unordered_multimap列表other对其进行复制拷贝

unordered_multimap& operator=( const unordered_multimap& other );

（2）使用unordered_multimap列表other对其进行移动拷贝，之后other的数据将被清空

unordered_multimap& operator=( unordered_multimap&& other );

（3）使用初始化列表对unordered_multimap进行赋值

unordered_multimap& operator=( std::initializer_list l );

iterator begin() ;// 返回容器的迭代器到第一个元素
local_iterator begin ( size_type n );// 返回容器中桶序号为n的第一个元素迭代器

iterator end();    // 返回容器的迭代器到最后一个元素的后一个位置 
local_iterator end(size_type n);// 返回容器容器中桶序号为n的迭代器到最后一个元素的后一个位置 

const_iterator cbegin(); // 返回容器的迭代器到第一个元素
const_local_iterator cbegin ( size_type n );// 返回容器中桶序号为n的第一个元素迭代器

const_iterator cend();   // 返回容器的迭代器到最后一个元素
const_local_iterator cend(size_type n);// 返回容器容器中桶序号为n的迭代器到最后一个元素的后一个位置 

bool empty(); // 判断容器是否为空
size_type size();// 返回容器中当前元素个数
size_type max_size(); //返回容器内可存放的最大元素个数,由系统或库实现进行限制，这是容器可以容纳的最大潜在元素数量。

pair insert (const value_type& val);
pair insert (value_type&& val);

// 尽量靠近position位置插入新元素val，并返回新元素位置或在set中已经存在元素位置
iterator insert (const_iterator position, const value_type& val);
iterator insert (const_iterator position, value_type&& val);

// 插入新元素[first,last)
template 
  void insert (InputIterator first, InputIterator last);

// 将初始化列表l内的元素插入到容器中
void insert (initializer_list l);

// 删除位于position的元素，并返回position之后的迭代器
iterator erase (const_iterator position);

// 删除值为val的元素，并返回删除元素的总个数
size_type erase (const value_type& val);

// 删除位置为[first,last)的元素，并返回最后一个移除元素之后的迭代器
iterator  erase (const_iterator first, const_iterator last);

// 用x的内容交换容器的内容
void swap (set& x);

// 清空容器内所有元素
void clear() ;


pair emplace (Args&&... args);


iterator emplace_hint (const_iterator position, Args&&... args);

// 返回容器中元素的键值为key的元素个数 
size_type count( const Key& key ) const

// 查找容器元素中键值为key的元素，并返回其迭代器位置
iterator find( const Key& key );
const_iterator find( const Key& key ) const;

// 查找容器中符合特定要求的键值，并返回两个迭代器:一个指向不小于key的第一个元素，一个指向大于key的第一个元素
std:: pair < iterator,iterator > equal_range ( const Key & key ) ;
std:: pair < const_iterator,const_iterator > equal_range ( const Key & key ) const ;

// 返回容器中的桶数。
size_type bucket_count() const noexcept;

// 返回容器可以拥有的最大桶数
size_type max_bucket_count() const noexcept;

// 返回容器中桶n的元素数。
size_type bucket_size ( size_type n ) const;

// 返回容器中值为k的元素所在的桶号
size_type bucket ( const key_type& k ) const;

// 返回容器的当前负载因子,负载因子是容器中元素个数与桶数的比值：load_factor = size / bucket_count
float load_factor() const noexcept;

// 返回容器的当前最大负载因子
float max_load_factor() const noexcept;

// 将z设置为容器的新最大负载因子,默认为1.0
void max_load_factor ( float z );

// 将容器中的最小桶数设置为n
// 若n大于容器中的当前桶数，则强制进行重新哈希，新的桶数可以等于或大于n。
// 若n小于容器中的当前桶数，则该函数可能对桶数没有影响，并且可能不会强制重新散列。
void rehash ( size_type n );

// 将容器中的桶数设置为最适合包含至少n个元素的桶数
void reserve ( size_type n );

// 返回该容器正在使用的哈希函数对象(一个一元函数，它接受一个key_type类型的对象作为参数，并基于它返回一个size_t类型的唯一值)
hasher hash_function() const;

// 返回容器正在使用的比较函数(一个谓词，它将两个元素 的值作为参数并返回一个布尔值，指示它们是否被认为是等价的)
key_equal key_eq() const;

// 返回用于构造容器的分配器对象。
allocator_type get_allocator() const noexcept;