26 Numerics library [numerics]

26.7 Numeric arrays [numarray]

26.7.2 Class template valarray [template.valarray]

26.7.2.1 Overview [template.valarray.overview]

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

    // [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& operator=(const valarray&);
    valarray& operator=(valarray&&) noexcept;
    valarray& operator=(initializer_list<T>);
    valarray& operator=(const T&);
    valarray& operator=(const slice_array<T>&);
    valarray& operator=(const gslice_array<T>&);
    valarray& operator=(const mask_array<T>&);
    valarray& operator=(const indirect_array<T>&);

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

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

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

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

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

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

    size_t size() const;

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

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

  template<class T, size_t cnt> valarray(const T(&)[cnt], size_t) -> valarray<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.

For convenience, an 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.249

249)

The intent is to specify an array template that has the minimum functionality necessary to address aliasing ambiguities and the proliferation of temporary objects.

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.7.2.2 Constructors [valarray.cons]

🔗

valarray();

Effects: Constructs a valarray that has zero length.250

🔗

explicit valarray(size_t n);

Effects: Constructs a valarray that has length n.

Each element of the array is value-initialized .

🔗

valarray(const T& v, size_t n);

Effects: Constructs a valarray that has length n.

Each element of the array is initialized with v.

🔗

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.251

🔗

valarray(const valarray& v);

Effects: Constructs a valarray that has the same length as v.

The elements are initialized with the values of the corresponding elements of v.252

🔗

valarray(valarray&& v) noexcept;

Effects: Constructs a valarray that has the same length as v.

The elements are initialized with the values of the corresponding elements of v.

Complexity: Constant.

🔗

valarray(initializer_list<T> il);

Effects: Equivalent to 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();

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

250)

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.

⮥

251)

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

⮥

252)

This copy constructor creates a distinct array rather than an alias.

Implementations in which arrays share storage are permitted, but they would need to implement a copy-on-reference mechanism to ensure that arrays are conceptually distinct.

⮥

26.7.2.3 Assignment [valarray.assign]

🔗

valarray& operator=(const valarray& v);

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

🔗

valarray& operator=(valarray&& v) noexcept;

Effects: *this obtains the value of v.

The value of v after the assignment is not specified.

Returns: *this.

Complexity: Linear.

🔗

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

Effects: Equivalent to: return *this = valarray(il);

🔗

valarray& operator=(const T& v);

Effects: Assigns v to each element of *this.

Returns: *this.

🔗

valarray& operator=(const slice_array<T>&);
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.

26.7.2.4 Element access [valarray.access]

🔗

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

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

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 valarrays.

— end note

]

The reference returned by the subscript operator for an array shall be valid until the member function resize(size_t, T) is called for that array or until the lifetime of that array ends, whichever happens first.

26.7.2.5 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) shall exist.

🔗

valarray operator[](slice slicearr) const;

Returns: A valarray 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 operator[](const gslice& gslicearr) const;

Returns: A valarray 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("ABCDEF", 6);
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 operator[](const valarray<bool>& boolarr) const;

Returns: A valarray 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 operator[](const valarray<size_t>& indarr) const;

Returns: A valarray 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.7.2.6 Unary operators [valarray.unary]

🔗

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.

26.7.2.7 Compound assignment [valarray.cassign]

🔗

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

Remarks: The appearance of an array on the left-hand side of a compound assignment does not invalidate references or pointers.

🔗

valarray& operator*= (const T& v);
valarray& operator/= (const T& v);
valarray& operator%= (const T& v);
valarray& operator+= (const T& v);
valarray& operator-= (const T& v);
valarray& operator^= (const T& v);
valarray& operator&= (const T& v);
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.

26.7.2.8 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;

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.

🔗

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

🔗

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

🔗

valarray shift(int n) const;

Returns: A valarray of length size(), each of whose elements I is (*this)[I + n] if I + n is non-negative and less than size(), otherwise T().

[Note

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

If the argument has the value -2, the first two elements of the result will be value-initialized; the third element of the result will be assigned the value of the first element of the argument; etc.

— end example

]

🔗

valarray cshift(int n) const;

Returns: A valarray 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 apply(T func(T)) const;
valarray apply(T func(const T&)) const;

Returns: A valarray whose length is size().

Each element of the returned array is assigned the value returned by applying the argument function to the corresponding element of *this.

🔗

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

Effects: 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.