ArrayLogical.h

Go to the documentation of this file.
00001 //# ArrayLogical.h: Element by element logical operations on arrays.
00002 //# Copyright (C) 1993,1994,1995,1999,2001
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$
00027 
00028 #ifndef CASA_ARRAYLOGICAL_H
00029 #define CASA_ARRAYLOGICAL_H
00030 
00031 //# Includes
00032 #include <casacore/casa/aips.h>
00033 #include <casacore/casa/Arrays/Array.h>
00034 #include <casacore/casa/Arrays/LogiArray.h>
00035 #include <casacore/casa/Arrays/ArrayMathBase.h>
00036 
00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00038 
00039 //# Forward Declarations
00040 template <class T> class Vector;
00041 template <class T> class Matrix;
00042 template <class T> class Cube;
00043 
00044 // <summary>
00045 //    Logical operations for Arrays.
00046 // </summary>
00047 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayLogical">
00048 //
00049 // <prerequisite>
00050 //   <li> <linkto class=Array>Array</linkto>
00051 // </prerequisite>
00052 //
00053 // <etymology>
00054 // This file contains global functions which perform element by element logical
00055 // operations on arrays.
00056 // </etymology>
00057 //
00058 // <synopsis>
00059 // These functions perform element by element logical operations on
00060 // arrays.  The two arrays must conform, except for allEQ which returns
00061 // False if the arrays do not conform.
00062 //
00063 // There are two classes of functions.  One class returns a LogicalArray.
00064 // In these functions, the value of an element of the LogicalArray is
00065 // the value of the logical operation applied to the corresponding elements
00066 // of the input Arrays.  The other class of functions returns a single
00067 // Bool.  The return value is True if the logical operation returns True for
00068 // all elements of the input arrays for the "all" functions
00069 // (e.g. allLE()), and returns True if the logical operation returns True for
00070 // any elements of the input arrays for the "any" functions
00071 // (e.g. anyLE()).
00072 //
00073 // For instance allLE (a, b) implies that every element of a is
00074 // less than or equal to every element of b. Note that with this definition
00075 // allLE (a, b) and allGE (a, b) can both be false (e.g. a = [1,0] b = [0,1]).
00076 //
00077 // <note role=caution> Comparison between two zero-sized arrays is not defined
00078 // (should it throw an exception?).
00079 // </note>
00080 //
00081 // </synopsis>
00082 //
00083 // <example>
00084 // <srcblock>
00085 //   Vector<Int> a(10);
00086 //   Vector<Int> b(10);
00087 //   LogicalVector l(10);
00088 //      . . .
00089 //   l = a < b;
00090 // </srcblock>
00091 // This example sets the elements of l (a<b).
00092 // The result of the comparison is a LogicalArray.
00093 // </example>
00094 //
00095 // <example>
00096 // <srcblock>
00097 //   Vector<Int> a(10);
00098 //   Vector<Int> b(10);
00099 //   Bool result;
00100 //      . . .
00101 //   result = allLT (a, b);
00102 // </srcblock>
00103 // This example sets result to True if, for all elements, a<b.
00104 // </example>
00105 //
00106 // <motivation>
00107 // One wants to be able to perform logical operations on arrays.
00108 // </motivation>
00109 //
00110 // <todo asof="$DATE:$>
00111 //   <li> Reconsider where the origin of the returned LogicalArray should
00112 //          be located.
00113 // </todo>
00114 //
00115 // <linkfrom anchor="Array logical operations" classes="Array Vector Matrix Cube">
00116 //    <here>Array logical operations</here> -- Logical operations for Arrays.
00117 // </linkfrom>
00118 //
00119 // <group name="Array logical operations">
00120 
00121 
00122 // Determine if the comparisons between corresponding array elements yield True.
00123 // <group>
00124 template<typename T, typename CompareOperator>
00125 bool arrayCompareAll (const Array<T>& left, const Array<T>& right,
00126                       CompareOperator op);
00127 template<typename T, typename CompareOperator>
00128 bool arrayCompareAll (const Array<T>& left, T right,
00129                       CompareOperator op);
00130 template<typename T, typename CompareOperator>
00131 bool arrayCompareAll (T left, const Array<T>& right,
00132                       CompareOperator op);
00133 // </group>
00134 
00135 // Determine if the comparisons between corresponding array elements yield True.
00136 // <group>
00137 template<typename T, typename CompareOperator>
00138 bool arrayCompareAny (const Array<T>& left, const Array<T>& right,
00139                       CompareOperator op);
00140 template<typename T, typename CompareOperator>
00141 bool arrayCompareAny (const Array<T>& left, T right,
00142                       CompareOperator op);
00143 template<typename T, typename CompareOperator>
00144 bool arrayCompareAny (T left, const Array<T>& right,
00145                       CompareOperator op);
00146 // </group>
00147 
00148 // 
00149 // Element by element comparisons between the "l" and "r" arrays. The result
00150 // is true only if the comparison is true for every element of the arrays.
00151 //
00152 // The operator forms of array logical operations which return a single Bool
00153 // have been replaced by these "all" functions.
00154 // The operator forms of array logical operations now return a LogicalArray.
00155 //
00156 // The arrays must conform except for allEQ, which will return False if the
00157 // arrays have different shapes.
00158 //
00159 // <thrown>
00160 //    <li> ArrayConformanceError
00161 // </thrown>
00162 //
00163 // <group>
00164 template<class T> Bool allLE (const Array<T> &l, const Array<T> &r);
00165 template<class T> Bool allLT (const Array<T> &l, const Array<T> &r);
00166 template<class T> Bool allGE (const Array<T> &l, const Array<T> &r);
00167 template<class T> Bool allGT (const Array<T> &l, const Array<T> &r);
00168 template<class T> Bool allEQ (const Array<T> &l, const Array<T> &r);
00169 template<class T> Bool allNE (const Array<T> &l, const Array<T> &r);
00170 template<class T> Bool allNear (const Array<T> &l, const Array<T> &r,
00171                                 Double tol);
00172 template<class T> Bool allNearAbs (const Array<T> &l, const Array<T> &r,
00173                                    Double tol);
00174 //
00175 // This only makes sense if the array element type is logical valued.
00176 // <group>
00177 template<class T> Bool allAND (const Array<T> &l, const Array<T> &r);
00178 template<class T> Bool allOR (const Array<T> &l, const Array<T> &r);
00179 // </group>
00180 //
00181 // </group>
00182 
00183 
00184 // 
00185 // Element by element comparisons between the "l" and "r" arrays. The result
00186 // is a LogicalArray.
00187 // The arrays must conform or an exception is thrown.
00188 //
00189 // The Vector, Matrix and Cube version are present to bypass the problems
00190 // due to the existence of automatic comparison inline templates in standard
00191 // algorithm library, producing a single Bool value.
00192 //
00193 // <group>
00194 template<class T> LogicalArray operator <= (const Array<T> &l,
00195                                             const Array<T> &r);
00196 template<class T> LogicalArray operator <  (const Array<T> &l,
00197                                             const Array<T> &r);
00198 template<class T> LogicalArray operator >= (const Array<T> &l,
00199                                             const Array<T> &r);
00200 template<class T> LogicalArray operator >  (const Array<T> &l,
00201                                             const Array<T> &r);
00202 template<class T> LogicalArray operator == (const Array<T> &l,
00203                                             const Array<T> &r);
00204 template<class T> LogicalArray operator != (const Array<T> &l,
00205                                             const Array<T> &r);
00206 
00207 template<class T> LogicalArray near(const Array<T> &l, const Array<T> &r,
00208                                     Double tol);
00209 template<class T> LogicalArray nearAbs(const Array<T> &l, const Array<T> &r,
00210                                        Double tol);
00211 //
00212 // This only makes sense if the array element type is logical valued.
00213 // <group>
00214 template<class T> LogicalArray operator && (const Array<T> &l, const Array<T> &r);
00215 template<class T> LogicalArray operator || (const Array<T> &l, const Array<T> &r);
00216 // </group>
00217 //
00218 // </group>
00219 
00220 
00221 // 
00222 // Logical negation of an array.  This only makes sense if the array
00223 // element type is logical valued.
00224 template<class T> LogicalArray operator ! (const Array<T> &l);
00225 
00226 
00227 // 
00228 // Element by element comparisons between an array and a scalar, which
00229 // behaves as if it were a conformant array filled with the value "val."
00230 // The result is true only if the comparison is true for every element
00231 // of the array.
00232 // <group>
00233 template<class T> Bool allLE (const Array<T> &array, const T &val);
00234 template<class T> Bool allLE (const T &val, const Array<T> &array);
00235 template<class T> Bool allLT (const Array<T> &array, const T &val);
00236 template<class T> Bool allLT (const T &val, const Array<T> &array);
00237 template<class T> Bool allGE (const Array<T> &array, const T &val);
00238 template<class T> Bool allGE (const T &val, const Array<T> &array);
00239 template<class T> Bool allGT (const Array<T> &array, const T &val);
00240 template<class T> Bool allGT (const T &val, const Array<T> &array);
00241 template<class T> Bool allEQ (const Array<T> &array, const T &val);
00242 template<class T> Bool allEQ (const T &val, const Array<T> &array);
00243 template<class T> Bool allNE (const Array<T> &array, const T &val);
00244 template<class T> Bool allNE (const T &val, const Array<T> &array);
00245 template<class T> Bool allNear (const Array<T> &array, const T &val, Double tol);
00246 template<class T> Bool allNear (const T &val, const Array<T> &array, Double tol);
00247 template<class T> Bool allNearAbs (const Array<T> &array, const T &val,
00248                                    Double tol);
00249 template<class T> Bool allNearAbs (const T &val, const Array<T> &array,
00250                                    Double tol);
00251 //
00252 // This only makes sense if the array element type is logical valued.
00253 // <group>
00254 template<class T> Bool allAND (const Array<T> &array, const T &val);
00255 template<class T> Bool allAND (const T &val, const Array<T> &array);
00256 template<class T> Bool allOR (const Array<T> &array, const T &val);
00257 template<class T> Bool allOR (const T &val, const Array<T> &array);
00258 // </group>
00259 //
00260 // </group>
00261 
00262 
00263 // Test if all elements in an array are the same.
00264 template<class T> Bool allSame (const Array<T> &a)
00265   { return a.size() <= 1  ||  allEQ(*a.data(), a); }
00266 
00267 
00268 // Element by element test for NaN or (In)finity.
00269 // <group>
00270 template<class T> LogicalArray isNaN    (const Array<T> &array);
00271 template<class T> LogicalArray isInf    (const Array<T> &array);
00272 template<class T> LogicalArray isFinite (const Array<T> &array);
00273 // </group>
00274 
00275 // 
00276 // Element by element comparisons between an array and a scalar, which
00277 // behaves as if it were a conformant array filled with the value "val."
00278 // The result is a LogicalArray.
00279 //
00280 // <thrown>
00281 //    <li> ArrayConformanceError
00282 // </thrown>
00283 //
00284 // <group>
00285 template<class T> LogicalArray operator <= (const Array<T> &array, const T &val);
00286 template<class T> LogicalArray operator <= (const T &val, const Array<T> &array);
00287 template<class T> LogicalArray operator <  (const Array<T> &array, const T &val);
00288 template<class T> LogicalArray operator <  (const T &val, const Array<T> &array);
00289 template<class T> LogicalArray operator >= (const Array<T> &array, const T &val);
00290 template<class T> LogicalArray operator >= (const T &val, const Array<T> &array);
00291 template<class T> LogicalArray operator >  (const Array<T> &array, const T &val);
00292 template<class T> LogicalArray operator >  (const T &val, const Array<T> &array);
00293 template<class T> LogicalArray operator == (const Array<T> &array, const T &val);
00294 template<class T> LogicalArray operator == (const T &val, const Array<T> &array);
00295 template<class T> LogicalArray operator != (const Array<T> &array, const T &val);
00296 template<class T> LogicalArray operator != (const T &val, const Array<T> &array);
00297 template<class T> LogicalArray near (const Array<T> &array, const T &val,
00298                                      Double tol);
00299 template<class T> LogicalArray near (const T &val, const Array<T> &array,
00300                                       Double tol);
00301 template<class T> LogicalArray nearAbs (const Array<T> &array, const T &val,
00302                                      Double tol);
00303 template<class T> LogicalArray nearAbs (const T &val, const Array<T> &array,
00304                                       Double tol);
00305 //
00306 // This only makes sense if the array element type is logical valued.
00307 // <group>
00308 template<class T> LogicalArray operator && (const Array<T> &array, const T &val);
00309 template<class T> LogicalArray operator && (const T &val, const Array<T> &array);
00310 template<class T> LogicalArray operator || (const Array<T> &array, const T &val);
00311 template<class T> LogicalArray operator || (const T &val, const Array<T> &array);
00312 // </group>
00313 //
00314 // </group>
00315 
00316 
00317 //# With two arrays, they must both conform, and the result is done element
00318 //# by element. For instance anyLE (a, b) implies that some element of a is
00319 //# less than or equal to the corresponding element of b.
00320 //# NB comparison between two zero-sized arrays is not defined (should it
00321 //# throw an exception?).
00322 
00323 // 
00324 // Element by element comparisons between the "l" and "r" arrays. The result
00325 // is true if the comparison is true for some element of the arrays.
00326 //
00327 // <thrown>
00328 //    <li> ArrayConformanceError
00329 // </thrown>
00330 //
00331 // <group>
00332 
00333 template<class T> Bool anyLE (const Array<T> &l, const Array<T> &r);
00334 template<class T> Bool anyLT (const Array<T> &l, const Array<T> &r);
00335 template<class T> Bool anyGE (const Array<T> &l, const Array<T> &r);
00336 template<class T> Bool anyGT (const Array<T> &l, const Array<T> &r);
00337 template<class T> Bool anyEQ (const Array<T> &l, const Array<T> &r);
00338 template<class T> Bool anyNE (const Array<T> &l, const Array<T> &r);
00339 template<class T> Bool anyNear (const Array<T> &l, const Array<T> &r, 
00340                                 Double tol);
00341 template<class T> Bool anyNearAbs (const Array<T> &l, const Array<T> &r,
00342                                    Double tol);
00343 //
00344 // This only makes sense if the array element type is logical valued.
00345 // <group>
00346 template<class T> Bool anyAND (const Array<T> &l, const Array<T> &r);
00347 template<class T> Bool anyOR (const Array<T> &l, const Array<T> &r);
00348 // </group>
00349 //
00350 // </group>
00351 
00352 // 
00353 // Element by element comparisons between an array and a scalar, which
00354 // behaves as if it were a conformant array filled with the value "val."
00355 // The result is true if the comparison is true for some element of the array.
00356 // At some point operators will be available that return masks where the
00357 // comparison is true.
00358 // <group>
00359 
00360 template<class T> Bool anyLE (const Array<T> &array, const T &val);
00361 template<class T> Bool anyLE (const T &val, const Array<T> &array);
00362 template<class T> Bool anyLT (const Array<T> &array, const T &val);
00363 template<class T> Bool anyLT (const T &val, const Array<T> &array);
00364 template<class T> Bool anyGE (const Array<T> &array, const T &val);
00365 template<class T> Bool anyGE (const T &val, const Array<T> &array);
00366 template<class T> Bool anyGT (const Array<T> &array, const T &val);
00367 template<class T> Bool anyGT (const T &val, const Array<T> &array);
00368 template<class T> Bool anyEQ (const Array<T> &array, const T &val);
00369 template<class T> Bool anyEQ (const T &val, const Array<T> &array);
00370 template<class T> Bool anyNE (const Array<T> &array, const T &val);
00371 template<class T> Bool anyNE (const T &val, const Array<T> &array);
00372 template<class T> Bool anyNear (const Array<T> &array, const T &val, Double tol);
00373 template<class T> Bool anyNear (const T &val, const Array<T> &array, Double tol);
00374 template<class T> Bool anyNearAbs (const Array<T> &array, const T &val,
00375                                    Double tol);
00376 template<class T> Bool anyNearAbs (const T &val, const Array<T> &array,
00377                                    Double tol);
00378 //
00379 // This only makes sense if the array element type is logical valued.
00380 // <group>
00381 template<class T> Bool anyAND (const Array<T> &array, const T &val);
00382 template<class T> Bool anyAND (const T &val, const Array<T> &array);
00383 template<class T> Bool anyOR (const Array<T> &array, const T &val);
00384 template<class T> Bool anyOR (const T &val, const Array<T> &array);
00385 // </group>
00386 //
00387 // </group>
00388 
00389 
00390 // Are all elements true?
00391 inline Bool allTrue (const Array<Bool>& array)
00392   { return allEQ (array, True); }
00393 
00394 // Is any element true?
00395 inline Bool anyTrue (const Array<Bool>& array)
00396   { return anyEQ (array, True); }
00397 
00398 // The same functions as above, but for selected axes.
00399 Array<Bool> partialAllTrue (const Array<Bool>& array,
00400                             const IPosition& collapseAxes);
00401 Array<Bool> partialAnyTrue (const Array<Bool>& array,
00402                             const IPosition& collapseAxes);
00403 
00404 // Determine the number of true or false elements.
00405 // Note: it is meant for Bool arrays, but can also be used for
00406 // e.g. Int arrays.
00407 // <group>
00408 
00409 // Determine it for the full array.
00410 // <group>
00411 template<class T> size_t nfalse (const Array<T> &array);
00412 template<class T> size_t ntrue (const Array<T> &array)
00413   { return array.nelements() - nfalse(array); }
00414 // </group>
00415 
00416 // The same functions as above, but determine ntrue and nfalse for the
00417 // given axes only. The result is an array with a shape formed by the
00418 // remaining axes.
00419 // For example, for an array with shape [3,4,5], collapsing axis 0
00420 // results in an array with shape [4,5] containing ntrue or nfalse for
00421 // each X line.
00422 // Summing for axes 0 and 2 results in an array with shape [4] containing
00423 // ntrue or nfalse for each XZ plane.
00424 // <group>
00425 template<class T> Array<uInt> partialNTrue (const Array<T>& array,
00426                                             const IPosition& collapseAxes);
00427 template<class T> Array<uInt> partialNFalse (const Array<T>& array,
00428                                              const IPosition& collapseAxes);
00429 // </group>
00430 
00431 // </group>
00432 
00433 // </group>
00434 
00435 // Define logical Functors.
00436 // <group>
00437 template<typename T> class AllFunc : public ArrayFunctorBase<T,Bool> {
00438 public:
00439   virtual ~AllFunc() {}
00440   virtual Bool operator() (const Array<T>& arr) const { return allTrue(arr); }
00441 };
00442 template<typename T> class AnyFunc : public ArrayFunctorBase<T,Bool> {
00443 public:
00444   virtual ~AnyFunc() {}
00445   virtual Bool operator() (const Array<T>& arr) const { return anyTrue(arr); }
00446 };
00447 
00448 template<typename T> class NTrueFunc : public ArrayFunctorBase<T,uInt> {
00449 public:
00450   virtual uInt operator() (const Array<T>& arr) const { return ntrue(arr); }
00451 };
00452 template<typename T> class NFalseFunc : public ArrayFunctorBase<T,uInt> {
00453 public:
00454   virtual uInt operator() (const Array<T>& arr) const { return nfalse(arr); }
00455 };
00456 // </group>
00457 
00458 
00459 } //# NAMESPACE CASACORE - END
00460 
00461 #ifndef CASACORE_NO_AUTO_TEMPLATES
00462 #include <casacore/casa/Arrays/ArrayLogical.tcc>
00463 #endif //# CASACORE_NO_AUTO_TEMPLATES
00464 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1