namespace std::ranges {
inline namespace /*unspecified*/ {
inline constexpr /*unspecified*/ reserve_hint = /*unspecified*/;
}
}
概要
Rangeに対し、要素数の近似値 (償却定数時間で求められる) を取得するカスタマイゼーションポイントオブジェクト。
ranges::toやコンテナの構築で出力先のメモリを事前確保 (reserve()) するために用いる。uppercase_viewのように要素数が厳密には事前にわからないが概算は可能であるような遅延評価Rangeから、効率的にコンテナを構築できる。
ranges::sizeで正確な要素数が取得できるRangeに対しては、ranges::reserve_hintはranges::sizeと等価。それ以外で、メンバ関数または ADL で発見できるreserve_hint関数を提供するRangeに対しては、そちらを呼び出す。
効果
型Tの部分式Eに対して、tをEの参照とすると、式ranges::reserve_hint(E)の効果は以下の通り：
ranges::size(E)が有効な式であれば、ranges::size(E)と等価- そうでなければ、
auto(t.reserve_hint())がinteger-like型の有効な式であれば、auto(t.reserve_hint())と等価 - そうでなければ、
Tがクラス型または列挙体であって、ADLでのみ発見されるreserve_hint(t)がinteger-like型の有効な式であれば、その式と等価 - そうでなければ、呼び出しは不適格
戻り値
Rangeの要素数の近似値。常に0以上で、range_difference_t<T>で表現可能。
カスタマイゼーションポイント
メンバ関数reserve_hintを持たせるか、ADLで発見できる非メンバ関数reserve_hintを提供することでカスタマイズできる。
備考
ranges::reserve_hint(E)が有効な式であるとき、その型はinteger-like- 計算量は償却定数時間でなければならない
標準ライブラリでの使用箇所
この関数オブジェクトは、Rangeからコンテナを構築・拡張する際に出力先のメモリを事前確保するために、標準ライブラリの内部で使用される：
std::ranges::to: 内部でreserve_hint()を呼び出してから要素のコピーを行うstd::vectorのRangeコンストラクタ :reserve_hint()を利用して再確保を回避するstd::vector::insert_range()/append_range():reserve_hint()を利用して再確保を高々1回に抑える
例
#include <ranges>
#include <vector>
#include <print>
int main()
{
std::vector v = {1, 2, 3, 4, 5};
// sized_rangeなので、size()と等価な値を返す
std::println("{}", std::ranges::reserve_hint(v));
}
出力
5
バージョン
言語
- C++26
処理系
- Clang: 22 ❌
- GCC: 16.1 ❌
- Visual C++: 2026 Update 2 ❌