Man Page mask_array.3

                       Standard C++ Library
             Copyright 1998, Rogue Wave Software, Inc.

NAME

     mask_array

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

SYNOPSIS

     #include <valarray>
     template <class T>
     class mask_array;

DESCRIPTION

     mask_array<T>  gives  a  masked  view   into   a   valarray.
     mask_arrays are only 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 dis-
     tinct elements. The template cannot be instantiated directly
     since  all  its  constructors  are private. However, you can
     copy a slice_array to a valarray using either  the  valarray
     copy  constructor  or  the  assignment  operator.  Reference
     semantics are lost at that point.

INTERFACE

     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 FUNCTIONS

     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" // Contains a valarray stream inserter
     using namespace std;

     int main(void)
     {
      int ibuf[10] = {0,1,2,3,4,5,6,7,8,9};
      bool mbuf[10] = {1,0,1,1,1,0,0,1,1,0};

       // create a valarray of ints
      valarray<int>         vi(ibuf,10);

       // create a valarray of bools for a mask
      valarray<bool> mask(mbuf,10);

       // print out the valarray<int>
      cout << vi << endl;

       // Get a mask array and assign that mask to another array
      mask_array<int> msk = vi[mask];
      valarray<int> vi3 = msk;

       // print out the masked_array
      cout << vi3 << endl;

       // Double the masked values
      msk += vi3;

       // print out vi1 again
      cout << vi << endl;

      return 0;
     }

     Program Output




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

WARNINGS

     If your compiler does not support namespaces,  then  you  do
     not need the using declaration for std.

SEE ALSO

     slice,   slice_array,   valarray,   gslice,    gslice_array,
     indirect_array