[numarray]

26.6 Numeric arrays [numarray]

26.6.1 Header <valarray> synopsis [valarray.syn]

#include <initializer_list>

namespace std {

  template<class T> class valarray;         // An array of type T
  class slice;                              // a BLAS-like slice out of an array
  template<class T> class slice_array;
  class gslice;                             // a generalized slice out of an array
  template<class T> class gslice_array;
  template<class T> class mask_array;       // a masked array
  template<class T> class indirect_array;   // an indirected array

  template<class T> void swap(valarray<T>&, valarray<T>&) noexcept;

  template<class T> valarray<T> operator* (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator* (const valarray<T>&, const T&);
  template<class T> valarray<T> operator* (const T&, const valarray<T>&);

  template<class T> valarray<T> operator/ (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator/ (const valarray<T>&, const T&);
  template<class T> valarray<T> operator/ (const T&, const valarray<T>&);

  template<class T> valarray<T> operator% (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator% (const valarray<T>&, const T&);
  template<class T> valarray<T> operator% (const T&, const valarray<T>&);

  template<class T> valarray<T> operator+ (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator+ (const valarray<T>&, const T&);
  template<class T> valarray<T> operator+ (const T&, const valarray<T>&);

  template<class T> valarray<T> operator- (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator- (const valarray<T>&, const T&);
  template<class T> valarray<T> operator- (const T&, const valarray<T>&);

  template<class T> valarray<T> operator^ (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator^ (const valarray<T>&, const T&);
  template<class T> valarray<T> operator^ (const T&, const valarray<T>&);

  template<class T> valarray<T> operator& (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator& (const valarray<T>&, const T&);
  template<class T> valarray<T> operator& (const T&, const valarray<T>&);

  template<class T> valarray<T> operator| (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator| (const valarray<T>&, const T&);
  template<class T> valarray<T> operator| (const T&, const valarray<T>&);

  template<class T> valarray<T> operator<<(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator<<(const valarray<T>&, const T&);
  template<class T> valarray<T> operator<<(const T&, const valarray<T>&);

  template<class T> valarray<T> operator>>(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator>>(const valarray<T>&, const T&);
  template<class T> valarray<T> operator>>(const T&, const valarray<T>&);

  template<class T> valarray<bool> operator&&(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator&&(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator&&(const T&, const valarray<T>&);

  template<class T> valarray<bool> operator||(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator||(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator||(const T&, const valarray<T>&);

  template<class T>
    valarray<bool> operator==(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator==(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator==(const T&, const valarray<T>&);
  template<class T>
    valarray<bool> operator!=(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator!=(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator!=(const T&, const valarray<T>&);

  template<class T>
    valarray<bool> operator< (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator< (const valarray<T>&, const T&);
  template<class T> valarray<bool> operator< (const T&, const valarray<T>&);
  template<class T>
    valarray<bool> operator> (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator> (const valarray<T>&, const T&);
  template<class T> valarray<bool> operator> (const T&, const valarray<T>&);
  template<class T>
    valarray<bool> operator<=(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator<=(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator<=(const T&, const valarray<T>&);
  template<class T>
    valarray<bool> operator>=(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator>=(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator>=(const T&, const valarray<T>&);

  template<class T> valarray<T> abs  (const valarray<T>&);
  template<class T> valarray<T> acos (const valarray<T>&);
  template<class T> valarray<T> asin (const valarray<T>&);
  template<class T> valarray<T> atan (const valarray<T>&);

  template<class T> valarray<T> atan2(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> atan2(const valarray<T>&, const T&);
  template<class T> valarray<T> atan2(const T&, const valarray<T>&);

  template<class T> valarray<T> cos  (const valarray<T>&);
  template<class T> valarray<T> cosh (const valarray<T>&);
  template<class T> valarray<T> exp  (const valarray<T>&);
  template<class T> valarray<T> log  (const valarray<T>&);
  template<class T> valarray<T> log10(const valarray<T>&);

  template<class T> valarray<T> pow(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> pow(const valarray<T>&, const T&);
  template<class T> valarray<T> pow(const T&, const valarray<T>&);

  template<class T> valarray<T> sin  (const valarray<T>&);
  template<class T> valarray<T> sinh (const valarray<T>&);
  template<class T> valarray<T> sqrt (const valarray<T>&);
  template<class T> valarray<T> tan  (const valarray<T>&);
  template<class T> valarray<T> tanh (const valarray<T>&);

  template <class T> unspecified1 begin(valarray<T>& v);
  template <class T> unspecified2 begin(const valarray<T>& v);
  template <class T> unspecified1 end(valarray<T>& v);
  template <class T> unspecified2 end(const valarray<T>& v);
}

The header <valarray> defines five class templates (valarray, slice_array, gslice_array, mask_array, and indirect_array), two classes (slice and gslice), and a series of related function templates for representing and manipulating arrays of values.

The valarray array classes are defined to be free of certain forms of aliasing, thus allowing operations on these classes to be optimized.

Any function returning a valarray<T> is permitted to return an object of another type, provided all the const member functions of valarray<T> are also applicable to this type. This return type shall not add more than two levels of template nesting over the most deeply nested argument type.281

Implementations introducing such replacement types shall provide additional functions and operators as follows:

(4.1)
for every function taking a const valarray<T>& other than begin and end ([valarray.range]), identical functions taking the replacement types shall be added;
(4.2)
for every function taking two const valarray<T>& arguments, identical functions taking every combination of const valarray<T>& and replacement types shall be added.

In particular, an implementation shall allow a valarray<T> to be constructed from such replacement types and shall allow assignments and computed assignments of such types to valarray<T>, slice_array<T>, gslice_array<T>, mask_array<T> and indirect_array<T> objects.

These library functions are permitted to throw a bad_alloc ([bad.alloc]) exception if there are not sufficient resources available to carry out the operation. Note that the exception is not mandated.

280)

Clause [limits] recommends a minimum number of recursively nested template instantiations. This requirement thus indirectly suggests a minimum allowable complexity for valarray expressions.

26.6.2 Class template valarray [template.valarray]

26.6.2.1 Class template valarray overview [template.valarray.overview]

namespace std {
  template<class T> class valarray {
  public:
    typedef T value_type;

    // [valarray.cons] construct/destroy:
    valarray();
    explicit valarray(size_t);
    valarray(const T&, size_t);
    valarray(const T*, size_t);
    valarray(const valarray&);
    valarray(valarray&&) noexcept;
    valarray(const slice_array<T>&);
    valarray(const gslice_array<T>&);
    valarray(const mask_array<T>&);
    valarray(const indirect_array<T>&);
    valarray(initializer_list<T>);
    ~valarray();

    // [valarray.assign] assignment:
    valarray<T>& operator=(const valarray<T>&);
    valarray<T>& operator=(valarray<T>&&) noexcept;
    valarray& operator=(initializer_list<T>);
    valarray<T>& operator=(const T&);
    valarray<T>& operator=(const slice_array<T>&);
    valarray<T>& operator=(const gslice_array<T>&);
    valarray<T>& operator=(const mask_array<T>&);
    valarray<T>& operator=(const indirect_array<T>&);

    // [valarray.access] element access:
    const T&          operator[](size_t) const;
    T&                operator[](size_t);

    // [valarray.sub] subset operations:
    valarray<T>       operator[](slice) const;
    slice_array<T>    operator[](slice);
    valarray<T>       operator[](const gslice&) const;
    gslice_array<T>   operator[](const gslice&);
    valarray<T>       operator[](const valarray<bool>&) const;
    mask_array<T>     operator[](const valarray<bool>&);
    valarray<T>       operator[](const valarray<size_t>&) const;
    indirect_array<T> operator[](const valarray<size_t>&);

    // [valarray.unary] unary operators:
    valarray<T> operator+() const;
    valarray<T> operator-() const;
    valarray<T> operator~() const;
    valarray<bool> operator!() const;

    // [valarray.cassign] computed assignment:
    valarray<T>& operator*= (const T&);
    valarray<T>& operator/= (const T&);
    valarray<T>& operator%= (const T&);
    valarray<T>& operator+= (const T&);
    valarray<T>& operator-= (const T&);
    valarray<T>& operator^= (const T&);
    valarray<T>& operator&= (const T&);
    valarray<T>& operator|= (const T&);
    valarray<T>& operator<<=(const T&);
    valarray<T>& operator>>=(const T&);

    valarray<T>& operator*= (const valarray<T>&);
    valarray<T>& operator/= (const valarray<T>&);
    valarray<T>& operator%= (const valarray<T>&);
    valarray<T>& operator+= (const valarray<T>&);
    valarray<T>& operator-= (const valarray<T>&);
    valarray<T>& operator^= (const valarray<T>&);
    valarray<T>& operator|= (const valarray<T>&);
    valarray<T>& operator&= (const valarray<T>&);
    valarray<T>& operator<<=(const valarray<T>&);
    valarray<T>& operator>>=(const valarray<T>&);

    // [valarray.members] member functions:
    void swap(valarray&) noexcept;

    size_t size() const;

    T sum() const;
    T min() const;
    T max() const;

    valarray<T> shift (int) const;
    valarray<T> cshift(int) const;
    valarray<T> apply(T func(T)) const;
    valarray<T> apply(T func(const T&)) const;
    void resize(size_t sz, T c = T());
  };
}

The class template valarray<T> is a one-dimensional smart array, with elements numbered sequentially from zero. It is a representation of the mathematical concept of an ordered set of values. 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.282

An implementation is permitted to qualify any of the functions declared in <valarray> as inline.

281)

The intent is to specify an array template that has the minimum functionality necessary to address aliasing ambiguities and the proliferation of temporaries. Thus, the valarray template is neither a matrix class nor a field class. However, it is a very useful building block for designing such classes.

26.6.2.2 valarray constructors [valarray.cons]

valarray();

Effects: Constructs an object of class valarray<T>283 which has zero length.284

explicit valarray(size_t);

The array created by this constructor has a length equal to the value of the argument. The elements of the array are value-initialized ([dcl.init]).

valarray(const T&, size_t);

The array created by this constructor has a length equal to the second argument. The elements of the array are initialized with the value of the first argument.

valarray(const T*, size_t);

The array created by this constructor has a length equal to the second argument n. The values of the elements of the array are initialized with the first n values pointed to by the first argument.285 If the value of the second argument is greater than the number of values pointed to by the first argument, the behavior is undefined.

valarray(const valarray<T>&);

The array created by this constructor has the same length as the argument array. The elements are initialized with the values of the corresponding elements of the argument array.286

valarray(valarray<T>&& v) noexcept;

The array created by this constructor has the same length as the argument array. The elements are initialized with the values of the corresponding elements of the argument array.

Complexity: Constant.

valarray(initializer_list<T> il);

Effects: Same as valarray(il.begin(), il.size()).

valarray(const slice_array<T>&); valarray(const gslice_array<T>&); valarray(const mask_array<T>&); valarray(const indirect_array<T>&);

These conversion constructors convert one of the four reference templates to a valarray.

~valarray();

The destructor is applied to every element of *this; an implementation may return all allocated memory.

282)

For convenience, such objects are referred to as “arrays” throughout the remainder of [numarray].

283)

This default constructor is essential, since arrays of valarray may be useful. After initialization, the length of an empty array can be increased with the resize member function.

284)

This constructor is the preferred method for converting a C array to a valarray object.

285)

This copy constructor creates a distinct array rather than an alias. Implementations in which arrays share storage are permitted, but they shall implement a copy-on-reference mechanism to ensure that arrays are conceptually distinct.

26.6.2.3 valarray assignment [valarray.assign]

valarray<T>& operator=(const valarray<T>& v);

Each element of the *this array is assigned the value of the corresponding element of the argument array. 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.

Postcondition: size() == v.size().

valarray<T>& operator=(valarray<T>&& v) noexcept;

Effects: *this obtains the value of v. The value of v after the assignment is not specified.

Complexity: Linear.

valarray& operator=(initializer_list<T> il);

Effects: *this = valarray(il).

Returns: *this.

valarray<T>& operator=(const T&);

The scalar assignment operator causes each element of the *this array to be assigned the value of the argument.

valarray<T>& operator=(const slice_array<T>&); valarray<T>& operator=(const gslice_array<T>&); valarray<T>& operator=(const mask_array<T>&); valarray<T>& operator=(const indirect_array<T>&);

Requires: The length of the array to which the argument refers equals size().

These operators allow the results of a generalized subscripting operation to be assigned directly to a valarray.

If the value of an element in the left-hand side of a valarray assignment operator depends on the value of another element in that left-hand side, the resulting behavior is undefined.

26.6.2.4 valarray element access [valarray.access]

const T& operator[](size_t) const; T& operator[](size_t);

The subscript operator returns a reference to the corresponding element of the array.

Thus, the expression (a[i] = q, a[i]) == q evaluates as 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.

The expression &a[i+j] == &a[i] + j evaluates as true for all size_t i and size_t j such that i+j is less than the length of the array a.

Likewise, the expression &a[i] != &b[j] evaluates as true for any two arrays a and b and for any size_t i and size_t j such that i is less than the length of a and j is less than the length of b. This property indicates an absence of aliasing and may be used to advantage by optimizing compilers.287

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.

If the subscript operator is invoked with a size_t argument whose value is not less than the length of the array, the behavior is undefined.

286)

Compilers may take advantage of inlining, constant propagation, loop fusion, tracking of pointers obtained from operator new, and other techniques to generate efficient valarrays.

26.6.2.5 valarray subset operations [valarray.sub]

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.

valarray<T> operator[](slice slicearr) const;

Returns: An object of class valarray<T> containing those elements of the controlled sequence designated by slicearr. [ Example:

const valarray<char> v0("abcdefghijklmnop", 16);
// v0[slice(2, 5, 3)] returns valarray<char>("cfilo", 5)

— end example ]

slice_array<T> operator[](slice slicearr);

Returns: An object that holds references to elements of the controlled sequence selected by slicearr. [ Example:

valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDE", 5);
v0[slice(2, 5, 3)] = v1;
// v0 == valarray<char>("abAdeBghCjkDmnEp", 16);

— end example ]

valarray<T> operator[](const gslice& gslicearr) const;

Returns: An object of class valarray<T> containing those elements of the controlled sequence designated by gslicearr. [ Example:

const valarray<char> v0("abcdefghijklmnop", 16);
const size_t lv[] = { 2, 3 };
const size_t dv[] = { 7, 2 };
const valarray<size_t> len(lv, 2), str(dv, 2);
// v0[gslice(3, len, str)] returns
// valarray<char>("dfhkmo", 6)

— end example ]

gslice_array<T> operator[](const gslice& gslicearr);

Returns: An object that holds references to elements of the controlled sequence selected by gslicearr. [ Example:

valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDE", 5);
const size_t lv[] = { 2, 3 };
const size_t dv[] = { 7, 2 };
const valarray<size_t> len(lv, 2), str(dv, 2);
v0[gslice(3, len, str)] = v1;
// v0 == valarray<char>("abcAeBgCijDlEnFp", 16)

— end example ]

valarray<T> operator[](const valarray<bool>& boolarr) const;

Returns: An object of class valarray<T> containing those elements of the controlled sequence designated by boolarr. [ Example:

const valarray<char> v0("abcdefghijklmnop", 16);
const bool vb[] = { false, false, true, true, false, true };
// v0[valarray<bool>(vb, 6)] returns
// valarray<char>("cdf", 3)

— end example ]

mask_array<T> operator[](const valarray<bool>& boolarr);

Returns: An object that holds references to elements of the controlled sequence selected by boolarr. [ Example:

valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABC", 3);
const bool vb[] = { false, false, true, true, false, true };
v0[valarray<bool>(vb, 6)] = v1;
// v0 == valarray<char>("abABeCghijklmnop", 16)

— end example ]

valarray<T> operator[](const valarray<size_t>& indarr) const;

Returns: An object of class valarray<T> containing those elements of the controlled sequence designated by indarr. [ Example:

const valarray<char> v0("abcdefghijklmnop", 16);
const size_t vi[] = { 7, 5, 2, 3, 8 };
// v0[valarray<size_t>(vi, 5)] returns
// valarray<char>("hfcdi", 5)

— end example ]

indirect_array<T> operator[](const valarray<size_t>& indarr);

Returns: An object that holds references to elements of the controlled sequence selected by indarr. [ Example:

valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDE", 5);
const size_t vi[] = { 7, 5, 2, 3, 8 };
v0[valarray<size_t>(vi, 5)] = v1;
// v0 == valarray<char>("abCDeBgAEjklmnop", 16)

— end example ]

26.6.2.6 valarray unary operators [valarray.unary]

valarray<T> operator+() const; valarray<T> operator-() const; valarray<T> operator~() const; valarray<bool> operator!() const;

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!).

Each of these operators returns an array whose length is equal to the length of the array. Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding element of the array.

26.6.2.7 valarray computed assignment [valarray.cassign]

valarray<T>& operator*= (const valarray<T>&); valarray<T>& operator/= (const valarray<T>&); valarray<T>& operator%= (const valarray<T>&); valarray<T>& operator+= (const valarray<T>&); valarray<T>& operator-= (const valarray<T>&); valarray<T>& operator^= (const valarray<T>&); valarray<T>& operator&= (const valarray<T>&); valarray<T>& operator|= (const valarray<T>&); valarray<T>& operator<<=(const valarray<T>&); valarray<T>& operator>>=(const valarray<T>&);

Each of these operators may only be instantiated for a type T to which the indicated operator can be applied. Each of these operators performs the indicated operation on each of its elements and the corresponding element of the argument array.

The array is then returned by reference.

If the array and the argument array do not have the same length, the behavior is undefined. The appearance of an array on the left-hand side of a computed assignment does not invalidate references or pointers.

If the value of an element in the left-hand side of a valarray computed assignment operator depends on the value of another element in that left hand side, the resulting behavior is undefined.

valarray<T>& operator*= (const T&); valarray<T>& operator/= (const T&); valarray<T>& operator%= (const T&); valarray<T>& operator+= (const T&); valarray<T>& operator-= (const T&); valarray<T>& operator^= (const T&); valarray<T>& operator&= (const T&); valarray<T>& operator|= (const T&); valarray<T>& operator<<=(const T&); valarray<T>& operator>>=(const T&);

Each of these operators may only be instantiated for a type T to which the indicated operator can be applied.

Each of these operators applies the indicated operation to each element of the array and the non-array argument.

The array is then returned by reference.

The appearance of an array on the left-hand side of a computed assignment does not invalidate references or pointers to the elements of the array.

26.6.2.8 valarray member functions [valarray.members]

void swap(valarray& v) noexcept;

Effects: *this obtains the value of v. v obtains the value of *this.

Complexity: Constant.

size_t size() const;

Returns: The number of elements in the array.

Complexity: Constant time.

T sum() const;

This function may only be instantiated for a type T to which operator+= can be applied. This function returns the sum of all the elements of the array.

If the array has length 0, the behavior is undefined. If the array has length 1, sum() 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.

T min() const;

This function returns the minimum value contained in *this. The value returned for an array of length 0 is undefined. For an array of length 1, the value of element 0 is returned. For all other array lengths, the determination is made using operator<.

T max() const;

This function returns the maximum value contained in *this. The value returned for an array of length 0 is undefined. For an array of length 1, the value of element 0 is returned. For all other array lengths, the determination is made using operator<.

valarray<T> shift(int n) const;

This function returns an object of class valarray<T> of length size(), each of whose elements I is (*this)[I + n] if I + n is non-negative and less than size(), otherwise T(). Thus if element zero is taken as the leftmost element, a positive value of n shifts the elements left n places, with zero fill.

[ Example: 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 ] valarray<T> cshift(int n) const;

This function returns an object of class valarray<T> of length size() that is a circular shift of *this. If element zero is taken as the leftmost element, a non-negative value of n shifts the elements circularly left n places and a negative value of n shifts the elements circularly right -n places.

valarray<T> apply(T func(T)) const; valarray<T> apply(T func(const T&)) const;

These functions return an array whose length is equal to the array. Each element of the returned array is assigned the value returned by applying the argument function to the corresponding element of the array.

void resize(size_t sz, T c = T());

This member function changes the length of the *this array to sz and then assigns to each element the value of the second argument. Resizing invalidates all pointers and references to elements in the array.

26.6.3 valarray non-member operations [valarray.nonmembers]

26.6.3.1 valarray binary operators [valarray.binary]

template<class T> valarray<T> operator* (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator/ (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator% (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator+ (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator- (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator^ (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator& (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator| (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator<< (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator>> (const valarray<T>&, const valarray<T>&);

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 or which can be unambiguously implicitly converted to type T.

Each of these operators returns an array whose length is equal to the lengths of the argument arrays. Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding elements of the argument arrays.

If the argument arrays do not have the same length, the behavior is undefined.

template<class T> valarray<T> operator* (const valarray<T>&, const T&); template<class T> valarray<T> operator* (const T&, const valarray<T>&); template<class T> valarray<T> operator/ (const valarray<T>&, const T&); template<class T> valarray<T> operator/ (const T&, const valarray<T>&); template<class T> valarray<T> operator% (const valarray<T>&, const T&); template<class T> valarray<T> operator% (const T&, const valarray<T>&); template<class T> valarray<T> operator+ (const valarray<T>&, const T&); template<class T> valarray<T> operator+ (const T&, const valarray<T>&); template<class T> valarray<T> operator- (const valarray<T>&, const T&); template<class T> valarray<T> operator- (const T&, const valarray<T>&); template<class T> valarray<T> operator^ (const valarray<T>&, const T&); template<class T> valarray<T> operator^ (const T&, const valarray<T>&); template<class T> valarray<T> operator& (const valarray<T>&, const T&); template<class T> valarray<T> operator& (const T&, const valarray<T>&); template<class T> valarray<T> operator| (const valarray<T>&, const T&); template<class T> valarray<T> operator| (const T&, const valarray<T>&); template<class T> valarray<T> operator<<(const valarray<T>&, const T&); template<class T> valarray<T> operator<<(const T&, const valarray<T>&); template<class T> valarray<T> operator>>(const valarray<T>&, const T&); template<class T> valarray<T> operator>>(const T&, const valarray<T>&);

Each of these operators returns an array whose length is equal to the length of the array argument. Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding element of the array argument and the non-array argument.

26.6.3.2 valarray logical operators [valarray.comparison]

template<class T> valarray<bool> operator== (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator!= (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator< (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator> (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator<= (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator>= (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator&& (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator|| (const valarray<T>&, const valarray<T>&);

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 bool or which can be unambiguously implicitly converted to type bool.

Each of these operators returns a bool array whose length is equal to the length of the array arguments. Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding elements of the argument arrays.

If the two array arguments do not have the same length, the behavior is undefined.

template<class T> valarray<bool> operator==(const valarray<T>&, const T&); template<class T> valarray<bool> operator==(const T&, const valarray<T>&); template<class T> valarray<bool> operator!=(const valarray<T>&, const T&); template<class T> valarray<bool> operator!=(const T&, const valarray<T>&); template<class T> valarray<bool> operator< (const valarray<T>&, const T&); template<class T> valarray<bool> operator< (const T&, const valarray<T>&); template<class T> valarray<bool> operator> (const valarray<T>&, const T&); template<class T> valarray<bool> operator> (const T&, const valarray<T>&); template<class T> valarray<bool> operator<=(const valarray<T>&, const T&); template<class T> valarray<bool> operator<=(const T&, const valarray<T>&); template<class T> valarray<bool> operator>=(const valarray<T>&, const T&); template<class T> valarray<bool> operator>=(const T&, const valarray<T>&); template<class T> valarray<bool> operator&&(const valarray<T>&, const T&); template<class T> valarray<bool> operator&&(const T&, const valarray<T>&); template<class T> valarray<bool> operator||(const valarray<T>&, const T&); template<class T> valarray<bool> operator||(const T&, const valarray<T>&);

Each of these operators returns a bool array whose length is equal to the length of the array argument. Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding element of the array and the non-array argument.

26.6.3.3 valarray transcendentals [valarray.transcend]

template<class T> valarray<T> abs (const valarray<T>&); template<class T> valarray<T> acos (const valarray<T>&); template<class T> valarray<T> asin (const valarray<T>&); template<class T> valarray<T> atan (const valarray<T>&); template<class T> valarray<T> atan2 (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> atan2(const valarray<T>&, const T&); template<class T> valarray<T> atan2(const T&, const valarray<T>&); template<class T> valarray<T> cos (const valarray<T>&); template<class T> valarray<T> cosh (const valarray<T>&); template<class T> valarray<T> exp (const valarray<T>&); template<class T> valarray<T> log (const valarray<T>&); template<class T> valarray<T> log10(const valarray<T>&); template<class T> valarray<T> pow (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> pow (const valarray<T>&, const T&); template<class T> valarray<T> pow (const T&, const valarray<T>&); template<class T> valarray<T> sin (const valarray<T>&); template<class T> valarray<T> sinh (const valarray<T>&); template<class T> valarray<T> sqrt (const valarray<T>&); template<class T> valarray<T> tan (const valarray<T>&); template<class T> valarray<T> tanh (const valarray<T>&);

Each of these functions may only be instantiated for a type T to which a unique function with the indicated name can be applied (unqualified). This function shall return a value which is of type T or which can be unambiguously implicitly converted to type T.

26.6.3.4 valarray specialized algorithms [valarray.special]

template <class T> void swap(valarray<T>& x, valarray<T>& y) noexcept;

Effects: x.swap(y).

26.6.4 Class slice [class.slice]

26.6.4.1 Class slice overview [class.slice.overview]

namespace std {
  class slice {
  public:
    slice();
    slice(size_t, size_t, size_t);

    size_t start() const;
    size_t size() const;
    size_t stride() const;
  };
}

The slice class represents a BLAS-like slice from an array. Such a slice is specified by a starting index, a length, and a stride.288

287)

BLAS stands for Basic Linear Algebra Subprograms. C++ programs may instantiate this class. See, for example, Dongarra, Du Croz, Duff, and Hammerling: A set of Level 3 Basic Linear Algebra Subprograms; Technical Report MCS-P1-0888, Argonne National Laboratory (USA), Mathematics and Computer Science Division, August, 1988.

26.6.4.2 slice constructors [cons.slice]

slice(); slice(size_t start, size_t length, size_t stride); slice(const slice&);

The default constructor is equivalent to slice(0, 0, 0). A default constructor is provided only to permit the declaration of arrays of slices. The constructor with arguments for a slice takes a start, length, and stride parameter.

[ Example: slice(3, 8, 2) constructs a slice which selects elements 3, 5, 7, ... 17 from an array. — end example ]

26.6.4.3 slice access functions [slice.access]

size_t start() const; size_t size() const; size_t stride() const;

Returns: The start, length, or stride specified by a slice object.

Complexity: Constant time.

26.6.5 Class template slice_array [template.slice.array]

26.6.5.1 Class template slice_array overview [template.slice.array.overview]

namespace std {
  template <class T> class slice_array {
  public:
    typedef T value_type;

    void operator=  (const valarray<T>&) const;
    void operator*= (const valarray<T>&) const;
    void operator/= (const valarray<T>&) const;
    void operator%= (const valarray<T>&) const;
    void operator+= (const valarray<T>&) const;
    void operator-= (const valarray<T>&) const;
    void operator^= (const valarray<T>&) const;
    void operator&= (const valarray<T>&) const;
    void operator|= (const valarray<T>&) const;
    void operator<<=(const valarray<T>&) const;
    void operator>>=(const valarray<T>&) const;

    slice_array(const slice_array&);
    ~slice_array();
    const slice_array& operator=(const slice_array&) const;
  void operator=(const T&) const;

    slice_array() = delete;       // as implied by declaring copy constructor above
  };
}

The slice_array template is a helper template used by the slice subscript operator

slice_array<T> valarray<T>::operator[](slice);

It has reference semantics to a subset of an array specified by a slice object.

[ Example: The expression a[slice(1, 5, 3)] = b; has the effect of assigning the elements of b to a slice of the elements in a. For the slice shown, the elements selected from a are 1, 4, ..., 13. — end example ]

26.6.5.2 slice_array assignment [slice.arr.assign]

void operator=(const valarray<T>&) const; const slice_array& operator=(const slice_array&) const;

These assignment operators have reference semantics, assigning the values of the argument array elements to selected elements of the valarray<T> object to which the slice_array object refers.

26.6.5.3 slice_array computed assignment [slice.arr.comp.assign]

void operator*= (const valarray<T>&) const; void operator/= (const valarray<T>&) const; void operator%= (const valarray<T>&) const; void operator+= (const valarray<T>&) const; void operator-= (const valarray<T>&) const; void operator^= (const valarray<T>&) const; void operator&= (const valarray<T>&) const; void operator|= (const valarray<T>&) const; void operator<<=(const valarray<T>&) const; void operator>>=(const valarray<T>&) const;

These computed assignments have reference semantics, applying the indicated operation to the elements of the argument array and selected elements of the valarray<T> object to which the slice_array object refers.

26.6.5.4 slice_array fill function [slice.arr.fill]

void operator=(const T&) const;

This function has reference semantics, assigning the value of its argument to the elements of the valarray<T> object to which the slice_array object refers.

26.6.6 The gslice class [class.gslice]

26.6.6.1 The gslice class overview [class.gslice.overview]

namespace std {
  class gslice {
  public:
    gslice();
    gslice(size_t s, const valarray<size_t>& l, const valarray<size_t>& d);

    size_t           start() const;
    valarray<size_t> size() const;
    valarray<size_t> stride() const;
  };
}

This class represents a generalized slice out of an array. A gslice is defined by a starting offset (s), a set of lengths (l_j), and a set of strides (d_j). The number of lengths shall equal the number of strides.

A gslice represents a mapping from a set of indices (i_j), equal in number to the number of strides, to a single index k. It is useful for building multidimensional array classes using the valarray template, which is one-dimensional. The set of one-dimensional index values specified by a gslice are $k = s + \sum_ji_jd_j$ where the multidimensional indices i_j range in value from 0 to l_ij - 1.

[ Example: The gslice specification

start  = 3
length = {2, 4, 3}
stride = {19, 4, 1}

yields the sequence of one-dimensional indices

k = 3 + (0,1) × 19 + (0,1,2,3) × 4 + (0,1,2) × 1

which are ordered as shown in the following table:

	(i₀,   i₁,   i₂,   k)   =
		(0,   0,   0,    3),    
		(0,   0,   1,    4),    
		(0,   0,   2,    5),    
		(0,   1,   0,    7),    
		(0,   1,   1,    8),    
		(0,   1,   2,    9),    
		(0,   2,   0,   11), 
		(0,   2,   1,   12), 
		(0,   2,   2,   13), 
		(0,   3,   0,   15), 
		(0,   3,   1,   16), 
		(0,   3,   2,   17), 
		(1,   0,   0,   22), 
		(1,   0,   1,   23), 
		…      
		(1,   3,   2,   36)

That is, the highest-ordered index turns fastest. — end example ]

It is possible to have degenerate generalized slices in which an address is repeated.

[ Example: If the stride parameters in the previous example are changed to {1, 1, 1}, the first few elements of the resulting sequence of indices will be

	(0,   0,   0,    3),  
	(0,   0,   1,    4),  
	(0,   0,   2,    5),  
	(0,   1,   0,    4),  
	(0,   1,   1,    5),  
	(0,   1,   2,    6),  
	…

— end example ]

If a degenerate slice is used as the argument to the non-const version of operator[](const gslice&), the resulting behavior is undefined.

26.6.6.2 gslice constructors [gslice.cons]

gslice(); gslice(size_t start, const valarray<size_t>& lengths, const valarray<size_t>& strides); gslice(const gslice&);

The default constructor is equivalent to gslice(0, valarray<size_t>(), valarray<size_t>()). The constructor with arguments builds a gslice based on a specification of start, lengths, and strides, as explained in the previous section.

26.6.6.3 gslice access functions [gslice.access]

size_t start() const; valarray<size_t> size() const; valarray<size_t> stride() const;

Returns: The representation of the start, lengths, or strides specified for the gslice.

Complexity: start() is constant time. size() and stride() are linear in the number of strides.

26.6.7 Class template gslice_array [template.gslice.array]

26.6.7.1 Class template gslice_array overview [template.gslice.array.overview]

namespace std {
  template <class T> class gslice_array {
  public:
    typedef T value_type;

    void operator=  (const valarray<T>&) const;
    void operator*= (const valarray<T>&) const;
    void operator/= (const valarray<T>&) const;
    void operator%= (const valarray<T>&) const;
    void operator+= (const valarray<T>&) const;
    void operator-= (const valarray<T>&) const;
    void operator^= (const valarray<T>&) const;
    void operator&= (const valarray<T>&) const;
    void operator|= (const valarray<T>&) const;
    void operator<<=(const valarray<T>&) const;
    void operator>>=(const valarray<T>&) const;

    gslice_array(const gslice_array&);
    ~gslice_array();
    const gslice_array& operator=(const gslice_array&) const;
    void operator=(const T&) const;

    gslice_array() = delete;      // as implied by declaring copy constructor above
  };
}

This template is a helper template used by the slice subscript operator

gslice_array<T> valarray<T>::operator[](const gslice&);

It has reference semantics to a subset of an array specified by a gslice object.

Thus, the expression a[gslice(1, length, stride)] = b has the effect of assigning the elements of b to a generalized slice of the elements in a.

26.6.7.2 gslice_array assignment [gslice.array.assign]

void operator=(const valarray<T>&) const; const gslice_array& operator=(const gslice_array&) const;

These assignment operators have reference semantics, assigning the values of the argument array elements to selected elements of the valarray<T> object to which the gslice_array refers.

26.6.7.3 gslice_array [gslice.array.comp.assign]

26.6.7.4 gslice_array fill function [gslice.array.fill]

void operator=(const T&) const;

This function has reference semantics, assigning the value of its argument to the elements of the valarray<T> object to which the gslice_array object refers.

26.6.8 Class template mask_array [template.mask.array]

26.6.8.1 Class template mask_array overview [template.mask.array.overview]

namespace std {
  template <class T> class mask_array {
  public:
    typedef T value_type;

    void operator=  (const valarray<T>&) const;
    void operator*= (const valarray<T>&) const;
    void operator/= (const valarray<T>&) const;
    void operator%= (const valarray<T>&) const;
    void operator+= (const valarray<T>&) const;
    void operator-= (const valarray<T>&) const;
    void operator^= (const valarray<T>&) const;
    void operator&= (const valarray<T>&) const;
    void operator|= (const valarray<T>&) const;
    void operator<<=(const valarray<T>&) const;
    void operator>>=(const valarray<T>&) const;

    mask_array(const mask_array&);
   ~mask_array();
    const mask_array& operator=(const mask_array&) const;
    void operator=(const T&) const;

    mask_array() = delete;        // as implied by declaring copy constructor above
  };
}

This template is a helper template used by the mask subscript operator:

mask_array<T> valarray<T>::operator[](const valarray<bool>&).

It has reference semantics to a subset of an array specified by a boolean mask. Thus, the expression a[mask] = b; has the effect of assigning the elements of b to the masked elements in a (those for which the corresponding element in mask is true.)

26.6.8.2 mask_array assignment [mask.array.assign]

void operator=(const valarray<T>&) const; const mask_array& operator=(const mask_array&) const;

These assignment operators have reference semantics, assigning the values of the argument array elements to selected elements of the valarray<T> object to which it refers.

26.6.8.3 mask_array computed assignment [mask.array.comp.assign]

26.6.8.4 mask_array fill function [mask.array.fill]

void operator=(const T&) const;

This function has reference semantics, assigning the value of its argument to the elements of the valarray<T> object to which the mask_array object refers.

26.6.9 Class template indirect_array [template.indirect.array]

26.6.9.1 Class template indirect_array overview [template.indirect.array.overview]

namespace std {
  template <class T> class indirect_array {
  public:
    typedef T value_type;

    void operator=  (const valarray<T>&) const;
    void operator*= (const valarray<T>&) const;
    void operator/= (const valarray<T>&) const;
    void operator%= (const valarray<T>&) const;
    void operator+= (const valarray<T>&) const;
    void operator-= (const valarray<T>&) const;
    void operator^= (const valarray<T>&) const;
    void operator&= (const valarray<T>&) const;
    void operator|= (const valarray<T>&) const;
    void operator<<=(const valarray<T>&) const;
    void operator>>=(const valarray<T>&) const;

    indirect_array(const indirect_array&);
   ~indirect_array();
    const indirect_array& operator=(const indirect_array&) const;
    void operator=(const T&) const;

    indirect_array() = delete;        // as implied by declaring copy constructor above
  };
}

This template is a helper template used by the indirect subscript operator

indirect_array<T> valarray<T>::operator[](const valarray<size_t>&).

It has reference semantics to a subset of an array specified by an indirect_array. Thus the expression a[indirect] = b; has the effect of assigning the elements of b to the elements in a whose indices appear in indirect.

26.6.9.2 indirect_array assignment [indirect.array.assign]

void operator=(const valarray<T>&) const; const indirect_array& operator=(const indirect_array&) const;

These assignment operators have reference semantics, assigning the values of the argument array elements to selected elements of the valarray<T> object to which it refers.

If the indirect_array specifies an element in the valarray<T> object to which it refers more than once, the behavior is undefined.

[ Example:

int addr[] = {2, 3, 1, 4, 4};
valarray<size_t> indirect(addr, 5);
valarray<double> a(0., 10), b(1., 5);
a[indirect] = b;

results in undefined behavior since element 4 is specified twice in the indirection. — end example ]

26.6.9.3 indirect_array computed assignment [indirect.array.comp.assign]

If the indirect_array specifies an element in the valarray<T> object to which it refers more than once, the behavior is undefined.

26.6.9.4 indirect_array fill function [indirect.array.fill]

void operator=(const T&) const;

This function has reference semantics, assigning the value of its argument to the elements of the valarray<T> object to which the indirect_array object refers.

26.6.10 valarray range access [valarray.range]

In the begin and end function templates that follow, unspecified1 is a type that meets the requirements of a mutable random access iterator ([random.access.iterators]) whose value_type is the template parameter T and whose reference type is T&. unspecified2 is a type that meets the requirements of a constant random access iterator ([random.access.iterators]) whose value_type is the template parameter T and whose reference type is const T&.

The iterators returned by begin and end for an array are guaranteed to 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.

template <class T> unspecified1 begin(valarray<T>& v); template <class T> unspecified2 begin(const valarray<T>& v);

Returns: An iterator referencing the first value in the numeric array.

template <class T> unspecified1 end(valarray<T>& v); template <class T> unspecified2 end(const valarray<T>& v);

Returns: An iterator referencing one past the last value in the numeric array.

26 Numerics library [numerics]

26.6 Numeric arrays [numarray]

26.6.1 Header <valarray> synopsis [valarray.syn]

26.6.2 Class template valarray [template.valarray]

26.6.2.1 Class template valarray overview [template.valarray.overview]

26.6.2.2 valarray constructors [valarray.cons]

26.6.2.3 valarray assignment [valarray.assign]

26.6.2.4 valarray element access [valarray.access]

26.6.2.5 valarray subset operations [valarray.sub]

26.6.2.6 valarray unary operators [valarray.unary]

26.6.2.7 valarray computed assignment [valarray.cassign]

26.6.2.8 valarray member functions [valarray.members]

26.6.3 valarray non-member operations [valarray.nonmembers]

26.6.3.1 valarray binary operators [valarray.binary]

26.6.3.2 valarray logical operators [valarray.comparison]

26.6.3.3 valarray transcendentals [valarray.transcend]

26.6.3.4 valarray specialized algorithms [valarray.special]

26.6.4 Class slice [class.slice]

26.6.4.1 Class slice overview [class.slice.overview]

26.6.4.2 slice constructors [cons.slice]

26.6.4.3 slice access functions [slice.access]

26.6.5 Class template slice_array [template.slice.array]

26.6.5.1 Class template slice_array overview [template.slice.array.overview]

26.6.5.2 slice_array assignment [slice.arr.assign]

26.6.5.3 slice_array computed assignment [slice.arr.comp.assign]

26.6.5.4 slice_array fill function [slice.arr.fill]

26.6.6 The gslice class [class.gslice]

26.6.6.1 The gslice class overview [class.gslice.overview]

26.6.6.2 gslice constructors [gslice.cons]

26.6.6.3 gslice access functions [gslice.access]

26.6.7 Class template gslice_array [template.gslice.array]

26.6.7.1 Class template gslice_array overview [template.gslice.array.overview]

26.6.7.2 gslice_array assignment [gslice.array.assign]

26.6.7.3 gslice_array [gslice.array.comp.assign]

26.6.7.4 gslice_array fill function [gslice.array.fill]

26.6.8 Class template mask_array [template.mask.array]

26.6.8.1 Class template mask_array overview [template.mask.array.overview]

26.6.8.2 mask_array assignment [mask.array.assign]

26.6.8.3 mask_array computed assignment [mask.array.comp.assign]

26.6.8.4 mask_array fill function [mask.array.fill]

26.6.9 Class template indirect_array [template.indirect.array]

26.6.9.1 Class template indirect_array overview [template.indirect.array.overview]

26.6.9.2 indirect_array assignment [indirect.array.assign]

26.6.9.3 indirect_array computed assignment [indirect.array.comp.assign]

26.6.9.4 indirect_array fill function [indirect.array.fill]

26.6.10 valarray range access [valarray.range]