[container.requirements] (original) (raw)

Table 81: 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)

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 expressionhf(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 asX::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 asX::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.

see [container.node]

compile time

X(n, hf, eq)
X a(n, hf, eq);

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);

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);

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;

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 andkey_equal() as the key equality predicate.

constant

X(i, j, n, hf, eq)
X a(i, j, n, hf, eq);

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);

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);

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);

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 andkey_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)

Same as X(il.begin(), il.end()).

X(il, n)

Same as X(il.begin(), il.end(), n).

X(il, n, hf)

Same as X(il.begin(), il.end(), n, hf).

X(il, n, hf, eq)

Same as X(il.begin(), il.end(), n, hf, eq).

X(b)
X a(b);

Copy constructor.

In addition to the requirements of Table 73, copies the hash function, predicate, and maximum load factor.

Average case linear in b.size(), worst case quadratic.

a = b

Copy assignment operator.

In addition to the requirements of Table 73, copies the hash function, predicate, and maximum load factor.

Average case linear in b.size(), worst case quadratic.

a = il

Preconditions: value_type isCpp17CopyInsertable into Xand 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 withstd::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 withstd::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 isCpp17MoveInsertable into X; otherwise, value_type isCpp17CopyInsertable 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 isCpp17MoveInsertable into X; otherwise, value_type isCpp17CopyInsertable 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 isCpp17MoveInsertable into X; otherwise, value_type isCpp17CopyInsertable 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 ora_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 ora_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 ora.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 emptynode_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.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 tok, 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 toke, 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 tok.

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

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 might 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 shall be 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, thenb.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, thenb.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() anda.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.