casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
MaskedArray.h
Go to the documentation of this file.
00001 //# MaskedArray.h: A templated N-D masked array class with zero origin.
00002 //# Copyright (C) 1993,1994,1995,1996,1997,1999,2000,2005
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: MaskedArray.h 21130 2011-10-18 07:39:05Z gervandiepen $
00027 
00028 #ifndef CASA_MASKEDARRAY_H
00029 #define CASA_MASKEDARRAY_H
00030 
00031 
00032 //# Includes
00033 #include <casa/aips.h>
00034 #include <casa/Arrays/IPosition.h>
00035 #include <casa/Utilities/CountedPtr.h>
00036 #include <casa/Arrays/LogiArrayFwd.h>
00037 #include <casa/Arrays/MaskLogiArrFwd.h>
00038 
00039 namespace casa { //# NAMESPACE CASA - BEGIN
00040 
00041 //# Forward declarations
00042 //# <note role=warning>
00043 //#   Array.h cannot be included in this header file.  Anything needed
00044 //#   from it must be forwarded.  This is why LogicalArrayFwd.h is
00045 //#   included instead of LogicalArray.h .
00046 //# </note>
00047 template <class T> class Array;
00048 class Slicer;
00049 
00050 
00051 // <summary> Class for masking an Array for operations on that Array. </summary>
00052 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMaskedArray tMaskArrExcp">
00053 // </reviewed>
00054 //
00055 // <prerequisite>
00056 //   <li> <linkto class=Array>Array</linkto>
00057 //   <li> <linkto group="LogiArray.h#LogicalArray">LogicalArray</linkto>
00058 // </prerequisite>
00059 //
00060 // <etymology>
00061 // MaskedArray is a class for masking elements of an Array while performing
00062 // operations on that Array.
00063 // </etymology>
00064 //
00065 // <synopsis>
00066 // A MaskedArray is an association between an Array and a mask.  The mask
00067 // selects elements of the Array.  Only elements of the Array where the
00068 // corresponding element of the mask is True are defined.  Thus, operations
00069 // on a MaskedArray only operate on those elements of the Array where the 
00070 // corresponding element of the mask is True.
00071 //
00072 // A MaskedArray should be thought of as a manipulator for an Array, analogous
00073 // to an iterator.  It allows one to perform whole Array operations on selected
00074 // elements of the Array.
00075 //
00076 // The mask used in the constructor for the MaskedArray must conform to
00077 // the Array, thus have the same shape.
00078 // The internal mask is (will be) copy constructed with reference semantics
00079 // from the input mask. Therefore, it is (will be) possible to change the
00080 // internal mask by changing values in the input mask *after* the MaskedArray
00081 // has been constructed.  To ensure that the internal mask is independent of
00082 // the input mask after construction, use mask.copy() as the input argument.
00083 //
00084 // One can explicitly construct a MaskedArray from an Array and a mask or
00085 // a MaskedArray and a mask.  One can also use operator() on an Array or
00086 // a MaskedArray to implicitly create a MaskedArray.
00087 //
00088 // One can create a MaskedArray from a MaskedArray and a mask.  The resulting
00089 // MaskedArray has as its Array the Array from the original MaskedArray.
00090 // The mask for the resulting MaskedArray is the AND of the mask from the
00091 // original MaskedArray and the input mask.
00092 //
00093 // Any operation involving a MaskedArray or a set of MaskedArrays is only
00094 // performed for those elements where the AND of the masks is True.
00095 //
00096 // Any operation involving a MaskedArray or a set of MaskedArrays results
00097 // in a MaskedArray whose mask is the AND of the masks of the original
00098 // MaskedArrays.  The only exception to this is assignment, where the
00099 // mask determines which elements of the underlying Array are assigned.
00100 //
00101 // Masks, which are LogicalArrays, can be constructed by logical operations
00102 // involving Arrays.  They can also, of course, be constructed by individually
00103 // setting individual elements of an LogicalArray.
00104 //
00105 // MaskedArrays constructed directly from Arrays are by default writeable.
00106 // MaskedArrays constructed indirectly from Arrays by <src>operator()</src>
00107 // are writeable if the Array is non-const and are readonly if the
00108 // Array is const.
00109 // MaskedArrays constructed from other MaskedArrays, either directly by
00110 // constructors or indirectly by <src>operator()</src>, are by default
00111 // writeable if the input MaskedArray is writeable, and readonly if the
00112 // input MaskedArray is readonly.
00113 //
00114 // A given MaskedArray can be set to be readonly.  One specifies
00115 // this in the constructor with the Bool argument <src>isreadonly</src>,
00116 // or calls the <src>setReadOnly()</src> member function.
00117 // A MaskedArray which would default to be readonly cannot be forced to
00118 // be writeable.  It will remain readonly even if the Bool argument
00119 // <src>isreadonly</src> is set to be <src>False</src>.
00120 //
00121 // The <src>isReadOnly(),</src> member function is used to test whether
00122 // the MaskedArray is readonly.
00123 //
00124 // Member functions which change the MaskedArray test to see whether
00125 // the MaskedArray is readonly, and throw an ArrayError exception if
00126 // it is.  These member functions are:
00127 // <ul>
00128 //    <li> <src>operator=()</src>
00129 //    <li> <src>getRWArray()</src>
00130 //    <li> <src>getRWArrayStorage()</src>
00131 //    <li> <src>putArrayStorage()</src>
00132 // </ul>
00133 //
00134 // The copy() member function makes a deep copy of a MaskedArray.
00135 // By default it returns a writeable MaskedArray, but the MaskedArray
00136 // returned can be made readonly by using the Bool argument "isreadonly"
00137 // to copy() (or by calling setReadOnly() on the new MaskedArray).
00138 //
00139 // The valid elements of the MaskedArray can be manipulated as a
00140 // "compressed" Array which contains only the valid elements.
00141 // The number of elements in this "compressed" Array is the number of valid
00142 // elements in the MaskedArray, <src>nelementsValid()</src>.
00143 // The "compressed" Array can have any shape which meets this requirement.
00144 // The MaskedArray can have any shape.
00145 //
00146 // The <src>getCompressedArray()</src> member functions get a compressed
00147 // Array from the valid members of the MaskedArray, while the
00148 // <src>setCompressedArray()</src> member function sets the valid members
00149 // of the MaskedArray from the input compressed Array.
00150 //
00151 // Many mathematical and logical global operators and functions which operate
00152 // on MaskedArrays are defined.  Typically, they are defined for all sensible
00153 // combinations of MaskedArrays, Arrays, and scalars.
00154 //
00155 // Mathematical global operators and functions are defined in
00156 // Arrays/MaskArrMath.h .
00157 // The list is:
00158 // <ul>
00159 //   <li> operator+= ()
00160 //   <li> operator-= ()
00161 //   <li> operator*= ()
00162 //   <li> operator/= ()
00163 //   <li> operator+ ()
00164 //   <li> operator- ()
00165 //   <li> operator* ()
00166 //   <li> operator/ ()
00167 //   <li> sin ()
00168 //   <li> cos ()
00169 //   <li> tan ()
00170 //   <li> asin ()
00171 //   <li> acos ()
00172 //   <li> atan ()
00173 //   <li> sinh ()
00174 //   <li> cosh ()
00175 //   <li> tanh ()
00176 //   <li> exp ()
00177 //   <li> log ()
00178 //   <li> log10 ()
00179 //   <li> sqrt ()
00180 //   <li> abs ()
00181 //   <li> fabs ()
00182 //   <li> ceil ()
00183 //   <li> floor ()
00184 //   <li> atan2 ()
00185 //   <li> fmod ()
00186 //   <li> pow ()
00187 //   <li> minMax ()
00188 //   <li> min ()
00189 //   <li> max ()
00190 //   <li> indgen ()
00191 //   <li> sum ()
00192 //   <li> sumsquares ()
00193 //   <li> product ()
00194 //   <li> mean ()
00195 //   <li> variance ()
00196 //   <li> stddev ()
00197 //   <li> avdev ()
00198 //   <li> median ()
00199 //   <li> square ()
00200 //   <li> cube ()
00201 // </ul>
00202 //
00203 // Logical global operators and functions are defined in
00204 // Arrays/MaskArrLogi.h .
00205 // The list is:
00206 // <ul>
00207 //   <li> allLE ()
00208 //   <li> allLT ()
00209 //   <li> allGE ()
00210 //   <li> allGT ()
00211 //   <li> allEQ ()
00212 //   <li> allNE ()
00213 //   <li> allAND ()
00214 //   <li> allOR ()
00215 //   <li> anyLE ()
00216 //   <li> anyLT ()
00217 //   <li> anyGE ()
00218 //   <li> anyGT ()
00219 //   <li> anyEQ ()
00220 //   <li> anyNE ()
00221 //   <li> anyAND ()
00222 //   <li> anyOR ()
00223 //   <li> operator<= ()
00224 //   <li> operator<  ()
00225 //   <li> operator>= ()
00226 //   <li> operator<  ()
00227 //   <li> operator== ()
00228 //   <li> operator!= ()
00229 //   <li> operator&& ()
00230 //   <li> operator|| ()
00231 // </ul>
00232 // </synopsis>
00233 //
00234 // <example>
00235 // Use an explicit MaskedArray to limit the maximum value of an Array.
00236 //
00237 // <srcblock>
00238 //   Vector<Int> arr (20);
00239 //      . . .
00240 //   MaskedArray<Int> marr (arr, (arr > 5));
00241 //   marr = 5;
00242 // </srcblock>
00243 //
00244 // This sets all elements of arr which are greater than 5 to 5.
00245 // </example>
00246 //
00247 // <example>
00248 // Use an implicit MaskedArray to limit the minimum value of an Array.
00249 //
00250 // <srcblock>
00251 //   Vector<Int> arr (20);
00252 //      . . .
00253 //   arr (arr < 0) = 0;
00254 // </srcblock>
00255 //
00256 // This sets all elements of arr which are less than 0 to 0.
00257 // </example>
00258 //
00259 // <example>
00260 // It does not matter where in an expression the MaskedArrays are located.
00261 // The operation is only performed on those elements where the AND of the
00262 // masks is True.
00263 //
00264 // The following expressions are all equivalent.
00265 // The first (and second) expressions are the most efficient, since the sum
00266 // is only performed for those elements where ((a > 0) && (b > 0)).
00267 // The third example is less efficient, since the sum is performed for
00268 // all elements of a and b, and then the assignment is only performed for
00269 // those elements where ((a > 0) && (b > 0)).
00270 //
00271 // <srcblock>
00272 //   Vector<Int> arr (20);
00273 //   Vector<Int> a (20);
00274 //   Vector<Int> b (20);
00275 //      . . .
00276 //   arr = a(a > 0) + b(b > 0);
00277 //
00278 //   arr = a(b > 0) + b(a > 0);
00279 //
00280 //   arr ((a > 0) && (b > 0)) = a + b;
00281 //
00282 //   arr = (a + b) ((a > 0) && (b > 0));
00283 //
00284 //   arr (a > 0) = a + b(b > 0);
00285 //
00286 // </srcblock>
00287 //
00288 // All of these expressions set those elements of arr where
00289 // ((a > 0) && (b > 0)) to a + b.  Those elements of arr where the condition
00290 // is False are unchanged.
00291 // </example>
00292 //
00293 // <example>
00294 // This example extracts the valid elements of the MaskedArray as a
00295 // "compressed" Vector, manipulates this Vector, and then puts the result
00296 // back into the MaskedArray.
00297 //
00298 // <srcblock>
00299 //   Matrix<Int> arr (20,5);
00300 //      . . .
00301 //   MaskedArray<Int> marr (arr, (arr>0) && (arr<10));
00302 //   Vector<Int> vec (marr.getCompressedArray());
00303 //      . . .
00304 //   marr.setCompressedArray (vec);
00305 // </srcblock>
00306 //
00307 // </example>
00308 //
00309 // <motivation>
00310 // A MaskedArray is an association between an Array and a LogicalArray which
00311 // masks the Array.  It allows one to perform whole Array manipulations
00312 // with a single expression, selecting those elements of the Array to modify
00313 // based either on a logical expression, typically involving some of the
00314 // Arrays involved in the expression, or based on a specifically set mask.
00315 // </motivation>
00316 //
00317 // <todo asof="$DATE:$>
00318 //   <li> Consider whether there should be constructors for masks
00319 //          specified as Array<Bool>.
00320 //   <li> Change constructors to always do copy construction with
00321 //          reference semantics when creating the internal mask.
00322 // </todo>
00323 
00324 
00325 template<class T> class MaskedArray
00326 {
00327 
00328 public:
00329   // Default constructor for a MaskedArray does not allocate any memory
00330   // for the Data array or Mask. Hence the masked array 
00331   // should not be used until some data is allocated to the object using one
00332   // of the set functions.
00333   MaskedArray();
00334   // Reset the data and mask of the the MaskedArray. There should perhaps be
00335   // a whole family of setData functions with different arguements,
00336   // analogous to the constructors. However these are sufficient for the
00337   // moment. 
00338   void setData(const Array<T> & data, const LogicalArray & mask, 
00339           Bool isReadOnly=False);
00340   void setData(const MaskedArray<T> & array, Bool isReadOnly=False);
00341     // Create a MaskedArray from an Array and a LogicalArray.
00342     //
00343     // The internal mask is a total copy of the input mask, and is
00344     // completely independent of the input mask.
00345     //
00346     // The Array is copy constructed, which means that it is a really smart
00347     // pointer to the underlying Block, and shares this Block with the input
00348     // Array.
00349     //
00350     // By default, the MaskedArray constructed is writeable.  If
00351     // <src>isreadonly</src> is <src>True</src>, then the MaskedArray
00352     // returned is readonly.
00353     //
00354     // <thrown>
00355     //    <li> ArrayConformanceError
00356     // </thrown>
00357     //
00358     // <group>
00359     MaskedArray(const Array<T> &inarray, const LogicalArray &inmask,
00360                 Bool isreadonly);
00361     MaskedArray(const Array<T> &inarray, const LogicalArray &inmask);
00362     // </group>
00363 
00364     // Create a MaskedArray from a MaskedArray and a LogicalArray.
00365     //
00366     // The internal mask is the AND of the input mask and the mask of
00367     // the input MaskedArray.
00368     //
00369     // The Array from the input MaskedArray is copy constructed, which
00370     // means that it is a really smart pointer to the underlying Block, and
00371     // shares this Block with the Array from the input MaskedArray.
00372     //
00373     // By default, the MaskedArray constructed is writeable if the input
00374     // MaskedArray is writeable, and readonly if the input MaskedArray
00375     // is readonly.  If <src>isreadonly</src> is <src>True</src>, then
00376     // the MaskedArray returned is readonly.  If <src>isreadonly</src> is
00377     // <src>False</src> and the input MaskedArray is readonly, then the
00378     // constructed MaskedArray is readonly.
00379     //
00380     // <thrown>
00381     //    <li> ArrayConformanceError
00382     // </thrown>
00383     //
00384     // <group>
00385     MaskedArray(const MaskedArray<T> &inarray, const LogicalArray &inmask,
00386                 Bool isreadonly);
00387     MaskedArray(const MaskedArray<T> &inarray, const LogicalArray &inmask);
00388     // </group>
00389 
00390     // Create a MaskedArray from an Array and a MaskedLogicalArray.
00391     //
00392     // The internal mask is the AND of the internal LogicalArray and the
00393     // internal mask of the MaskedLogicalArray.
00394     //
00395     // The Array is copy constructed, which means that it is a really smart
00396     // pointer to the underlying Block, and shares this Block with the input
00397     // Array.
00398     //
00399     // By default, the MaskedArray constructed is writeable.  If
00400     // <src>isreadonly</src> is <src>True</src>, then the MaskedArray
00401     // returned is readonly.
00402     //
00403     // <thrown>
00404     //    <li> ArrayConformanceError
00405     // </thrown>
00406     //
00407     // <group>
00408     MaskedArray(const Array<T> &inarray, const MaskedLogicalArray &inmask,
00409                 Bool isreadonly);
00410     MaskedArray(const Array<T> &inarray, const MaskedLogicalArray &inmask);
00411     // </group>
00412 
00413     // Create a MaskedArray from a MaskedArray and a MaskedLogicalArray.
00414     //
00415     // The internal mask is the AND of the internal LogicalArray and the
00416     // internal mask of the MaskedLogicalArray, ANDed with the mask of
00417     // the input MaskedArray.
00418     //
00419     // The Array from the input MaskedArray is copy constructed, which
00420     // means that it is a really smart pointer to the underlying Block, and
00421     // shares this Block with the Array from the input MaskedArray.
00422     //
00423     // By default, the MaskedArray constructed is writeable if the input
00424     // MaskedArray is writeable, and readonly if the input MaskedArray
00425     // is readonly.  If <src>isreadonly</src> is <src>True</src>, then
00426     // the MaskedArray returned is readonly.  If <src>isreadonly</src> is
00427     // <src>False</src> and the input MaskedArray is readonly, then the
00428     // constructed MaskedArray is readonly.
00429     //
00430     // <thrown>
00431     //    <li> ArrayConformanceError
00432     // </thrown>
00433     //
00434     // <group>
00435     MaskedArray(const MaskedArray<T> &inarray,
00436                 const MaskedLogicalArray &inmask,
00437                 Bool isreadonly);
00438     MaskedArray(const MaskedArray<T> &inarray,
00439                 const MaskedLogicalArray &inmask);
00440     // </group>
00441 
00442     // Copy constructor.
00443     //
00444     // The internal mask is a total copy of the mask from the input
00445     // MaskedArray, and is completely independent of this input mask.
00446     //
00447     // The Array from the input MaskedArray is copy constructed, which
00448     // means that it is a really smart pointer to the underlying Block, and
00449     // shares this Block with the Array from the input MaskedArray.
00450     //
00451     // By default, the MaskedArray constructed is writeable if the input
00452     // MaskedArray is writeable, and readonly if the input MaskedArray
00453     // is readonly.  If <src>isreadonly</src> is <src>True</src>, then
00454     // the MaskedArray returned is readonly.  If <src>isreadonly</src> is
00455     // <src>False</src> and the input MaskedArray is readonly, then the
00456     // constructed MaskedArray is readonly.
00457     //
00458     // <group>
00459     MaskedArray(const MaskedArray<T> &other, Bool isreadonly);
00460     MaskedArray(const MaskedArray<T> &other);
00461     // </group>
00462 
00463     ~MaskedArray();
00464 
00465     // Return a MaskedArray.  The new MaskedArray is masked by the input
00466     // LogicalArray "anded" with the mask of the original MaskedArray.
00467     // This mask must conform to the array.
00468     //
00469     // The MaskedArray constructed is writeable if the input
00470     // MaskedArray is writeable, and readonly if the input MaskedArray
00471     // is readonly.
00472     //
00473     MaskedArray<T> operator() (const LogicalArray &mask) const;
00474 
00475     // Return a MaskedArray.  The new MaskedArray is masked by the input
00476     // MaskedLogicalArray "anded" with the mask of the original MaskedArray.
00477     // This mask must conform to the array.
00478     //
00479     // The MaskedArray constructed is writeable if the input
00480     // MaskedArray is writeable, and readonly if the input MaskedArray
00481     // is readonly.
00482     //
00483     MaskedArray<T> operator() (const MaskedLogicalArray &mask) const;
00484 
00485     // Get a reference to an array part which extends from "start" to end."
00486     // <group>
00487     MaskedArray<T> operator()(const IPosition &start, const IPosition &end);
00488     // Along the ith axis, every inc[i]'th element is chosen.
00489     MaskedArray<T> operator()(const IPosition &start, const IPosition &end,
00490                               const IPosition &inc);
00491     // </group>
00492 
00493     // Get a reference to an array using a Slicer.
00494     MaskedArray<T> operator()(const Slicer&);
00495   
00496     // Make a copy of the masked array.
00497     //
00498     // This is a deep copy.  The Array and mask components of the returned
00499     // MaskedArray are deep copies of the Array and mask in the input
00500     // MaskedArray pointed to by this.  In other words, the Array and mask
00501     // in the output MaskedArray are completely independent of those in
00502     // the input MaskedArray.
00503     //
00504     // By default, the MaskedArray returned is writeable.  If
00505     // <src>isreadonly</src> is <src>True</src>, then the MaskedArray
00506     // returned is readonly.
00507     //
00508     // <group>
00509     MaskedArray<T> copy(Bool isreadonly) const;
00510     MaskedArray<T> copy() const;
00511     // </group>
00512 
00513     // Return the internal Array.
00514     const Array<T> & getArray() const;
00515 
00516     // Return the internal Array, writeable.
00517     //
00518     // <thrown>
00519     //    <li> ArrayError
00520     // </thrown>
00521     //
00522     Array<T> & getRWArray() const;
00523 
00524     // Return the (const) internal Mask.
00525     const LogicalArray & getMask() const;
00526 
00527     // The dimensionality of this masked array.
00528     uInt ndim() const;
00529 
00530     // The number of elements of this masked array.
00531     // This is the number of elements in the underlying Array.
00532     // <group>
00533     uInt nelements() const;
00534     uInt size() const
00535         { return nelements(); }
00536     // </group>
00537 
00538     // The number of valid elements of this masked array.
00539     // This is the number of elements of the mask which are TRUE.
00540     uInt nelementsValid() const;
00541 
00542 
00543     // Check to see if the masked array is consistent. This is about the same
00544     // thing as checking for invariants. If AIPS_DEBUG is defined, this is
00545     // invoked after construction and on entry to most member functions.
00546     Bool ok() const;
00547 
00548     // Are the shapes identical?
00549     // <group>
00550     Bool conform(const Array<T> &other) const;
00551     Bool conform(const MaskedArray<T> &other) const;
00552     // </group>
00553 
00554     // The length of each axis.
00555     const IPosition& shape() const
00556       { return pArray->shape(); }
00557 
00558     // Is the array read only?
00559     Bool isReadOnly() const
00560       { return isRO; }
00561 
00562     // Set the array to be read only.
00563     void setReadOnly() const;
00564 
00565 
00566     // Copy the values in inarray to this, only copying those elements
00567     // for which the corresponding mask element is True.
00568     //
00569     // <thrown>
00570     //    <li> ArrayConformanceError
00571     //    <li> ArrayError
00572     // </thrown>
00573     //
00574     MaskedArray<T> &operator=(const Array<T> &inarray);
00575 
00576     // Copy the values in other to this, only copying those elements
00577     // for which the logical AND of the corresponding mask elements
00578     // of both MaskedArrays is True.
00579     //
00580     // <thrown>
00581     //    <li> ArrayConformanceError
00582     //    <li> ArrayError
00583     // </thrown>
00584     //
00585     // <group>
00586     MaskedArray<T> &operator=(const MaskedArray<T> &other);
00587     // </group>
00588 
00589     // Set every element of this array to "value", only setting those elements
00590     // for which the corresponding mask element is True.
00591     // In other words, a scalar behaves as if it were a constant conformant
00592     // array.
00593     //
00594     // <thrown>
00595     //    <li> ArrayError
00596     // </thrown>
00597     //
00598     MaskedArray<T> &operator=(const T &value);
00599 
00600     // Return a "compressed" Array containing only the valid
00601     // elements of the MaskedArray.  The number of elements in the
00602     // Array will be <src>nelementsValid()</src> for the
00603     // MaskedArray.  The MaskedArray can have any shape.
00604     // <group>
00605 
00606     // The returned Array will have dimension one.
00607     Array<T> getCompressedArray () const;
00608 
00609     // The returned Array will have the input shape.  This shape must
00610     // give the returned Array the required number of elements.
00611     //
00612     // <thrown>
00613     //    <li> ArrayError
00614     // </thrown>
00615     //
00616     Array<T> getCompressedArray (const IPosition & shape) const;
00617 
00618     // </group>
00619 
00620     // Fill the argument "compressed" Array with only the
00621     // valid elements of the MaskedArray.  The size of the
00622     // Array must be <src>nelementsValid()</src> for the MaskedArray.
00623     // The Array can have any shape which meets this requirement.
00624     // The MaskedArray can have any shape.
00625     //
00626     // <thrown>
00627     //    <li> ArrayError
00628     // </thrown>
00629     //
00630     void getCompressedArray (Array<T> & inarr) const;
00631 
00632     // Set only the valid elements of the MaskedArray from the argument
00633     // "compressed" Array.  The size of the
00634     // Array must be <src>nelementsValid()</src> for the MaskedArray.
00635     // The Array can have any shape which meets this requirement.
00636     // The MaskedArray can have any shape.
00637     //
00638     // <thrown>
00639     //    <li> ArrayError
00640     // </thrown>
00641     //
00642     void setCompressedArray (const Array<T> & inarr);
00643 
00644     // Manipulate the storage for the underlying Array.
00645     // See the description of the corresponding Array functions
00646     // for more information.
00647     // <group>
00648     const T * getArrayStorage (Bool &deleteIt) const;
00649     //
00650     // <thrown>
00651     //    <li> ArrayError
00652     // </thrown>
00653     //
00654     T * getRWArrayStorage (Bool &deleteIt) const;
00655     //
00656     void freeArrayStorage(const T *&storage, Bool deleteIt) const;
00657     //
00658     // <thrown>
00659     //    <li> ArrayError
00660     // </thrown>
00661     //
00662     void putArrayStorage(T *&storage, Bool deleteAndCopy) const;
00663     // </group>
00664 
00665 
00666     // Manipulate the storage for the underlying Mask.
00667     // See the description of the corresponding Array functions
00668     // for more information.
00669     // <group>
00670     const LogicalArrayElem *getMaskStorage (Bool &deleteIt) const;
00671     //
00672     void freeMaskStorage(const LogicalArrayElem *&storage, Bool deleteIt) const;
00673     // </group>
00674 
00675 
00676 protected:
00677     // The array.
00678     Array<T> *pArray;
00679 
00680     // The mask.
00681     LogicalArray *pMask;
00682 
00683     // Cache the number of valid elements.
00684     uInt nelemValid;
00685 
00686     // Is the number of valid elements cache OK?
00687     // i.e. has it been calculated?
00688     Bool nelemValidIsOK;
00689 
00690     // Is the array read only?
00691     Bool isRO;
00692 
00693 };
00694 
00695 
00696 // <summary> General global functions for MaskedArrays, and MaskedArrays and Arrays. </summary>
00697 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMaskedArray">
00698 //
00699 // <prerequisite>
00700 //   <li> <linkto class=Array>Array</linkto>
00701 //   <li> <linkto group="LogiArray.h#LogicalArray">LogicalArray</linkto>
00702 //   <li> <linkto class=MaskedArray>MaskedArray</linkto>
00703 // </prerequisite>
00704 //
00705 // <synopsis>
00706 // These are generally useful global functions which operate on all
00707 // MaskedArrays, or on MaskedArrays and Arrays.
00708 // </synopsis>
00709 //
00710 // <linkfrom anchor="MaskedArray general global functions" classes="MaskedArray Array Vector Matrix Cube">
00711 //   <here>MaskedArray general global functions</here> -- General global
00712 //   functions for MaskedArrays, and between MaskedArrays and Arrays.
00713 // </linkfrom>
00714 //
00715 // <group name="MaskedArray general global functions">
00716 
00717 
00718 // Test conformance for masked arrays and arrays of different types.
00719 // Are the shapes identical?
00720 //
00721 //   <group name=conform2>
00722 //
00723 template<class T, class U>
00724   Bool conform2 (const MaskedArray<T> &left, const Array<U> &right);
00725 template<class T, class U>
00726   Bool conform2 (const Array<T> &left, const MaskedArray<U> &right);
00727 template<class T, class U>
00728   Bool conform2 (const MaskedArray<T> &left, const MaskedArray<U> &right);
00729 //
00730 //   </group>
00731 
00732 // </group>
00733 
00734 
00735 } //# NAMESPACE CASA - END
00736 
00737 #ifndef CASACORE_NO_AUTO_TEMPLATES
00738 #include <casa/Arrays/MaskedArray.tcc>
00739 #endif //# CASACORE_NO_AUTO_TEMPLATES
00740 #endif