C++ named requirements: Container

A Container is an object used to store other objects and taking care of the management of the memory used by the objects it contains.

Requirements

C container type;
T element type;
a, b objects of type C.
rv a prvalue expression of type C.

Types

name	type	notes
`value_type`	T	Erasable
`reference`	T&
`const_reference`	const T&
`iterator`	iterator pointing to T	LegacyForwardIterator convertible to `const_iterator`
`const_iterator`	constant iterator pointing to T	LegacyForwardIterator
`difference_type`	signed integer	must be the same as `iterator_traits::difference_type` for `iterator` and `const_iterator`
`size_type`	unsigned integer	large enough to represent all positive values of `difference_type`

Methods and operators

expression	return type	semantics	conditions	complexity
C()	C	creates an empty container	Post: C().empty() == true	Constant
C(a)	C	creates a copy of `a`	Pre: T must be CopyInsertable Post: a == C(a)	Linear
C(rv)(since C++11)	C	moves `rv`	Post: equal to the value rv had before this construction	Constant^[1]
a = b	C&	destroys or copy-assigns all elements of `a` from elements of `b`	Post: a == b	Linear
a = rv	C&	destroys or move-assigns all elements of `a` from elements of `rv`	Post: if a and rv do not refer the same object, a is equal to the value rv had before this assignment	Linear
a.~C()	void	destroys all elements of `a` and frees all memory		Linear
a.begin()	(const_)iterator	Iterator to the first element of `a`		Constant
a.end()	(const_)iterator	Iterator to one past the last element of `a`		Constant
a.cbegin()(since C++11)	const_iterator	const_cast<const C&>(a).begin()		Constant
a.cend()(since C++11)	const_iterator	const_cast<const C&>(a).end()		Constant
a == b	convertible to bool	a.size() == b.size() && std::equal(a.begin(), a.end(), b.begin()) (until C++14)std::equal(a.begin(), a.end(), b.begin(), b.end()) (since C++14)	Pre: T must be EqualityComparable	Constant^[2] if `a.size() != b.size()`, linear otherwise
a != b	convertible to bool	!(a == b)		Linear
a.swap(b)	void	exchanges the values of `a` and `b`		Constant^[1]^[3]
swap(a, b)	void	a.swap(b)		Constant^[1]
a.size()	size_type	std::distance(a.begin(), a.end())		Constant^[3]
a.max_size()	size_type	b.size() where `b` is the largest possible container		Constant^[3]
a.empty()	convertible to bool	a.begin() == a.end()		Constant
notes
↑ ^1.0 ^1.1 ^1.2 Linear for std::array ↑ always linear for std::forward_list ↑ ^3.0 ^3.1 ^3.2 (until C++11) Not strictly constant

Given

i and j, objects of a container's iterator type,

in the expressions i == j, i != j, i < j, i <= j, i >= j, i > j, i - j, either or both may be replaced by an object of the container's const_iterator type referring to the same element with no change in semantics.

Container data races

see container thread safety

Other requirements

C

T

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 179	C++98	`iterator` and `const_iterator` types might be incomparable	required to be comparable
LWG 2263	C++11	resolution of LWG179 was accidentally dropped in C++11	restored
LWG 2839	C++11	self move assignment of standard containers was not allowed	allowed but the result is unspecifed

Compiler support
Freestanding and hosted
Language
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Technical specifications
Symbols index
External libraries