[container.requirements.general]

Files changed (1) hide show

tmp/tmp5oj_j2g7/{from.md → to.md} +658 -2

tmp/tmp5oj_j2g7/{from.md → to.md} RENAMED Viewed

@@ -1,8 +1,10 @@
-#### General <a id="container.requirements.general">[[container.requirements.general]]</a>
-In subclause [[container.gen.reqmts]],
 - `X` denotes a container class containing objects of type `T`,
 - `a` denotes a value of type `X`,
 - `b` and `c` denote values of type (possibly const) `X`,
 - `i` and `j` denote values of type (possibly const) `X::iterator`,
@@ -19,5 +21,659 @@ containers:
 template<class R, class T>
 concept container-compatible-range =    // exposition only
   ranges::input_range<R> && convertible_to<ranges::range_reference_t<R>, T>;
 ```

+### General containers <a id="container.requirements.general">[[container.requirements.general]]</a>
+#### Introduction <a id="container.intro.reqmts">[[container.intro.reqmts]]</a>
+In [[container.requirements.general]],
 - `X` denotes a container class containing objects of type `T`,
 - `a` denotes a value of type `X`,
 - `b` and `c` denote values of type (possibly const) `X`,
 - `i` and `j` denote values of type (possibly const) `X::iterator`,
 template<class R, class T>
 concept container-compatible-range =    // exposition only
   ranges::input_range<R> && convertible_to<ranges::range_reference_t<R>, T>;
 ```
+#### Container requirements <a id="container.reqmts">[[container.reqmts]]</a>
+A type `X` meets the *container* requirements if the following types,
+statements, and expressions are well-formed and have the specified
+semantics.
+``` cpp
+typename X::value_type
+```
+*Result:* `T`
+*Preconditions:* `T` is *Cpp17Erasable* from `X`
+(see  [[container.alloc.reqmts]], below).
+``` cpp
+typename X::reference
+```
+*Result:* `T&`
+``` cpp
+typename X::const_reference
+```
+*Result:* `const T&`
+``` cpp
+typename X::iterator
+```
+*Result:* A type that meets the forward iterator
+requirements [[forward.iterators]] with value type `T`. The type
+`X::iterator` is convertible to `X::const_iterator`.
+``` cpp
+typename X::const_iterator
+```
+*Result:* A type that meets the requirements of a constant iterator and
+those of a forward iterator with value type `T`.
+``` cpp
+typename X::difference_type
+```
+*Result:* A signed integer type, identical to the difference type of
+`X::iterator` and `X::const_iterator`.
+``` cpp
+typename X::size_type
+```
+*Result:* An unsigned integer type that can represent any non-negative
+value of `X::difference_type`.
+``` cpp
+X u;
+X u = X();
+```
+*Ensures:* `u.empty()`
+*Complexity:* Constant.
+``` cpp
+X u(v);
+X u = v;
+```
+*Preconditions:* `T` is *Cpp17CopyInsertable* into `X` (see below).
+*Ensures:* `u == v`.
+*Complexity:* Linear.
+``` cpp
+X u(rv);
+X u = rv;
+```
+*Ensures:* `u` is equal to the value that `rv` had before this
+construction.
+*Complexity:* Linear for `array` and `inplace_vector` and constant for
+all other standard containers.
+``` cpp
+t = v
+```
+*Result:* `X&`.
+*Ensures:* `t == v`.
+*Complexity:* Linear.
+``` cpp
+t = rv
+```
+*Result:* `X&`.
+*Effects:* All existing elements of `t` are either move assigned to or
+destroyed.
+*Ensures:* If `t` and `rv` do not refer to the same object, `t` is equal
+to the value that `rv` had before this assignment.
+*Complexity:* Linear.
+``` cpp
+a.~X()
+```
+*Result:* `void`.
+*Effects:* Destroys every element of `a`; any memory obtained is
+deallocated.
+*Complexity:* Linear.
+``` cpp
+b.begin()
+```
+*Result:* `iterator`; `const_iterator` for constant `b`.
+*Returns:* An iterator referring to the first element in the container.
+*Complexity:* Constant.
+``` cpp
+b.end()
+```
+*Result:* `iterator`; `const_iterator` for constant `b`.
+*Returns:* An iterator which is the past-the-end value for the
+container.
+*Complexity:* Constant.
+``` cpp
+b.cbegin()
+```
+*Result:* `const_iterator`.
+*Returns:* `const_cast<X const&>(b).begin()`
+*Complexity:* Constant.
+``` cpp
+b.cend()
+```
+*Result:* `const_iterator`.
+*Returns:* `const_cast<X const&>(b).end()`
+*Complexity:* Constant.
+``` cpp
+i <=> j
+```
+*Result:* `strong_ordering`.
+*Constraints:* `X::iterator` meets the random access iterator
+requirements.
+*Complexity:* Constant.
+``` cpp
+c == b
+```
+*Preconditions:* `T` meets the *Cpp17EqualityComparable* requirements.
+*Result:* `bool`.
+*Returns:* `equal(c.begin(), c.end(), b.begin(), b.end())`
+[*Note 1*: The algorithm `equal` is defined in
+[[alg.equal]]. — *end note*]
+*Complexity:* Constant if `c.size() != b.size()`, linear otherwise.
+*Remarks:* `==` is an equivalence relation.
+``` cpp
+c != b
+```
+*Effects:* Equivalent to `!(c == b)`.
+``` cpp
+t.swap(s)
+```
+*Result:* `void`.
+*Effects:* Exchanges the contents of `t` and `s`.
+*Complexity:* Linear for `array` and `inplace_vector`, and constant for
+all other standard containers.
+``` cpp
+swap(t, s)
+```
+*Effects:* Equivalent to `t.swap(s)`.
+``` cpp
+c.size()
+```
+*Result:* `size_type`.
+*Returns:* `distance(c.begin(), c.end())`, i.e., the number of elements
+in the container.
+*Complexity:* Constant.
+*Remarks:* The number of elements is defined by the rules of
+constructors, inserts, and erases.
+``` cpp
+c.max_size()
+```
+*Result:* `size_type`.
+*Returns:* `distance(begin(), end())` for the largest possible
+container.
+*Complexity:* Constant.
+``` cpp
+c.empty()
+```
+*Result:* `bool`.
+*Returns:* `c.begin() == c.end()`
+*Complexity:* Constant.
+*Remarks:* If the container is empty, then `c.empty()` is `true`.
+In the expressions
+``` cpp
+i == j
+i != j
+i < j
+i <= j
+i >= j
+i > j
+i <=> j
+i - j
+```
+where `i` and `j` denote objects of a container’s `iterator` type,
+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.
+Unless otherwise specified, all containers defined in this Clause obtain
+memory using an allocator (see  [[allocator.requirements]]).
+[*Note 1*: In particular, containers and iterators do not store
+references to allocated elements other than through the allocator’s
+pointer type, i.e., as objects of type `P` or
+`pointer_traits<P>::template rebind<unspecified>`, where `P` is
+`allocator_traits<allocator_type>::pointer`. — *end note*]
+Copy constructors for these container types obtain an allocator by
+calling
+`allocator_traits<allocator_type>::select_on_container_copy_construction`
+on the allocator belonging to the container being copied. Move
+constructors obtain an allocator by move construction from the allocator
+belonging to the container being moved. Such move construction of the
+allocator shall not exit via an exception. All other constructors for
+these container types take a `const allocator_type&` argument.
+[*Note 2*: If an invocation of a constructor uses the default value of
+an optional allocator argument, then the allocator type must support
+value-initialization. — *end note*]
+A copy of this allocator is used for any memory allocation and element
+construction performed, by these constructors and by all other member
+functions, during the lifetime of each container object or until the
+allocator is replaced. The allocator may be replaced only via assignment
+or `swap()`. Allocator replacement is performed by copy assignment, move
+assignment, or swapping of the allocator only if
+- `allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value`,
+- `allocator_traits<allocator_type>::propagate_on_container_move_assignment::value`,
+  or
+- `allocator_traits<allocator_type>::propagate_on_container_swap::value`
+is `true` within the implementation of the corresponding container
+operation. In all container types defined in this Clause, the member
+`get_allocator()` returns a copy of the allocator used to construct the
+container or, if that allocator has been replaced, a copy of the most
+recent replacement.
+The expression `a.swap(b)`, for containers `a` and `b` of a standard
+container type other than `array` and `inplace_vector`, shall exchange
+the values of `a` and `b` without invoking any move, copy, or swap
+operations on the individual container elements. Any `Compare`, `Pred`,
+or `Hash` types belonging to `a` and `b` shall meet the *Cpp17Swappable*
+requirements and shall be exchanged by calling `swap` as described in
+[[swappable.requirements]]. If
+`allocator_traits<allocator_type>::propagate_on_container_swap::value`
+is `true`, then `allocator_type` shall meet the *Cpp17Swappable*
+requirements and the allocators of `a` and `b` shall also be exchanged
+by calling `swap` as described in  [[swappable.requirements]].
+Otherwise, the allocators shall not be swapped, and the behavior is
+undefined unless `a.get_allocator() == b.get_allocator()`. Every
+iterator referring to an element in one container before the swap shall
+refer to the same element in the other container after the swap. It is
+unspecified whether an iterator with value `a.end()` before the swap
+will have value `b.end()` after the swap.
+Unless otherwise specified (see  [[associative.reqmts.except]],
+[[unord.req.except]], [[deque.modifiers]], [[inplace.vector.modifiers]],
+and [[vector.modifiers]]) all container types defined in this Clause
+meet the following additional requirements:
+- If an exception is thrown by an `insert()` or `emplace()` function
+  while inserting a single element, that function has no effects.
+- If an exception is thrown by a `push_back()`, `push_front()`,
+  `emplace_back()`, or `emplace_front()` function, that function has no
+  effects.
+- No `erase()`, `clear()`, `pop_back()` or `pop_front()` function throws
+  an exception.
+- No copy constructor or assignment operator of a returned iterator
+  throws an exception.
+- No `swap()` function throws an exception.
+- No `swap()` function invalidates any references, pointers, or
+  iterators referring to the elements of the containers being swapped.
+  \[*Note 3*: The `end()` iterator does not refer to any element, so it
+  can be invalidated. — *end note*]
+Unless otherwise specified (either explicitly or by defining a function
+in terms of other functions), invoking a container member function or
+passing a container as an argument to a library function shall not
+invalidate iterators to, or change the values of, objects within that
+container.
+A *contiguous container* is a container whose member types `iterator`
+and `const_iterator` meet the *Cpp17RandomAccessIterator* requirements
+[[random.access.iterators]] and model `contiguous_iterator`
+[[iterator.concept.contiguous]].
+The behavior of certain container member functions and deduction guides
+depends on whether types qualify as input iterators or allocators. The
+extent to which an implementation determines that a type cannot be an
+input iterator is unspecified, except that as a minimum integral types
+shall not qualify as input iterators. Likewise, the extent to which an
+implementation determines that a type cannot be an allocator is
+unspecified, except that as a minimum a type `A` shall not qualify as an
+allocator unless it meets both of the following conditions:
+- The *qualified-id* `A::value_type` is valid and denotes a type
+  [[temp.deduct]].
+- The expression `declval<A&>().allocate(size_t{})` is well-formed when
+  treated as an unevaluated operand.
+#### Reversible container requirements <a id="container.rev.reqmts">[[container.rev.reqmts]]</a>
+A type `X` meets the *reversible container* requirements if `X` meets
+the container requirements, the iterator type of `X` belongs to the
+bidirectional or random access iterator categories
+[[iterator.requirements]], and the following types and expressions are
+well-formed and have the specified semantics.
+``` cpp
+typename X::reverse_iterator
+```
+*Result:* The type `reverse_iterator<X::iterator>`, an iterator type
+whose value type is `T`.
+``` cpp
+typename X::const_reverse_iterator
+```
+*Result:* The type `reverse_iterator<X::const_iterator>`, a constant
+iterator type whose value type is `T`.
+``` cpp
+a.rbegin()
+```
+*Result:* `reverse_iterator`; `const_reverse_iterator` for constant `a`.
+*Returns:* `reverse_iterator(end())`
+*Complexity:* Constant.
+``` cpp
+a.rend()
+```
+*Result:* `reverse_iterator`; `const_reverse_iterator` for constant `a`.
+*Returns:* `reverse_iterator(begin())`
+*Complexity:* Constant.
+``` cpp
+a.crbegin()
+```
+*Result:* `const_reverse_iterator`.
+*Returns:* `const_cast<X const&>(a).rbegin()`
+*Complexity:* Constant.
+``` cpp
+a.crend()
+```
+*Result:* `const_reverse_iterator`.
+*Returns:* `const_cast<X const&>(a).rend()`
+*Complexity:* Constant.
+#### Optional container requirements <a id="container.opt.reqmts">[[container.opt.reqmts]]</a>
+The following operations are provided for some types of containers but
+not others. Those containers for which the listed operations are
+provided shall implement the semantics as described unless otherwise
+stated. If the iterators passed to `lexicographical_compare_three_way`
+meet the constexpr iterator requirements
+[[iterator.requirements.general]] then the operations described below
+are implemented by constexpr functions.
+``` cpp
+a <=> b
+```
+*Result:* *`synth-three-way-result`*`<X::value_type>`.
+*Preconditions:* Either `T` models `three_way_comparable`, or `<` is
+defined for values of type (possibly const) `T` and `<` is a total
+ordering relationship.
+*Returns:*
+`lexicographical_compare_three_way(a.begin(), a.end(), b.begin(), b.end(), `*`synth-three-way`*`)`
+[*Note 1*: The algorithm `lexicographical_compare_three_way` is defined
+in [[algorithms]]. — *end note*]
+*Complexity:* Linear.
+#### Allocator-aware containers <a id="container.alloc.reqmts">[[container.alloc.reqmts]]</a>
+Except for `array` and `inplace_vector`, all of the containers defined
+in [[containers]], [[stacktrace.basic]], [[basic.string]], and
+[[re.results]] meet the additional requirements of an
+*allocator-aware container*, as described below.
+Given an allocator type `A` and given a container type `X` having a
+`value_type` identical to `T` and an `allocator_type` identical to
+`allocator_traits<A>::rebind_alloc<T>` and given an lvalue `m` of type
+`A`, a pointer `p` of type `T*`, an expression `v` that denotes an
+lvalue of type `T` or `const T` or an rvalue of type `const T`, and an
+rvalue `rv` of type `T`, the following terms are defined. If `X` is not
+allocator-aware or is a specialization of `basic_string`, the terms
+below are defined as if `A` were `allocator<T>` — no allocator object
+needs to be created and user specializations of `allocator<T>` are not
+instantiated:
+- `T` is **Cpp17DefaultInsertable* into `X`* means that the following
+  expression is well-formed:
+  ``` cpp
+  allocator_traits<A>::construct(m, p)
+  ```
+- An element of `X` is *default-inserted* if it is initialized by
+  evaluation of the expression
+  ``` cpp
+  allocator_traits<A>::construct(m, p)
+  ```
+  where `p` is the address of the uninitialized storage for the element
+  allocated within `X`.
+- `T` is **Cpp17MoveInsertable* into `X`* means that the following
+  expression is well-formed:
+  ``` cpp
+  allocator_traits<A>::construct(m, p, rv)
+  ```
+  and its evaluation causes the following postcondition to hold: The
+  value of `*p` is equivalent to the value of `rv` before the
+  evaluation.
+  \[*Note 1*: `rv` remains a valid object. Its state is
+  unspecified. — *end note*]
+- `T` is **Cpp17CopyInsertable* into `X`* means that, in addition to `T`
+  being *Cpp17MoveInsertable* into `X`, the following expression is
+  well-formed:
+  ``` cpp
+  allocator_traits<A>::construct(m, p, v)
+  ```
+  and its evaluation causes the following postcondition to hold: The
+  value of `v` is unchanged and is equivalent to `*p`.
+- `T` is **Cpp17EmplaceConstructible* into `X` from `args`*, for zero or
+  more arguments `args`, means that the following expression is
+  well-formed:
+  ``` cpp
+  allocator_traits<A>::construct(m, p, args)
+  ```
+- `T` is **Cpp17Erasable* from `X`* means that the following expression
+  is well-formed:
+  ``` cpp
+  allocator_traits<A>::destroy(m, p)
+  ```
+[*Note 2*: A container calls
+`allocator_traits<A>::construct(m, p, args)` to construct an element at
+`p` using `args`, with `m == get_allocator()`. The default `construct`
+in `allocator` will call `::new((void*)p) T(args)`, but specialized
+allocators can choose a different definition. — *end note*]
+In this subclause,
+- `X` denotes an allocator-aware container class with a `value_type` of
+  `T` using an allocator of type `A`,
+- `u` denotes a variable,
+- `a` and `b` denote non-const lvalues of type `X`,
+- `c` denotes an lvalue of type `const X`,
+- `t` denotes an lvalue or a const rvalue of type `X`,
+- `rv` denotes a non-const rvalue of type `X`, and
+- `m` is a value of type `A`.
+A type `X` meets the allocator-aware container requirements if `X` meets
+the container requirements and the following types, statements, and
+expressions are well-formed and have the specified semantics.
+``` cpp
+typename X::allocator_type
+```
+*Result:* `A`
+*Mandates:* `allocator_type::value_type` is the same as `X::value_type`.
+``` cpp
+c.get_allocator()
+```
+*Result:* `A`
+*Complexity:* Constant.
+``` cpp
+X u;
+X u = X();
+```
+*Preconditions:* `A` meets the *Cpp17DefaultConstructible* requirements.
+*Ensures:* `u.empty()` returns `true`, `u.get_allocator() == A()`.
+*Complexity:* Constant.
+``` cpp
+X u(m);
+```
+*Ensures:* `u.empty()` returns `true`, `u.get_allocator() == m`.
+*Complexity:* Constant.
+``` cpp
+X u(t, m);
+```
+*Preconditions:* `T` is *Cpp17CopyInsertable* into `X`.
+*Ensures:* `u == t`, `u.get_allocator() == m`.
+*Complexity:* Linear.
+``` cpp
+X u(rv);
+```
+*Ensures:* `u` has the same elements as `rv` had before this
+construction; the value of `u.get_allocator()` is the same as the value
+of `rv.get_allocator()` before this construction.
+*Complexity:* Constant.
+``` cpp
+X u(rv, m);
+```
+*Preconditions:* `T` is *Cpp17MoveInsertable* into `X`.
+*Ensures:* `u` has the same elements, or copies of the elements, that
+`rv` had before this construction, `u.get_allocator() == m`.
+*Complexity:* Constant if `m == rv.get_allocator()`, otherwise linear.
+``` cpp
+a = t
+```
+*Result:* `X&`.
+*Preconditions:* `T` is *Cpp17CopyInsertable* into `X` and
+*Cpp17CopyAssignable*.
+*Ensures:* `a == t` is `true`.
+*Complexity:* Linear.
+``` cpp
+a = rv
+```
+*Result:* `X&`.
+*Preconditions:* If
+`allocator_traits<allocator_type>::propagate_on_container_move_assignment::value`
+is `false`, `T` is *Cpp17MoveInsertable* into `X` and
+*Cpp17MoveAssignable*.
+*Effects:* All existing elements of `a` are either move assigned to or
+destroyed.
+*Ensures:* If `a` and `rv` do not refer to the same object, `a` is equal
+to the value that `rv` had before this assignment.
+*Complexity:* Linear.
+``` cpp
+a.swap(b)
+```
+*Result:* `void`
+*Effects:* Exchanges the contents of `a` and `b`.
+*Complexity:* Constant.

Diff to HTML by rtfpessoa