22 Containers library [containers]

22.2 Container requirements [container.requirements]

22.2.7 Unordered associative containers [unord.req]

22.2.7.1 General [unord.req.general]

Table 85: Unordered associative container requirements (in addition to container) [tab:container.hash.req]
Expression
Return type
Assertion/note
Complexity
pre-/post-condition
X​::​key_­type
Key
compile time
X​::​mapped_­type (unordered_­map and unordered_­multimap only)
T
compile time
X​::​value_­type (unordered_­set and unordered_­multiset only)
Key
Preconditions: value_­type is Cpp17Erasable from X
compile time
X​::​value_­type (unordered_­map and unordered_­multimap only)
pair<const Key, T>
Preconditions: value_­type is Cpp17Erasable from X
compile time
X​::​hasher
Hash
Preconditions: Hash is a unary function object type such that the expression hf(k) has type size_­t.
compile time
X​::​key_­equal
Pred
Preconditions: Pred meets the Cpp17CopyConstructible requirements.

Pred is a binary predicate that takes two arguments of type Key.
Pred is an equivalence relation.
compile time
X​::​local_­iterator
An iterator type whose category, value type, difference type, and pointer and reference types are the same as X​::​iterator's.
A local_­iterator object may be used to iterate through a single bucket, but may not be used to iterate across buckets.
compile time
X​::​const_­local_­iterator
An iterator type whose category, value type, difference type, and pointer and reference types are the same as X​::​const_­iterator's.
A const_­local_­iterator object may be used to iterate through a single bucket, but may not be used to iterate across buckets.
compile time
X​::​node_­type
a specialization of a node-handle class template, such that the public nested types are the same types as the corresponding types in X.
compile time
X(n, hf, eq)
X a(n, hf, eq);
X
Effects:  Constructs an empty container with at least n buckets, using hf as the hash function and eq as the key equality predicate.
X(n, hf)
X a(n, hf);
X
Preconditions: key_­equal meets the Cpp17DefaultConstructible requirements.

Effects:  Constructs an empty container with at least n buckets, using hf as the hash function and key_­equal() as the key equality predicate.
X(n)
X a(n);
X
Preconditions: hasher and key_­equal meet the Cpp17DefaultConstructible requirements.

Effects:  Constructs an empty container with at least n buckets, using hasher() as the hash function and key_­equal() as the key equality predicate.
X()
X a;
X
Preconditions: hasher and key_­equal meet the Cpp17DefaultConstructible requirements.

Effects:  Constructs an empty container with an unspecified number of buckets, using hasher() as the hash function and key_­equal() as the key equality predicate.
constant
X(i, j, n, hf, eq)
X a(i, j, n, hf, eq);
X
Preconditions: value_­type is Cpp17EmplaceConstructible into X from *i.

Effects:  Constructs an empty container with at least n buckets, using hf as the hash function and eq as the key equality predicate, and inserts elements from [i, j) into it.
Average case (N is distance(i, j)), worst case
X(i, j, n, hf)
X a(i, j, n, hf);
X
Preconditions: key_­equal meets the Cpp17DefaultConstructible requirements.
value_­type is Cpp17EmplaceConstructible into X from *i.

Effects:  Constructs an empty container with at least n buckets, using hf as the hash function and key_­equal() as the key equality predicate, and inserts elements from [i, j) into it.
Average case (N is distance(i, j)), worst case
X(i, j, n)
X a(i, j, n);
X
Preconditions: hasher and key_­equal meet the Cpp17DefaultConstructible requirements.
value_­type is Cpp17EmplaceConstructible into X from *i.

Effects:  Constructs an empty container with at least n buckets, using hasher() as the hash function and key_­equal() as the key equality predicate, and inserts elements from [i, j) into it.
Average case (N is distance(i, j)), worst case
X(i, j)
X a(i, j);
X
Preconditions: hasher and key_­equal meet the Cpp17DefaultConstructible requirements.
value_­type is Cpp17EmplaceConstructible into X from *i.

Effects:  Constructs an empty container with an unspecified number of buckets, using hasher() as the hash function and key_­equal() as the key equality predicate, and inserts elements from [i, j) into it.
Average case (N is distance(i, j)), worst case
X(il)
X
Same as X(il.begin(), il.end()).
Same as X(il.begin(), il.end()).
X(il, n)
X
Same as X(il.begin(), il.end(), n).
Same as X(il.begin(), il.end(), n).
X(il, n, hf)
X
Same as X(il.begin(), il.end(), n, hf).
Same as X(il.begin(), il.end(), n, hf).
X(il, n, hf, eq)
X
Same as X(il.begin(), il.end(), n, hf, eq).
Same as X(il.begin(), il.end(), n, hf, eq).
X(b)
X a(b);
X
Copy constructor.
In addition to the requirements of Table 77, copies the hash function, predicate, and maximum load factor.
Average case linear in b.size(), worst case quadratic.
a = b
X&
Copy assignment operator.
In addition to the requirements of Table 77, copies the hash function, predicate, and maximum load factor.
Average case linear in b.size(), worst case quadratic.
a = il
X&
Preconditions: value_­type is Cpp17CopyInsertable into X and Cpp17CopyAssignable.

Effects:  Assigns the range [il.begin(), il.end()) into a.
All existing elements of a are either assigned to or destroyed.
Same as a = X(il).
b.hash_­function()
hasher
Returns: b's hash function.
constant
b.key_­eq()
key_­equal
Returns: b's key equality predicate.
constant
a_­uniq. emplace(args)
pair<iterator, bool>
Preconditions: value_­type is Cpp17EmplaceConstructible into X from args.

Effects:  Inserts a value_­type object t constructed with std​::​forward<​Args​>(​args)... if and only if there is no element in the container with key equivalent to the key of t.
The bool component of the returned pair is true if and only if the insertion takes place, and the iterator component of the pair points to the element with key equivalent to the key of t.
Average case , worst case .
a_­eq.emplace(args)
iterator
Preconditions: value_­type is Cpp17EmplaceConstructible into X from args.

Effects:  Inserts a value_­type object t constructed with std​::​forward<​Args>(​args)... and returns the iterator pointing to the newly inserted element.
Average case , worst case .
a.emplace_­hint(p, args)
iterator
Preconditions: value_­type is Cpp17EmplaceConstructible into X from args.

Effects:  Equivalent to a.emplace( std​::​forward<​Args>(​args)...).
Return value is an iterator pointing to the element with the key equivalent to the newly inserted element.
The const_­iterator p is a hint pointing to where the search should start.
Implementations are permitted to ignore the hint.
Average case , worst case .
a_­uniq.insert(t)
pair<iterator, bool>
Preconditions: If t is a non-const rvalue, value_­type is Cpp17MoveInsertable into X; otherwise, value_­type is Cpp17CopyInsertable into X.

Effects:  Inserts t if and only if there is no element in the container with key equivalent to the key of t.
The bool component of the returned pair indicates whether the insertion takes place, and the iterator component points to the element with key equivalent to the key of t.
Average case , worst case .
a_­eq.insert(t)
iterator
Preconditions: If t is a non-const rvalue, value_­type is Cpp17MoveInsertable into X; otherwise, value_­type is Cpp17CopyInsertable into X.

Effects:  Inserts t, and returns an iterator pointing to the newly inserted element.
Average case , worst case .
a.insert(p, t)
iterator
Preconditions: If t is a non-const rvalue, value_­type is Cpp17MoveInsertable into X; otherwise, value_­type is Cpp17CopyInsertable into X.

Effects: Equivalent to a.insert(t).
Return value is an iterator pointing to the element with the key equivalent to that of t.
The iterator p is a hint pointing to where the search should start.
Implementations are permitted to ignore the hint.
Average case , worst case .
a.insert(i, j)
void
Preconditions: value_­type is Cpp17EmplaceConstructible into X from *i.
Neither i nor j are iterators into a.

Effects: Equivalent to a.insert(t) for each element in [i,j).
Average case , where N is distance(i, j), worst case .
a.insert(il)
void
Same as a.insert(il.begin(), il.end()).
Same as a.insert( il.begin(), il.end()).
a_­uniq.
insert(nh)
insert_­return_­type
Preconditions: nh is empty or a_­uniq.get_­allocator() == nh.get_­allocator().

Effects: If nh is empty, has no effect.
Otherwise, inserts the element owned by nh if and only if there is no element in the container with a key equivalent to nh.key().

Postconditions: If nh is empty, inserted is false, position is end(), and node is empty.
Otherwise if the insertion took place, inserted is true, position points to the inserted element, and node is empty; if the insertion failed, inserted is false, node has the previous value of nh, and position points to an element with a key equivalent to nh.key().
Average case , worst case .
a_­eq.
insert(nh)
iterator
Preconditions: nh is empty or a_­eq.get_­allocator() == nh.get_­allocator().

Effects: If nh is empty, has no effect and returns a_­eq.end().
Otherwise, inserts the element owned by nh and returns an iterator pointing to the newly inserted element.

Postconditions: nh is empty.
Average case , worst case .
a.insert(q, nh)
iterator
Preconditions: nh is empty or a.get_­allocator() == nh.get_­allocator().

Effects: If nh is empty, has no effect and returns a.end().
Otherwise, inserts the element owned by nh if and only if there is no element with key equivalent to nh.key() in containers with unique keys; always inserts the element owned by nh in containers with equivalent keys.
Always returns the iterator pointing to the element with key equivalent to nh.key().
The iterator q is a hint pointing to where the search should start.
Implementations are permitted to ignore the hint.

Postconditions: nh is empty if insertion succeeds, unchanged if insertion fails.
Average case , worst case .
a.extract(k)
node_­type
Effects: Removes an element in the container with key equivalent to k.

Returns: A node_­type owning the element if found, otherwise an empty node_­type.
Average case , worst case .
a_­tran.​extract(kx)
node_­type
Effects: Removes an element in the container with key equivalent to kx.

Returns: A node_­type owning the element if found, otherwise an empty node_­type.
Average case , worst case .
a.extract(q)
node_­type
Effects: Removes the element pointed to by q.

Returns: A node_­type owning that element.
Average case , worst case .
a.merge(a2)
void
Preconditions: a.get_­allocator() == a2.get_­allocator().

Attempts to extract each element in a2 and insert it into a using the hash function and key equality predicate of a.
In containers with unique keys, if there is an element in a with key equivalent to the key of an element from a2, then that element is not extracted from a2.
Postconditions: Pointers and references to the transferred elements of a2 refer to those same elements but as members of a.
Iterators referring to the transferred elements and all iterators referring to a will be invalidated, but iterators to elements remaining in a2 will remain valid.
Average case , where N is a2.size(), worst case .
a.erase(k)
size_­type
Effects: Erases all elements with key equivalent to k.

Returns: The number of elements erased.
Average case , worst case .
a_­tran.​erase(kx)
size_­type
Effects: Erases all elements with key equivalent to kx.

Returns: The number of elements erased.
Average case , worst case .
a.erase(q)
iterator
Effects: Erases the element pointed to by q.

Returns: The iterator immediately following q prior to the erasure.
Average case , worst case .
a.erase(r)
iterator
Effects: Erases the element pointed to by r.

Returns: The iterator immediately following r prior to the erasure.
Average case , worst case .
a.erase(q1, q2)
iterator
Effects: Erases all elements in the range [q1, q2).

Returns: The iterator immediately following the erased elements prior to the erasure.
Average case linear in distance(q1, q2), worst case .
a.clear()
void
Effects: Erases all elements in the container.

Postconditions: a.empty() is true
Linear in a.size().
b.find(k)
iterator;
const_­iterator for const b.
Returns: An iterator pointing to an element with key equivalent to k, or b.end() if no such element exists.
Average case , worst case .
a_­tran.find(ke)
iterator;
const_­iterator for const a_­tran.
Returns: An iterator pointing to an element with key equivalent to ke, or a_­tran.end() if no such element exists.
Average case , worst case .
b.count(k)
size_­type
Returns: The number of elements with key equivalent to k.
Average case , worst case .
a_­tran.count(ke)
size_­type
Returns: The number of elements with key equivalent to ke.
Average case , worst case .
b.contains(k)
bool
Effects: Equivalent to b.find(k) != b.end()
Average case , worst case .
a_­tran.contains(ke)
bool
Effects: Equivalent to a_­tran.find(ke) != a_­tran.end()
Average case , worst case .
b.equal_­range(k)
pair<iterator, iterator>;
pair<const_­iterator, const_­iterator> for const b.
Returns: A range containing all elements with keys equivalent to k.
Returns make_­pair(b.end(), b.end()) if no such elements exist.
Average case , worst case .
a_­tran.equal_­range(ke)
pair<iterator, iterator>;
pair<const_­iterator, const_­iterator> for const a_­tran.
Returns: A range containing all elements with keys equivalent to ke.
Returns make_­pair(a_­tran.end(), a_­tran.end()) if no such elements exist.
Average case , worst case .
b.bucket_­count()
size_­type
Returns: The number of buckets that b contains.
Constant
b.max_­bucket_­count()
size_­type
Returns: An upper bound on the number of buckets that b can ever contain.
Constant
b.bucket(k)
size_­type
Preconditions: b.bucket_­count() > 0.

Returns: The index of the bucket in which elements with keys equivalent to k would be found, if any such element existed.

Postconditions: The return value is in the range [0, b.bucket_­count()).
Constant
b.bucket_­size(n)
size_­type
Preconditions: n shall be in the range [0, b.bucket_­count()).
Returns: The number of elements in the bucket.
b.begin(n)
local_­iterator;
const_­local_­iterator for const b.
Preconditions: n is in the range [0, b.bucket_­count()).

Returns: An iterator referring to the first element in the bucket.
If the bucket is empty, then b.begin(n) == b.end(n).
Constant
b.end(n)
local_­iterator;
const_­local_­iterator for const b.
Preconditions: n is in the range [0, b.bucket_­count()).

Returns: An iterator which is the past-the-end value for the bucket.
Constant
b.cbegin(n)
const_­local_­iterator
Preconditions: n shall be in the range [0, b.bucket_­count()).

Returns: An iterator referring to the first element in the bucket.
If the bucket is empty, then b.cbegin(n) == b.cend(n).
Constant
b.cend(n)
const_­local_­iterator
Preconditions: n is in the range [0, b.bucket_­count()).

Returns: An iterator which is the past-the-end value for the bucket.
Constant
b.load_­factor()
float
Returns: The average number of elements per bucket.
Constant
b.max_­load_­factor()
float
Returns: A positive number that the container attempts to keep the load factor less than or equal to.
The container automatically increases the number of buckets as necessary to keep the load factor below this number.
Constant
a.max_­load_­factor(z)
void
Preconditions: z is positive.
May change the container's maximum load factor, using z as a hint.
Constant
a.rehash(n)
void
Postconditions: a.bucket_­count() >= a.size() / a.max_­load_­factor() and a.bucket_­count() >= n.
Average case linear in a.size(), worst case quadratic.
a.reserve(n)
void
Same as a.rehash(ceil(n / a.max_­load_­factor())).
Average case linear in a.size(), worst case quadratic.