Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/named req/Container"

From cppreference.com
< cpp‎ | named req
m (→‎Member functions and operators: +inplace_vector)
m (LWG2114)
Line 58: Line 58:
 
|{{c|1=i <=> j}}<br>{{mark since c++20}}||{{tt|strong_ordering}}||Three-way comparison of container iterators||{{c|C::​iterator}} meets the random access iterator requirements||Constant
 
|{{c|1=i <=> j}}<br>{{mark since c++20}}||{{tt|strong_ordering}}||Three-way comparison of container iterators||{{c|C::​iterator}} meets the random access iterator requirements||Constant
 
|-
 
|-
−
|{{c|1=a == b}}||Convertible to {{c/core|bool}}||{{rev begin}}
+
|{{c|1=a == b}}||{{c/core|bool}}||{{rev begin}}
 
{{rev|until=c++14|{{c|1=a.size() == b.size() &&
 
{{rev|until=c++14|{{c|1=a.size() == b.size() &&
 
     std::equal(a.begin(),
 
     std::equal(a.begin(),
Line 67: Line 67:
 
||Pre: {{tt|T}} must be {{named req|EqualityComparable}}||Constant<ref>Always linear for {{lc|std::forward_list}}</ref> if {{c|1=a.size() !=}}<br>{{c|b.size()}}, linear otherwise<!-- LWG2257 -->
 
||Pre: {{tt|T}} must be {{named req|EqualityComparable}}||Constant<ref>Always linear for {{lc|std::forward_list}}</ref> if {{c|1=a.size() !=}}<br>{{c|b.size()}}, linear otherwise<!-- LWG2257 -->
 
|-
 
|-
−
|{{c|1=a != b}}||convertible to {{c/core|bool}}||{{c|1=!(a == b)}}||||Linear
+
|{{c|1=a != b}}||{{c/core|bool}}||{{c|1=!(a == b)}}||||Linear
 
|-
 
|-
 
|{{c|a.swap(b)}}||{{c/core|void}}||Exchanges the values of {{c|a}} and {{c|b}}||
 
|{{c|a.swap(b)}}||{{c/core|void}}||Exchanges the values of {{c|a}} and {{c|b}}||
Line 78: Line 78:
 
|{{c|a.max_size()}}||{{tt|size_type}}||{{c|b.size()}} where {{c|b}} is the largest possible container||||Constant<ref name="should"/>
 
|{{c|a.max_size()}}||{{tt|size_type}}||{{c|b.size()}} where {{c|b}} is the largest possible container||||Constant<ref name="should"/>
 
|-
 
|-
−
|{{c|a.empty()}}||Convertible to {{c/core|bool}}||{{c|1=a.begin() == a.end()}}||||Constant
+
|{{c|a.empty()}}||{{c/core|bool}}||{{c|1=a.begin() == a.end()}}||||Constant
 
|-
 
|-
 
!colspan=6|Notes
 
!colspan=6|Notes
Line 141: Line 141:
 
{{dr list item|wg=lwg|dr=883|std=C++98|before={{c|a.swap(b)}} was defined as {{c|swap(a, b)}},<br>resulted in circular definition|after=defined as exchanging<br>the values of {{c|a}} and {{c|b}}}}
 
{{dr list item|wg=lwg|dr=883|std=C++98|before={{c|a.swap(b)}} was defined as {{c|swap(a, b)}},<br>resulted in circular definition|after=defined as exchanging<br>the values of {{c|a}} and {{c|b}}}}
 
{{dr list item|wg=lwg|dr=1319|std=C++98|before={{tt|iterator}} and {{tt|const_iterator}}<br>might not have multipass guarantee|after=they are required to satisfy<br>the requirements of<br>{{named req|ForwardIterator}}}}
 
{{dr list item|wg=lwg|dr=1319|std=C++98|before={{tt|iterator}} and {{tt|const_iterator}}<br>might not have multipass guarantee|after=they are required to satisfy<br>the requirements of<br>{{named req|ForwardIterator}}}}
 +
{{dr list item|wg=lwg|dr=2114|paper=P2167R3|std=C++98|before=non-{{c/core|bool}} return types of some functions were allowed|after=disallowed}}
 
{{dr list item|wg=lwg|dr=2263|std=C++11|before=the resolution of {{lwg|179}} was accidentally dropped in C++11|after=restored}}
 
{{dr list item|wg=lwg|dr=2263|std=C++11|before=the resolution of {{lwg|179}} was accidentally dropped in C++11|after=restored}}
 
{{dr list item|wg=lwg|dr=2839|std=C++11|before=self move assignment of standard containers was not allowed|after=allowed but the<br>result is unspecified}}
 
{{dr list item|wg=lwg|dr=2839|std=C++11|before=self move assignment of standard containers was not allowed|after=allowed but the<br>result is unspecified}}

Revision as of 18:45, 8 September 2024

 
C++
 
C++ named requirements
 

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.

Contents

Requirements

Legend

  • T, an element type;
  • C, a Container type containing elements of type T;
  • a and b, objects of type C;
  • i and j, values of (possibly const) type C::iterator;
  • rv, a prvalue expression of type C.

Member types

Name Type Requirements
C::value_type T CopyConstructible(until C++11)Erasable(since C++11)
C::reference T&
C::const_reference const T&
C::iterator Iterator whose value type is T LegacyForwardIterator
convertible to const_iterator
C::const_iterator Constant iterator whose value type is T LegacyForwardIterator
C::difference_type Signed integer Must be the same as iterator_traits::difference_type for iterator and const_iterator
C::size_type Unsigned integer Large enough to represent all positive values of difference_type

Member functions 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
(since C++11)		 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
i <=> j
(since C++20)		 strong_ordering Three-way comparison of container iterators C::​iterator meets the random access iterator requirements Constant
a == b 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 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() bool a.begin() == a.end() Constant
Notes
  1. ↑ 1.0 1.1 1.2 (since C++11) Linear for std::array and std::inplace_vector
  2. ↑ Always linear for std::forward_list
  3. ↑ 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.

Optional container requirements (since C++20)

The following operations are provided only for some types of containers.

If the iterators passed to std::lexicographical_compare_three_way meet the ConstexprIterator then the operations described below are implemented by constexpr functions.

Category Description
Expression a <=> b
Returns std::lexicographical_compare_three_way(a.begin(), a.end(),
                                       b.begin(), b.end(),
                                       /*synth-three-way*/)
Result /*synth-three-way-result*/<C::value_type>
Preconditions Either T models three_way_comparable, or < is defined for values of (possibly const) type T and < is a total ordering relationship.
Complexity Linear

Container data races

See container thread safety.

Other requirements

C (Container)

T (Type)

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 276 C++98 T was required to be CopyAssignable T is required to be
CopyConstructible
LWG 322 C++98 the value types of iterator and const_iterator were not specified specified as T
LWG 774 C++98 there was no requirement on swap(a, b) added
LWG 883 C++98 a.swap(b) was defined as swap(a, b),
resulted in circular definition 		defined as exchanging
the values of a and b
LWG 1319 C++98 iterator and const_iterator
might not have multipass guarantee 		they are required to satisfy
the requirements of
LegacyForwardIterator
LWG 2114
(P2167R3) 		C++98 non-bool return types of some functions were allowed disallowed
LWG 2263 C++11 the resolution of LWG issue 179 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 unspecified

See also

C++ documentation for Containers library
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/named_req/Container&oldid=175932"