Skip to main content

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

  • T, an element type;
  • C, a Container type containing elements of type T;
  • a and b, objects of type C;
  • rv, a prvalue expression of type C.

Types

NameTypeRequirements
value_typeTCopyConstructible (until C++11) Erasable (since C++11)
referenceT&
const_referenceconst T&
iteratoriterator whose value type is TLegacyForwardIterator convertible to const_iterator
const_iteratorconstant iterator whose value type is TLegacyForwardIterator
difference_typesigned integermust be the same as iterator_traits::difference_type for iterator and const_iterator
size_typeunsigned integerlarge enough to represent all positive values of difference_type

Methods and operators

ExpressionReturn typeSemanticsConditionsComplexity
C()Ccreates an empty containerPost:C().empty() == true Constant
C(a)Ccreates a copy of aPre: T must be CopyInsertable
Post: a == C(a)
Linear
C(rv) (since C++11)Cmoves rvPost: equal to the value rv had before this constructionConstant[1]
a = bC&destroys or copy-assigns all elements of a from elements of bPost: a == bLinear
a = rv (since C++11)C&destroys or move-assigns all elements of a from elements of rvPost: if a and rv do not refer the same object, a is equal to the value rv had before this assignmentLinear
a.~C()voiddestroys all elements of a and frees all memoryLinear
a.begin()(const_)iteratorIterator to the first element of aConstant
a.end()(const_)iteratorIterator to one past the last element of aConstant
a.cbegin() (since C++11)const_iteratorconst_cast<const C&>(a).begin()Constant
a.cend() (since C++11)const_iteratorconst_cast<const C&>(a).end()Constant
a == bconvertible to boola.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 EqualityComparableConstant[2] if a.size() != b.size(), linear otherwise
a != bconvertible to bool!(a == b)Linear
a.swap(b)voidexchanges the values of a and bConstant[1][3]
swap(a, b) voida.swap(b)Constant[1]
a.size()size_typestd::distance(a.begin(), a.end())Constant[3]
a.max_size()size_typeb.size() where b is the largest possible containerConstant[3]
a.empty()convertible to boola.begin() == a.end()Constant

Notes

1 Linear for std::array
2 always linear for std::forward_list
3 Not strictly constant (until C++11)

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.

DRApplied toBehavior as publishedCorrect behavior
LWG 179C++98iterator and const_iterator types might be incomparablerequired to be comparable
LWG 276C++98T was required to be CopyAssignableT is required to be CopyConstructible
LWG 322C++98the value types of iterator and const_iterator were not specifiedspecified as T
LWG 774C++98there was no requirement on swap(a, b)added
LWG 2263C++11the resolution of LWG issue 179 was accidentally dropped in C++11restored
LWG 2839C++11self move assignment of standard containers was not allowedallowed but the result is unspecifed

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

  • T, an element type;
  • C, a Container type containing elements of type T;
  • a and b, objects of type C;
  • rv, a prvalue expression of type C.

Types

NameTypeRequirements
value_typeTCopyConstructible (until C++11) Erasable (since C++11)
referenceT&
const_referenceconst T&
iteratoriterator whose value type is TLegacyForwardIterator convertible to const_iterator
const_iteratorconstant iterator whose value type is TLegacyForwardIterator
difference_typesigned integermust be the same as iterator_traits::difference_type for iterator and const_iterator
size_typeunsigned integerlarge enough to represent all positive values of difference_type

Methods and operators

ExpressionReturn typeSemanticsConditionsComplexity
C()Ccreates an empty containerPost:C().empty() == true Constant
C(a)Ccreates a copy of aPre: T must be CopyInsertable
Post: a == C(a)
Linear
C(rv) (since C++11)Cmoves rvPost: equal to the value rv had before this constructionConstant[1]
a = bC&destroys or copy-assigns all elements of a from elements of bPost: a == bLinear
a = rv (since C++11)C&destroys or move-assigns all elements of a from elements of rvPost: if a and rv do not refer the same object, a is equal to the value rv had before this assignmentLinear
a.~C()voiddestroys all elements of a and frees all memoryLinear
a.begin()(const_)iteratorIterator to the first element of aConstant
a.end()(const_)iteratorIterator to one past the last element of aConstant
a.cbegin() (since C++11)const_iteratorconst_cast<const C&>(a).begin()Constant
a.cend() (since C++11)const_iteratorconst_cast<const C&>(a).end()Constant
a == bconvertible to boola.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 EqualityComparableConstant[2] if a.size() != b.size(), linear otherwise
a != bconvertible to bool!(a == b)Linear
a.swap(b)voidexchanges the values of a and bConstant[1][3]
swap(a, b) voida.swap(b)Constant[1]
a.size()size_typestd::distance(a.begin(), a.end())Constant[3]
a.max_size()size_typeb.size() where b is the largest possible containerConstant[3]
a.empty()convertible to boola.begin() == a.end()Constant

Notes

1 Linear for std::array
2 always linear for std::forward_list
3 Not strictly constant (until C++11)

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.

DRApplied toBehavior as publishedCorrect behavior
LWG 179C++98iterator and const_iterator types might be incomparablerequired to be comparable
LWG 276C++98T was required to be CopyAssignableT is required to be CopyConstructible
LWG 322C++98the value types of iterator and const_iterator were not specifiedspecified as T
LWG 774C++98there was no requirement on swap(a, b)added
LWG 2263C++11the resolution of LWG issue 179 was accidentally dropped in C++11restored
LWG 2839C++11self move assignment of standard containers was not allowedallowed but the result is unspecifed