[template.valarray] - C++17 → C++20

Files changed (1) hide show

tmp/tmprxx1oxny/{from.md → to.md} +48 -49

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

@@ -1,8 +1,8 @@
 ### Class template `valarray` <a id="template.valarray">[[template.valarray]]</a>
-#### Class template `valarray` overview <a id="template.valarray.overview">[[template.valarray.overview]]</a>
 ``` cpp
 namespace std {
   template<class T> class valarray {
   public:
@@ -102,14 +102,11 @@ object of type `valarray<T>` is referred to as an “array” throughout the
 remainder of  [[numarray]]. The illusion of higher dimensionality may be
 produced by the familiar idiom of computed indices, together with the
 powerful subsetting capabilities provided by the generalized subscript
 operators.[^8]
-An implementation is permitted to qualify any of the functions declared
-in `<valarray>` as `inline`.
-#### `valarray` constructors <a id="valarray.cons">[[valarray.cons]]</a>
 ``` cpp
 valarray();
 ```
@@ -118,11 +115,11 @@ valarray();
 ``` cpp
 explicit valarray(size_t n);
 ```
 *Effects:* Constructs a `valarray` that has length `n`. Each element of
-the array is value-initialized ([[dcl.init]]).
 ``` cpp
 valarray(const T& v, size_t n);
 ```
@@ -131,12 +128,11 @@ the array is initialized with `v`.
 ``` cpp
 valarray(const T* p, size_t n);
 ```
-*Requires:* `p` points to an array ([[dcl.array]]) of at least `n`
-elements.
 *Effects:* Constructs a `valarray` that has length `n`. The values of
 the elements of the array are initialized with the first `n` values
 pointed to by the first argument.[^10]
@@ -179,11 +175,11 @@ templates to a `valarray`.
 ```
 *Effects:* The destructor is applied to every element of `*this`; an
 implementation may return all allocated memory.
-#### `valarray` assignment <a id="valarray.assign">[[valarray.assign]]</a>
 ``` cpp
 valarray& operator=(const valarray& v);
 ```
@@ -191,11 +187,11 @@ valarray& operator=(const valarray& v);
 the corresponding element of `v`. If the length of `v` is not equal to
 the length of `*this`, resizes `*this` to make the two arrays the same
 length, as if by calling `resize(v.size())`, before performing the
 assignment.
-*Postconditions:* `size() == v.size()`.
 *Returns:* `*this`.
 ``` cpp
 valarray& operator=(valarray&& v) noexcept;
@@ -227,63 +223,64 @@ valarray& operator=(const slice_array<T>&);
 valarray& operator=(const gslice_array<T>&);
 valarray& operator=(const mask_array<T>&);
 valarray& operator=(const indirect_array<T>&);
 ```
-*Requires:* The length of the array to which the argument refers equals
-`size()`. The value of an element in the left-hand side of a `valarray`
-assignment operator does not depend on the value of another element in
-that left-hand side.
 These operators allow the results of a generalized subscripting
 operation to be assigned directly to a `valarray`.
-#### `valarray` element access <a id="valarray.access">[[valarray.access]]</a>
 ``` cpp
 const T&  operator[](size_t n) const;
 T& operator[](size_t n);
 ```
-*Requires:* `n < size()`.
 *Returns:* A reference to the corresponding element of the array.
 [*Note 1*: The expression `(a[i] = q, a[i]) == q` evaluates to `true`
 for any non-constant `valarray<T> a`, any `T q`, and for any `size_t i`
 such that the value of `i` is less than the length of
 `a`. — *end note*]
-*Remarks:* The expression `&a[i+j] == &a[i] + j` evaluates to `true` for
-all `size_t i` and `size_t j` such that `i+j < a.size()`.
-The expression `&a[i] != &b[j]` evaluates to `true` for any two arrays
-`a` and `b` and for any `size_t i` and `size_t j` such that
-`i < a.size()` and `j < b.size()`.
 [*Note 2*: This property indicates an absence of aliasing and may be
 used to advantage by optimizing compilers. Compilers may take advantage
 of inlining, constant propagation, loop fusion, tracking of pointers
 obtained from `operator new`, and other techniques to generate efficient
 `valarray`s. — *end note*]
 The reference returned by the subscript operator for an array shall be
-valid until the member function
-`resize(size_t, T)` ([[valarray.members]]) is called for that array or
-until the lifetime of that array ends, whichever happens first.
-#### `valarray` subset operations <a id="valarray.sub">[[valarray.sub]]</a>
 The member `operator[]` is overloaded to provide several ways to select
 sequences of elements from among those controlled by `*this`. Each of
 these operations returns a subset of the array. The const-qualified
 versions return this subset as a new `valarray` object. The non-const
 versions return a class template object which has reference semantics to
 the original array, working in conjunction with various overloads of
 `operator=` and other assigning operators to allow selective replacement
 (slicing) of the controlled sequence. In each case the selected
-element(s) must exist.
 ``` cpp
 valarray operator[](slice slicearr) const;
 ```
@@ -430,30 +427,29 @@ v0[valarray<size_t>(vi, 5)] = v1;
 // v0 == valarray<char>("abCDeBgAEjklmnop", 16)
 ```
 — *end example*]
-#### `valarray` unary operators <a id="valarray.unary">[[valarray.unary]]</a>
 ``` cpp
 valarray operator+() const;
 valarray operator-() const;
 valarray operator~() const;
 valarray<bool> operator!() const;
 ```
-*Requires:* Each of these operators may only be instantiated for a type
-`T` to which the indicated operator can be applied and for which the
-indicated operator returns a value which is of type `T` (`bool` for
-`operator!`) or which may be unambiguously implicitly converted to type
-`T` (`bool` for `operator!`).
 *Returns:* A `valarray` whose length is `size()`. Each element of the
 returned array is initialized with the result of applying the indicated
 operator to the corresponding element of the array.
-#### `valarray` compound assignment <a id="valarray.cassign">[[valarray.cassign]]</a>
 ``` cpp
 valarray& operator*= (const valarray& v);
 valarray& operator/= (const valarray& v);
 valarray& operator%= (const valarray& v);
@@ -464,15 +460,18 @@ valarray& operator&= (const valarray& v);
 valarray& operator|= (const valarray& v);
 valarray& operator<<=(const valarray& v);
 valarray& operator>>=(const valarray& v);
 ```
-*Requires:* `size() == v.size()`. Each of these operators may only be
-instantiated for a type `T` if the indicated operator can be applied to
-two operands of type `T`. The value of an element in the left-hand side
-of a valarray compound assignment operator does not depend on the value
-of another element in that left hand side.
 *Effects:* Each of these operators performs the indicated operation on
 each of the elements of `*this` and the corresponding element of `v`.
 *Returns:* `*this`.
@@ -491,24 +490,23 @@ valarray& operator&= (const T& v);
 valarray& operator|= (const T& v);
 valarray& operator<<=(const T& v);
 valarray& operator>>=(const T& v);
 ```
-*Requires:* Each of these operators may only be instantiated for a type
-`T` if the indicated operator can be applied to two operands of type
-`T`.
 *Effects:* Each of these operators applies the indicated operation to
 each element of `*this` and `v`.
 *Returns:* `*this`
 *Remarks:* The appearance of an array on the left-hand side of a
 compound assignment does not invalidate references or pointers to the
 elements of the array.
-#### `valarray` member functions <a id="valarray.members">[[valarray.members]]</a>
 ``` cpp
 void swap(valarray& v) noexcept;
 ```
@@ -527,33 +525,34 @@ size_t size() const;
 ``` cpp
 T sum() const;
 ```
-*Requires:* `size() > 0`. This function may only be instantiated for a
-type `T` to which `operator+=` can be applied.
 *Returns:* The sum of all the elements of the array. If the array has
 length 1, returns the value of element 0. Otherwise, the returned value
 is calculated by applying `operator+=` to a copy of an element of the
 array and all other elements of the array in an unspecified order.
 ``` cpp
 T min() const;
 ```
-*Requires:* `size() > 0`
 *Returns:* The minimum value contained in `*this`. For an array of
 length 1, the value of element 0 is returned. For all other array
 lengths, the determination is made using `operator<`.
 ``` cpp
 T max() const;
 ```
-*Requires:* `size() > 0`.
 *Returns:* The maximum value contained in `*this`. For an array of
 length 1, the value of element 0 is returned. For all other array
 lengths, the determination is made using `operator<`.
@@ -568,13 +567,13 @@ is `(*this)[`*`I`*` + n]` if *`I`*` + n` is non-negative and less than
 [*Note 1*: If element zero is taken as the leftmost element, a positive
 value of `n` shifts the elements left `n` places, with zero
 fill. — *end note*]
 [*Example 1*: If the argument has the value -2, the first two elements
-of the result will be value-initialized ([[dcl.init]]); the third
-element of the result will be assigned the value of the first element of
-the argument; etc. — *end example*]
 ``` cpp
 valarray cshift(int n) const;
 ```

 ### Class template `valarray` <a id="template.valarray">[[template.valarray]]</a>
+#### Overview <a id="template.valarray.overview">[[template.valarray.overview]]</a>
 ``` cpp
 namespace std {
   template<class T> class valarray {
   public:
 remainder of  [[numarray]]. The illusion of higher dimensionality may be
 produced by the familiar idiom of computed indices, together with the
 powerful subsetting capabilities provided by the generalized subscript
 operators.[^8]
+#### Constructors <a id="valarray.cons">[[valarray.cons]]</a>
 ``` cpp
 valarray();
 ```
 ``` cpp
 explicit valarray(size_t n);
 ```
 *Effects:* Constructs a `valarray` that has length `n`. Each element of
+the array is value-initialized [[dcl.init]].
 ``` cpp
 valarray(const T& v, size_t n);
 ```
 ``` cpp
 valarray(const T* p, size_t n);
 ```
+*Preconditions:* \[`p`, `p + n`) is a valid range.
 *Effects:* Constructs a `valarray` that has length `n`. The values of
 the elements of the array are initialized with the first `n` values
 pointed to by the first argument.[^10]
 ```
 *Effects:* The destructor is applied to every element of `*this`; an
 implementation may return all allocated memory.
+#### Assignment <a id="valarray.assign">[[valarray.assign]]</a>
 ``` cpp
 valarray& operator=(const valarray& v);
 ```
 the corresponding element of `v`. If the length of `v` is not equal to
 the length of `*this`, resizes `*this` to make the two arrays the same
 length, as if by calling `resize(v.size())`, before performing the
 assignment.
+*Ensures:* `size() == v.size()`.
 *Returns:* `*this`.
 ``` cpp
 valarray& operator=(valarray&& v) noexcept;
 valarray& operator=(const gslice_array<T>&);
 valarray& operator=(const mask_array<T>&);
 valarray& operator=(const indirect_array<T>&);
 ```
+*Preconditions:* The length of the array to which the argument refers
+equals `size()`. The value of an element in the left-hand side of a
+`valarray` assignment operator does not depend on the value of another
+element in that left-hand side.
 These operators allow the results of a generalized subscripting
 operation to be assigned directly to a `valarray`.
+#### Element access <a id="valarray.access">[[valarray.access]]</a>
 ``` cpp
 const T&  operator[](size_t n) const;
 T& operator[](size_t n);
 ```
+*Preconditions:* `n < size()` is `true`.
 *Returns:* A reference to the corresponding element of the array.
 [*Note 1*: The expression `(a[i] = q, a[i]) == q` evaluates to `true`
 for any non-constant `valarray<T> a`, any `T q`, and for any `size_t i`
 such that the value of `i` is less than the length of
 `a`. — *end note*]
+*Remarks:* The expression `addressof(a[i+j]) == addressof(a[i]) + j`
+evaluates to `true` for all `size_t i` and `size_t j` such that
+`i+j < a.size()`.
+The expression `addressof(a[i]) != addressof(b[j])` evaluates to `true`
+for any two arrays `a` and `b` and for any `size_t i` and `size_t j`
+such that `i < a.size()` and `j < b.size()`.
 [*Note 2*: This property indicates an absence of aliasing and may be
 used to advantage by optimizing compilers. Compilers may take advantage
 of inlining, constant propagation, loop fusion, tracking of pointers
 obtained from `operator new`, and other techniques to generate efficient
 `valarray`s. — *end note*]
 The reference returned by the subscript operator for an array shall be
+valid until the member function `resize(size_t, T)` [[valarray.members]]
+is called for that array or until the lifetime of that array ends,
+whichever happens first.
+#### Subset operations <a id="valarray.sub">[[valarray.sub]]</a>
 The member `operator[]` is overloaded to provide several ways to select
 sequences of elements from among those controlled by `*this`. Each of
 these operations returns a subset of the array. The const-qualified
 versions return this subset as a new `valarray` object. The non-const
 versions return a class template object which has reference semantics to
 the original array, working in conjunction with various overloads of
 `operator=` and other assigning operators to allow selective replacement
 (slicing) of the controlled sequence. In each case the selected
+element(s) shall exist.
 ``` cpp
 valarray operator[](slice slicearr) const;
 ```
 // v0 == valarray<char>("abCDeBgAEjklmnop", 16)
 ```
 — *end example*]
+#### Unary operators <a id="valarray.unary">[[valarray.unary]]</a>
 ``` cpp
 valarray operator+() const;
 valarray operator-() const;
 valarray operator~() const;
 valarray<bool> operator!() const;
 ```
+*Mandates:* The indicated operator can be applied to operands of type
+`T` and returns a value of type `T` (`bool` for `operator!`) or which
+may be unambiguously implicitly converted to type `T` (`bool` for
+`operator!`).
 *Returns:* A `valarray` whose length is `size()`. Each element of the
 returned array is initialized with the result of applying the indicated
 operator to the corresponding element of the array.
+#### Compound assignment <a id="valarray.cassign">[[valarray.cassign]]</a>
 ``` cpp
 valarray& operator*= (const valarray& v);
 valarray& operator/= (const valarray& v);
 valarray& operator%= (const valarray& v);
 valarray& operator|= (const valarray& v);
 valarray& operator<<=(const valarray& v);
 valarray& operator>>=(const valarray& v);
 ```
+*Mandates:* The indicated operator can be applied to two operands of
+type `T`.
+*Preconditions:* `size() == v.size()` is `true`.
+The value of an element in the left-hand side of a valarray compound
+assignment operator does not depend on the value of another element in
+that left hand side.
 *Effects:* Each of these operators performs the indicated operation on
 each of the elements of `*this` and the corresponding element of `v`.
 *Returns:* `*this`.
 valarray& operator|= (const T& v);
 valarray& operator<<=(const T& v);
 valarray& operator>>=(const T& v);
 ```
+*Mandates:* The indicated operator can be applied to two operands of
+type `T`.
 *Effects:* Each of these operators applies the indicated operation to
 each element of `*this` and `v`.
 *Returns:* `*this`
 *Remarks:* The appearance of an array on the left-hand side of a
 compound assignment does not invalidate references or pointers to the
 elements of the array.
+#### Member functions <a id="valarray.members">[[valarray.members]]</a>
 ``` cpp
 void swap(valarray& v) noexcept;
 ```
 ``` cpp
 T sum() const;
 ```
+*Mandates:* `operator+=` can be applied to operands of type `T`.
+*Preconditions:* `size() > 0` is `true`.
 *Returns:* The sum of all the elements of the array. If the array has
 length 1, returns the value of element 0. Otherwise, the returned value
 is calculated by applying `operator+=` to a copy of an element of the
 array and all other elements of the array in an unspecified order.
 ``` cpp
 T min() const;
 ```
+*Preconditions:* `size() > 0` is `true`.
 *Returns:* The minimum value contained in `*this`. For an array of
 length 1, the value of element 0 is returned. For all other array
 lengths, the determination is made using `operator<`.
 ``` cpp
 T max() const;
 ```
+*Preconditions:* `size() > 0` is `true`.
 *Returns:* The maximum value contained in `*this`. For an array of
 length 1, the value of element 0 is returned. For all other array
 lengths, the determination is made using `operator<`.
 [*Note 1*: If element zero is taken as the leftmost element, a positive
 value of `n` shifts the elements left `n` places, with zero
 fill. — *end note*]
 [*Example 1*: If the argument has the value -2, the first two elements
+of the result will be value-initialized [[dcl.init]]; the third element
+of the result will be assigned the value of the first element of the
+argument; etc. — *end example*]
 ``` cpp
 valarray cshift(int n) const;
 ```

Diff to HTML by rtfpessoa