Apache C++ Standard Library Reference Guide

## mask_array

Library: Numerics

    Does not inherit

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Constructors
- Assignment Operators
- Computed Assignment Operators
- Member Function
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

mask_array() operator%=() operator&=() | operator>>=() operator<<=() operator*=() | operator+=() operator-=() operator/=() | operator=() operator^=() operator|

### Summary

A numeric array class that gives a masked view of a valarray

### Synopsis

    #include <valarray>

    namespace std {
      template <class T>
      class mask_array;
    }

### Description

mask_array gives a masked view into a valarray. A mask_array can only be produced by applying the mask subscript operator to a valarray. This subscript operator takes a valarray<bool> argument and produces a mask_array. Only the elements in the valarray whose corresponding elements in the valarray<bool> argument were `true` are selected by the mask_array. The elements in a mask_array are references to selected elements in the valarray (so changing an element in the mask_array really changes the corresponding element in the valarray). A mask_array does not itself hold any distinct elements. The template cannot be instantiated directly since all its constructors are private. However, you can copy a mask_array to a valarray using either the valarray copy constructor or the assignment operator. Reference semantics are lost at that point.

### Interface

    namespace std {

      template <class T> class mask_array {
      public:

        // types
        typedef T value_type;

        // destructor
        ~mask_array();

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

        // other
        void operator=(const T&) const;

      private:
        // constructors
        mask_array();
        mask_array(const mask_array<T>&);
        // operator=
        mask_array<T>& operator=(const mask_array<T>& array);
      };
    }

### Constructors

    mask_array();
    mask_array(const mask_array&);

All mask_array constructors are private and cannot be called directly. This prevents copy construction of mask_arrays.

### Assignment Operators

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

Assigns values from `x` to the selected elements of the valarray that self refers to. Remember that a mask_array never holds any elements itself, it simply refers to selected elements in the valarray used to generate it.

    mask_array<T>&
    operator=(const mask_array<T>& x);

Private assignment operator. Cannot be called directly, thus preventing assignment between mask_arrays.

### Computed Assignment Operators

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

Applies the indicated operation using elements from `val` to the selected elements of the valarray that self refers to. Remember that a mask_array never holds any elements itself; it simply refers to selected elements in the valarray used to generate it.

### Member Function

    void operator=(const T& x) const;

Assigns `x` to the selected elements of the valarray that self refers to.

### Example

    //
    //  mask_array.cpp
    //

    #include <valarray.h>  // Includes valarray and
                           // provides stream inserter.

    typedef std::valarray<int>    valarray_t;
    typedef std::valarray<bool>   maskarray_t;

    int main(void) {

      // Create a valarray of ints.
      valarray_t::value_type   ibuf[10] = {0,1,2,3,4,5,6,7,8,9};
      valarray_t               vi(ibuf, 10);

      // Create a valarray of bools for a mask.
      maskarray_t::value_type  mbuf[10] = {1,0,1,1,1,0,0,1,1,0};
      maskarray_t              mask(mbuf,10);

      // Print out the valarray<int>.
      std::cout << "original valarray<int> vi\n\n" << vi << "\n\n";

      // Print out the valarray<bool>.
      std::cout << "original valarray<bool> mask\n\n" << mask
                << "\n\n";

      // Print a mask array.
      std::cout << "vi[mask]\n\n" << vi[mask] << "\n\n";

      // Double the values of the masked array and print out.
      vi[mask] += static_cast<valarray_t> (vi[mask]);
      std::cout << "vi[mask] += vi[mask]\n\n" << vi << std::endl;

      return 0;
    }

    Program Output:

    original valarray<int> vi

    [0,1,2,3,4,5,6,7,8,9]

    original valarray<bool> mask

    [1,0,1,1,1,0,0,1,1,0]

    vi[mask]

    [0,2,3,4,7,8]

    vi[mask] += vi[mask]

    [0,1,4,6,8,5,6,14,16,9]

### See Also

slice, slice_array, valarray, gslice, gslice_array, indirect_array

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 26.3.8