std::unordered_set::reserve(C++11)

void reserve(size_type n);

概要

コンテナが、リハッシュされずに少なくとも引数 n で指定された要素数格納できるようにバケット数を調整（リハッシュ）する。（ただし、備考を参照）

事後条件

bucket_count() > size() / max_load_factor() かつ、bucket_count() >= ceil(n / max_load_factor())。

戻り値

なし

例外

ハッシュ関数、および、キー比較用関数以外から例外が投げられた場合、コンテナは変更されない。

計算量

平均的なケースでは size() に比例するが、最悪のケースでは size() の 2 乗に比例する。

備考

• C++11 : リハッシュされずに引数 n で指定された要素数が格納できるように意図されているはずが、 n - 1 しか格納することができない場合がある（少なくとも、事後条件を満たすだけでは確実に n 要素を格納できる保証はない）。
  • この問題については、Issue 「2156. Unordered containers' reserve(n) reserves for n-1 elements」を参照。
• C++17 : リハッシュされずに引数 n で指定された要素数以上が格納できるようになる。
• リハッシュされる条件については、insert()、emplace()、emplace_hint() も参照。
• リハッシュが行われた場合、
  • 全てのイテレータが無効になる。
  • 要素間の順番が変わる。
  • 要素の格納されているバケットが変更になる。
  • 要素へのポインタや参照は無効にならない。
• 現在のバケット数が既に ceil(n / max_load_factor()) 以上の場合の動作は、標準では特に規定されていない。

例

#include <iostream>
#include <unordered_set>

int main()
{
  std::unordered_set<int> us{ 1, 2, 3, 4, 5, 6, };

  std::cout << "size is " << us.size() << ", max_load_factor is " << us.max_load_factor() << std::endl;

  std::cout << "bucket_count is " << us.bucket_count() << std::endl;

  // 現在の要素数より大きな値を指定する。
  us.reserve(100);
  std::cout << "bucket_count is " << us.bucket_count() << std::endl;

  // 現在の要素数よりは大きく、現在のバケット数 / max_load_factor() よりは小さい値を指定する。
  us.reserve(10);
  std::cout << "bucket_count is " << us.bucket_count() << std::endl;

  // 現在の要素数より小さい値を指定する。
  us.reserve(1);
  std::cout << "bucket_count is " << us.bucket_count() << std::endl;
}

出力例

size is 6, max_load_factor is 1
bucket_count is 11
bucket_count is 101
bucket_count is 11
bucket_count is 7

バージョン

言語

• C++11

処理系

• Clang: 3.1 ✅
• GCC: 4.7.0 ✅
• ICC: ?
• Visual C++: ?

関連項目