casacore
ArrayLogical.h
Go to the documentation of this file.
1 //# ArrayLogical.h: Element by element logical operations on arrays.
2 //# Copyright (C) 1993,1994,1995,1999,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_ARRAYLOGICAL_H
29 #define CASA_ARRAYLOGICAL_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/Array.h>
34 #include <casacore/casa/Arrays/LogiArray.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 template <class T> class Vector;
40 template <class T> class Matrix;
41 template <class T> class Cube;
42 
43 // <summary>
44 // Logical operations for Arrays.
45 // </summary>
46 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayLogical">
47 //
48 // <prerequisite>
49 // <li> <linkto class=Array>Array</linkto>
50 // </prerequisite>
51 //
52 // <etymology>
53 // This file contains global functions which perform element by element logical
54 // operations on arrays.
55 // </etymology>
56 //
57 // <synopsis>
58 // These functions perform element by element logical operations on
59 // arrays. The two arrays must conform, except for allEQ which returns
60 // False if the arrays do not conform.
61 //
62 // There are two classes of functions. One class returns a LogicalArray.
63 // In these functions, the value of an element of the LogicalArray is
64 // the value of the logical operation applied to the corresponding elements
65 // of the input Arrays. The other class of functions returns a single
66 // Bool. The return value is True if the logical operation returns True for
67 // all elements of the input arrays for the "all" functions
68 // (e.g. allLE()), and returns True if the logical operation returns True for
69 // any elements of the input arrays for the "any" functions
70 // (e.g. anyLE()).
71 //
72 // For instance allLE (a, b) implies that every element of a is
73 // less than or equal to every element of b. Note that with this definition
74 // allLE (a, b) and allGE (a, b) can both be false (e.g. a = [1,0] b = [0,1]).
75 //
76 // <note role=caution> Comparison between two zero-sized arrays is not defined
77 // (should it throw an exception?).
78 // </note>
79 //
80 // </synopsis>
81 //
82 // <example>
83 // <srcblock>
84 // Vector<Int> a(10);
85 // Vector<Int> b(10);
86 // LogicalVector l(10);
87 // . . .
88 // l = a < b;
89 // </srcblock>
90 // This example sets the elements of l (a<b).
91 // The result of the comparison is a LogicalArray.
92 // </example>
93 //
94 // <example>
95 // <srcblock>
96 // Vector<Int> a(10);
97 // Vector<Int> b(10);
98 // Bool result;
99 // . . .
100 // result = allLT (a, b);
101 // </srcblock>
102 // This example sets result to True if, for all elements, a<b.
103 // </example>
104 //
105 // <motivation>
106 // One wants to be able to perform logical operations on arrays.
107 // </motivation>
108 //
109 // <todo asof="$DATE:$>
110 // <li> Reconsider where the origin of the returned LogicalArray should
111 // be located.
112 // </todo>
113 //
114 // <linkfrom anchor="Array logical operations" classes="Array Vector Matrix Cube">
115 // <here>Array logical operations</here> -- Logical operations for Arrays.
116 // </linkfrom>
117 //
118 // <group name="Array logical operations">
120 
121 // Determine if the comparisons between corresponding array elements yield True.
122 // <group>
123 template<typename T, typename CompareOperator>
124 bool arrayCompareAll (const Array<T>& left, const Array<T>& right,
125  CompareOperator op);
126 template<typename T, typename CompareOperator>
127 bool arrayCompareAll (const Array<T>& left, T right,
128  CompareOperator op);
129 template<typename T, typename CompareOperator>
130 bool arrayCompareAll (T left, const Array<T>& right,
131  CompareOperator op);
132 // </group>
133 
134 // Determine if the comparisons between corresponding array elements yield True.
135 // <group>
136 template<typename T, typename CompareOperator>
137 bool arrayCompareAny (const Array<T>& left, const Array<T>& right,
138  CompareOperator op);
139 template<typename T, typename CompareOperator>
140 bool arrayCompareAny (const Array<T>& left, T right,
141  CompareOperator op);
142 template<typename T, typename CompareOperator>
143 bool arrayCompareAny (T left, const Array<T>& right,
144  CompareOperator op);
145 // </group>
146 
147 //
148 // Element by element comparisons between the "l" and "r" arrays. The result
149 // is true only if the comparison is true for every element of the arrays.
150 //
151 // The operator forms of array logical operations which return a single Bool
152 // have been replaced by these "all" functions.
153 // The operator forms of array logical operations now return a LogicalArray.
154 //
155 // The arrays must conform except for allEQ, which will return False if the
156 // arrays have different shapes.
157 //
158 // <thrown>
159 // <li> ArrayConformanceError
160 // </thrown>
161 //
162 // <group>
163 template<class T> Bool allLE (const Array<T> &l, const Array<T> &r);
164 template<class T> Bool allLT (const Array<T> &l, const Array<T> &r);
165 template<class T> Bool allGE (const Array<T> &l, const Array<T> &r);
166 template<class T> Bool allGT (const Array<T> &l, const Array<T> &r);
167 template<class T> Bool allEQ (const Array<T> &l, const Array<T> &r);
168 template<class T> Bool allNE (const Array<T> &l, const Array<T> &r);
169 template<class T> Bool allNear (const Array<T> &l, const Array<T> &r,
170  Double tol);
171 template<class T> Bool allNearAbs (const Array<T> &l, const Array<T> &r,
172  Double tol);
173 //
174 // This only makes sense if the array element type is logical valued.
175 // <group>
176 template<class T> Bool allAND (const Array<T> &l, const Array<T> &r);
177 template<class T> Bool allOR (const Array<T> &l, const Array<T> &r);
178 // </group>
179 //
180 // </group>
181 
182 
183 //
184 // Element by element comparisons between the "l" and "r" arrays. The result
185 // is a LogicalArray.
186 // The arrays must conform or an exception is thrown.
187 //
188 // The Vector, Matrix and Cube version are present to bypass the problems
189 // due to the existence of automatic comparison inline templates in standard
190 // algorithm library, producing a single Bool value.
191 //
192 // <group>
193 template<class T> LogicalArray operator <= (const Array<T> &l,
194  const Array<T> &r);
195 template<class T> LogicalArray operator < (const Array<T> &l,
196  const Array<T> &r);
197 template<class T> LogicalArray operator >= (const Array<T> &l,
198  const Array<T> &r);
199 template<class T> LogicalArray operator > (const Array<T> &l,
200  const Array<T> &r);
201 template<class T> LogicalArray operator == (const Array<T> &l,
202  const Array<T> &r);
203 template<class T> LogicalArray operator != (const Array<T> &l,
204  const Array<T> &r);
205 
206 template<class T> LogicalArray near(const Array<T> &l, const Array<T> &r,
207  Double tol);
208 template<class T> LogicalArray nearAbs(const Array<T> &l, const Array<T> &r,
209  Double tol);
210 //
211 // This only makes sense if the array element type is logical valued.
212 // <group>
213 template<class T> LogicalArray operator && (const Array<T> &l, const Array<T> &r);
214 template<class T> LogicalArray operator || (const Array<T> &l, const Array<T> &r);
215 // </group>
216 //
217 // </group>
218 
219 
220 //
221 // Logical negation of an array. This only makes sense if the array
222 // element type is logical valued.
223 template<class T> LogicalArray operator ! (const Array<T> &l);
224 
225 
226 //
227 // Element by element comparisons between an array and a scalar, which
228 // behaves as if it were a conformant array filled with the value "val."
229 // The result is true only if the comparison is true for every element
230 // of the array.
231 // <group>
232 template<class T> Bool allLE (const Array<T> &array, const T &val);
233 template<class T> Bool allLE (const T &val, const Array<T> &array);
234 template<class T> Bool allLT (const Array<T> &array, const T &val);
235 template<class T> Bool allLT (const T &val, const Array<T> &array);
236 template<class T> Bool allGE (const Array<T> &array, const T &val);
237 template<class T> Bool allGE (const T &val, const Array<T> &array);
238 template<class T> Bool allGT (const Array<T> &array, const T &val);
239 template<class T> Bool allGT (const T &val, const Array<T> &array);
240 template<class T> Bool allEQ (const Array<T> &array, const T &val);
241 template<class T> Bool allEQ (const T &val, const Array<T> &array);
242 template<class T> Bool allNE (const Array<T> &array, const T &val);
243 template<class T> Bool allNE (const T &val, const Array<T> &array);
244 template<class T> Bool allNear (const Array<T> &array, const T &val, Double tol);
245 template<class T> Bool allNear (const T &val, const Array<T> &array, Double tol);
246 template<class T> Bool allNearAbs (const Array<T> &array, const T &val,
247  Double tol);
248 template<class T> Bool allNearAbs (const T &val, const Array<T> &array,
249  Double tol);
250 //
251 // This only makes sense if the array element type is logical valued.
252 // <group>
253 template<class T> Bool allAND (const Array<T> &array, const T &val);
254 template<class T> Bool allAND (const T &val, const Array<T> &array);
255 template<class T> Bool allOR (const Array<T> &array, const T &val);
256 template<class T> Bool allOR (const T &val, const Array<T> &array);
257 // </group>
258 //
259 // </group>
260 
261 
262 // Test if all elements in an array are the same.
263 template<class T> Bool allSame (const Array<T> &a)
264  { return a.size() <= 1 || allEQ(*a.data(), a); }
265 
266 
267 // Element by element test for NaN or (In)finity.
268 // <group>
269 template<class T> LogicalArray isNaN (const Array<T> &array);
270 template<class T> LogicalArray isInf (const Array<T> &array);
271 template<class T> LogicalArray isFinite (const Array<T> &array);
272 // </group>
273 
274 //
275 // Element by element comparisons between an array and a scalar, which
276 // behaves as if it were a conformant array filled with the value "val."
277 // The result is a LogicalArray.
278 //
279 // <thrown>
280 // <li> ArrayConformanceError
281 // </thrown>
282 //
283 // <group>
284 template<class T> LogicalArray operator <= (const Array<T> &array, const T &val);
285 template<class T> LogicalArray operator <= (const T &val, const Array<T> &array);
286 template<class T> LogicalArray operator < (const Array<T> &array, const T &val);
287 template<class T> LogicalArray operator < (const T &val, const Array<T> &array);
288 template<class T> LogicalArray operator >= (const Array<T> &array, const T &val);
289 template<class T> LogicalArray operator >= (const T &val, const Array<T> &array);
290 template<class T> LogicalArray operator > (const Array<T> &array, const T &val);
291 template<class T> LogicalArray operator > (const T &val, const Array<T> &array);
292 template<class T> LogicalArray operator == (const Array<T> &array, const T &val);
293 template<class T> LogicalArray operator == (const T &val, const Array<T> &array);
294 template<class T> LogicalArray operator != (const Array<T> &array, const T &val);
295 template<class T> LogicalArray operator != (const T &val, const Array<T> &array);
296 template<class T> LogicalArray near (const Array<T> &array, const T &val,
297  Double tol);
298 template<class T> LogicalArray near (const T &val, const Array<T> &array,
299  Double tol);
300 template<class T> LogicalArray nearAbs (const Array<T> &array, const T &val,
301  Double tol);
302 template<class T> LogicalArray nearAbs (const T &val, const Array<T> &array,
303  Double tol);
304 //
305 // This only makes sense if the array element type is logical valued.
306 // <group>
307 template<class T> LogicalArray operator && (const Array<T> &array, const T &val);
308 template<class T> LogicalArray operator && (const T &val, const Array<T> &array);
309 template<class T> LogicalArray operator || (const Array<T> &array, const T &val);
310 template<class T> LogicalArray operator || (const T &val, const Array<T> &array);
311 // </group>
312 //
313 // </group>
314 
315 
316 //# With two arrays, they must both conform, and the result is done element
317 //# by element. For instance anyLE (a, b) implies that some element of a is
318 //# less than or equal to the corresponding element of b.
319 //# NB comparison between two zero-sized arrays is not defined (should it
320 //# throw an exception?).
321 
322 //
323 // Element by element comparisons between the "l" and "r" arrays. The result
324 // is true if the comparison is true for some element of the arrays.
325 //
326 // <thrown>
327 // <li> ArrayConformanceError
328 // </thrown>
329 //
330 // <group>
331 
332 template<class T> Bool anyLE (const Array<T> &l, const Array<T> &r);
333 template<class T> Bool anyLT (const Array<T> &l, const Array<T> &r);
334 template<class T> Bool anyGE (const Array<T> &l, const Array<T> &r);
335 template<class T> Bool anyGT (const Array<T> &l, const Array<T> &r);
336 template<class T> Bool anyEQ (const Array<T> &l, const Array<T> &r);
337 template<class T> Bool anyNE (const Array<T> &l, const Array<T> &r);
338 template<class T> Bool anyNear (const Array<T> &l, const Array<T> &r,
339  Double tol);
340 template<class T> Bool anyNearAbs (const Array<T> &l, const Array<T> &r,
341  Double tol);
342 //
343 // This only makes sense if the array element type is logical valued.
344 // <group>
345 template<class T> Bool anyAND (const Array<T> &l, const Array<T> &r);
346 template<class T> Bool anyOR (const Array<T> &l, const Array<T> &r);
347 // </group>
348 //
349 // </group>
350 
351 //
352 // Element by element comparisons between an array and a scalar, which
353 // behaves as if it were a conformant array filled with the value "val."
354 // The result is true if the comparison is true for some element of the array.
355 // At some point operators will be available that return masks where the
356 // comparison is true.
357 // <group>
358 
359 template<class T> Bool anyLE (const Array<T> &array, const T &val);
360 template<class T> Bool anyLE (const T &val, const Array<T> &array);
361 template<class T> Bool anyLT (const Array<T> &array, const T &val);
362 template<class T> Bool anyLT (const T &val, const Array<T> &array);
363 template<class T> Bool anyGE (const Array<T> &array, const T &val);
364 template<class T> Bool anyGE (const T &val, const Array<T> &array);
365 template<class T> Bool anyGT (const Array<T> &array, const T &val);
366 template<class T> Bool anyGT (const T &val, const Array<T> &array);
367 template<class T> Bool anyEQ (const Array<T> &array, const T &val);
368 template<class T> Bool anyEQ (const T &val, const Array<T> &array);
369 template<class T> Bool anyNE (const Array<T> &array, const T &val);
370 template<class T> Bool anyNE (const T &val, const Array<T> &array);
371 template<class T> Bool anyNear (const Array<T> &array, const T &val, Double tol);
372 template<class T> Bool anyNear (const T &val, const Array<T> &array, Double tol);
373 template<class T> Bool anyNearAbs (const Array<T> &array, const T &val,
374  Double tol);
375 template<class T> Bool anyNearAbs (const T &val, const Array<T> &array,
376  Double tol);
377 //
378 // This only makes sense if the array element type is logical valued.
379 // <group>
380 template<class T> Bool anyAND (const Array<T> &array, const T &val);
381 template<class T> Bool anyAND (const T &val, const Array<T> &array);
382 template<class T> Bool anyOR (const Array<T> &array, const T &val);
383 template<class T> Bool anyOR (const T &val, const Array<T> &array);
384 // </group>
385 //
386 // </group>
387 
388 
389 // Are all elements true?
390 inline Bool allTrue (const Array<Bool>& array)
391  { return allEQ (array, True); }
392 
393 // Is any all element true?
394 inline Bool anyTrue (const Array<Bool>& array)
395  { return anyEQ (array, True); }
396 
397 //
398 // Determine the number of true or false elements.
399 // Note that is meant for Bool arrays, but can also be used for
400 // e.g. Int arrays.
401 // <group>
402 
403 // Determine it for the full array.
404 // <group>
405 template<class T> size_t nfalse (const Array<T> &array);
406 template<class T> size_t ntrue (const Array<T> &array)
407  { return array.nelements() - nfalse(array); }
408 // </group>
409 
410 // The same functions as above, but determine ntrue and nfalse for the
411 // given axes only. The result is an array with a shape formed by the
412 // remaining axes.
413 // For example, for an array with shape [3,4,5], collapsing axis 0
414 // results in an array with shape [4,5] containing ntrue or nfalse for
415 // each X line.
416 // Summing for axes 0 and 2 results in an array with shape [4] containing
417 // ntrue or nfalse for each XZ plane.
418 // <group>
419 template<class T> Array<uInt> partialNTrue (const Array<T>& array,
420  const IPosition& collapseAxes);
421 template<class T> Array<uInt> partialNFalse (const Array<T>& array,
422  const IPosition& collapseAxes);
423 // </group>
424 
425 // </group>
426 
427 // </group>
428 
429 // Define logical Functors.
430 // <group>
431 class AllFunc {
432 public:
433  Bool operator() (const Array<Bool>& arr) const { return allTrue(arr); }
434 };
435 class AnyFunc {
436 public:
437  Bool operator() (const Array<Bool>& arr) const { return anyTrue(arr); }
438 };
439 template<typename T> class NTrueFunc {
440 public:
441  T operator() (const Array<T>& arr) const { return ntrue(arr); }
442 };
443 template<typename T> class NFalseFunc {
444 public:
445  T operator() (const Array<T>& arr) const { return nfalse(arr); }
446 };
447 // </group>
448 
449 
450 } //# NAMESPACE CASACORE - END
451 
452 #ifndef CASACORE_NO_AUTO_TEMPLATES
453 #include <casacore/casa/Arrays/ArrayLogical.tcc>
454 #endif //# CASACORE_NO_AUTO_TEMPLATES
455 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
bool allNearAbs(const C1 &l, const C2 &r, U tolerance)
Test if all elements of the containers are absolutely near each other.
Definition: StdLogical.h:54
bool allNear(const C1 &l, const C2 &r, U tolerance)
Test if all elements of the containers are relatively near each other.
Definition: StdLogical.h:49
size_t nelements() const
How many elements does this array have? Product of all axis lengths.
Definition: ArrayBase.h:99
bool operator==(const std11_allocator< T > &, const std11_allocator< T > &)
Definition: Allocator.h:99
Bool anyLT(const TableVector< T > &l, const TableVector< T > &r)
Definition: TabVecLogic.h:153
bool operator!=(const std11_allocator< T > &, const std11_allocator< T > &)
Definition: Allocator.h:105
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:1986
Bool near(const GaussianBeam &left, const GaussianBeam &other, const Double relWidthTol, const Quantity &absPaTol)
LatticeExprNode ntrue(const LatticeExprNode &expr)
Bool allTrue(const Array< Bool > &array)
Are all elements true?
Definition: ArrayLogical.h:390
Define logical Functors.
Definition: ArrayLogical.h:431
LatticeExprNode operator>=(const LatticeExprNode &left, const LatticeExprNode &right)
Bool anyNE(const TableVector< T > &l, const TableVector< T > &r)
Definition: TabVecLogic.h:173
T * data()
Get a pointer to the beginning of the array.
Definition: Array.h:596
Bool operator()(const Array< Bool > &arr) const
Definition: ArrayLogical.h:433
LatticeExprNode nfalse(const LatticeExprNode &expr)
LatticeExprNode operator!(const LatticeExprNode &expr)
TableExprNode isInf(const TableExprNode &node)
Definition: ExprNode.h:1683
double Double
Definition: aipstype.h:52
TableExprNode isFinite(const TableExprNode &node)
Function to test if a scalar or array is finite.
Definition: ExprNode.h:1687
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
Bool anyGE(const TableVector< T > &l, const TableVector< T > &r)
Definition: TabVecLogic.h:158
Bool anyGT(const TableVector< T > &l, const TableVector< T > &r)
Definition: TabVecLogic.h:163
template <class T, class U> class vector;
Definition: Array.h:169
LatticeExprNode operator>(const LatticeExprNode &left, const LatticeExprNode &right)
Bool allSame(const Array< T > &a)
Test if all elements in an array are the same.
Definition: ArrayLogical.h:263
Bool anyEQ(const TableVector< T > &l, const TableVector< T > &r)
Definition: TabVecLogic.h:168
Bool anyTrue(const Array< Bool > &array)
Is any all element true?
Definition: ArrayLogical.h:394
TableExprNode nearAbs(const TableExprNode &left, const TableExprNode &right)
Definition: ExprNode.h:1316
LatticeExprNode isNaN(const LatticeExprNode &expr)
Test if a value is a NaN.
size_t size() const
Definition: ArrayBase.h:101
Bool anyLE(const TableVector< T > &l, const TableVector< T > &r)
Element by element comparisons between the "l" and "r" table vectors.
Definition: TabVecLogic.h:148
const Bool True
Definition: aipstype.h:40
LatticeExprNode operator||(const LatticeExprNode &left, const LatticeExprNode &right)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
LatticeExprNode operator&&(const LatticeExprNode &left, const LatticeExprNode &right)
Logical binary operators.