casacore
ArrayUtil.h
Go to the documentation of this file.
1 //# ArrayUtil.h: Utility functions for arrays
2 //# Copyright (C) 1995,1999,2000,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_ARRAYUTIL_H
29 #define CASA_ARRAYUTIL_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/Vector.h>
35 #include <casacore/casa/BasicSL/String.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class Regex;
41 
42 // <summary>
43 // Split a String into its elements.
44 // </summary>
45 
46 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil">
47 
48 // <prerequisite>
49 // <li> <linkto class=Vector>Vector</linkto>
50 // <li> <linkto class=String>String</linkto>
51 // </prerequisite>
52 
53 // <etymology>
54 // stringToVector converts a String to a Vector of Strings.
55 // </etymology>
56 
57 // <synopsis>
58 // The function stringToVector splits a string into its elements
59 // using the given delimiter and returns them in a <src>Vector<String></src>.
60 // The default delimiter is a comma (,).
61 // It is very useful when using a function taking a vector of strings
62 // as shown in the example.
63 // <p>
64 // A more advanced way of splitting a string is by using a
65 // <linkto class=Regex>regular expression</linkto> as delimiter.
66 // It makes it, for example, possible to treat whitespace around a comma
67 // as part of the delimiter (as shown in an example below).
68 // <p>
69 // A string with length 0 results in a zero-length vector.
70 // </synopsis>
71 
72 // <motivation>
73 // As shown in the example, the function stringToVector makes
74 // passing a Vector of Strings far easier.
75 // </motivation>
76 
77 // <example>
78 // <srcblock>
79 // someFunction (stringToVector ("abc,def ,,gh"));
80 // </srcblock>
81 // This results in a vector with 4 elements containing the values
82 // "abc", "def ", "", and "gh". The vector is passed to someFunction.
83 // This is far easier than having to do it as:
84 // <srcblock>
85 // Vector<String> vector(4);
86 // vector(0) = "abc";
87 // vector(1) = "def ";
88 // vector(2) = "";
89 // vector(3) = "gh";
90 // someFunction (vector);
91 // </srcblock>
92 //
93 // The following example shows how to use a delimiter consisting of a comma
94 // surrounded by possible whitespace.
95 // <srcblock>
96 // Vector<String> result = stringToVector (source, Regex(" *, *"));
97 // </srcblock>
98 // <example>
99 
100 // <group name=stringToVector>
101 Vector<String> stringToVector (const String& string, char delim = ',');
102 Vector<String> stringToVector (const String& string, const Regex& delim);
103 // </group>
104 
105 
106 
107 // <summary>
108 // Concatenate two Arrays.
109 // </summary>
110 
111 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil">
112 
113 // <prerequisite>
114 // <li> <linkto class=Array>Array</linkto>
115 // </prerequisite>
116 
117 // <etymology>
118 // concatenateArray concatenates two Arrays into a new Array.
119 // </etymology>
120 
121 // <synopsis>
122 // The function concatenates two Arrays into a new Array.
123 // The shape of both arrays must match except for the last dimension.
124 // The shape of the resulting array is equal to that of the input
125 // arrays with its last dimension as the sum of both last dimensions.
126 // <p>
127 // An exception ArrayConformanceError is thrown when the shapes
128 // do not match.
129 // </synopsis>
130 
131 // <motivation>
132 // The table system needed this function.
133 // </motivation>
134 
135 // <example>
136 // <srcblock>
137 // Vector<Int> vector1(5);
138 // Vector<Int> vector2(10);
139 // indgen (vector1); // fill with values 0..4
140 // indgen (vector2); // fill with values 0..9
141 // Vector<Int> result = concatenateVector (vector1, vector2);
142 // </srcblock>
143 // The example above results in a vector with length 15 and values
144 // 0,1,2,3,4,0,1,2,3,4,5,6,7,8,9.
145 // <p>
146 // It can also be used with matrices or arrays with higher dimensionality
147 // as long as all dimensions but the last one have equal length.
148 // <srcblock>
149 // Matrix<Int> matrix1 (3,4);
150 // Matrix<Int> matrix2 (3,5);
151 // Matrix<Int> matrix3 (4,4);
152 // // Concatenation of matrix1 and matrix 2 will succeed and result
153 // // in a 3x9 matrix.
154 // Matrix<Int> matrixConc = concatenateArray (matrix1, matrix2);
155 // if (matrixConc.shape() != IPosition(2,3,9)) {
156 // cout << "Error in shape of concatenated matrices" << endl;
157 // }
158 // // Concatenation of matrix1 and matrix3 will fail, because the
159 // // first dimensions have a different length (3 vs. 4).
160 // try {
161 // concatenateArray (matrix1, matrix2);
162 // } catch (ArrayConformanceError x) {
163 // cout << x.getMesg() << endl;
164 // }
165 // </srcblock>
166 // <example>
167 
168 // <group name=concatenateArray>
169 template<class T>
170 Array<T> concatenateArray (const Array<T>& left, const Array<T>& right);
171 // </group>
172 
173 
174 
175 // <summary> Helper function for partialX functions </summary>
176 // <use visibility=export>
177 // <synopsis>
178 // This is a specialized helper function for functions like partialSums.
179 // It determines the shape of the resulting array and calculates the
180 // result increments when iterating linearly through the source array.
181 // It returns the first result axis which indicates the number of the first
182 // contiguous collapse axes. The number of contiguous data points is
183 // returned in nelemCont.
184 // </synopsis>
185 // <group name=partialFuncHelper>
186 uInt partialFuncHelper (Int& nelemCont,
187  IPosition& resultShape, IPosition& incr,
188  const IPosition& sourceShape,
189  const IPosition& collapseAxes);
190 // </group>
191 
192 
193 // <summary>
194 // Reverse the order of one or more axes of an array.
195 // </summary>
196 
197 // <use visibility=export>
198 
199 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil2.cc">
200 
201 // <synopsis>
202 // This function makes it possible to reverse one or more axes of an array by
203 // swapping around the elements of each axis.
204 // The resulting array is a copy of the input array with its data
205 // moved around according to the new order.
206 // If the order does not change, a copy is returned if the
207 // <src>alwaysCopy</src> is true. Otherwise a reference of the
208 // input array is returned.
209 // <p>
210 // Reversing axis 0 means that its elements are reversed.
211 // Reversing axis 1 means that the
212 // </synopsis>
213 
214 // <example>
215 // Reversing axis 0 of a Vector means that the Vector is reversed.
216 // Reversing axis 1 of a Matrix means that its rows are reversed.
217 // Reversing axis 0 of an N-dim array means that the elements of each Vector
218 // in that array are reversed.
219 // Reversing axis 1 of a Matrix means that its columns are reversed.
220 // </example>
221 
222 // <group name=reverseArray>
223 template<class T>
224 Array<T> reverseArray (const Array<T>& array,
225  const IPosition& reversedAxes,
226  Bool alwaysCopy = True);
227 template<class T>
228 Array<T> reverseArray (const Array<T>& array, uInt axis,
229  Bool alwaysCopy = True);
230 // </group>
231 
232 
233 // <summary>
234 // Reorder the axes of an array.
235 // </summary>
236 
237 // <use visibility=export>
238 
239 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil2.cc">
240 
241 // <synopsis>
242 // This function makes it possible to reorder the axes of an array.
243 // The resulting array is a copy of the input array with its data
244 // moved around according to the new array order.
245 // If the order does not change, a copy is returned if the
246 // <src>alwaysCopy</src> is true. Otherwise a reference of the
247 // input array is returned.
248 // <p>
249 // The <src>newAxisOrder</src> defines the new axes order.
250 // Its length can be less than the dimensionality of the input array.
251 // It is appended with the non-specified axes in their natural order.
252 // <src>newAxisOrder(i)</src> gives the axis in the original array
253 // which will now get axis <src>i</src>.
254 // </synopsis>
255 
256 // <example>
257 // <srcblock>
258 // Array<Int> result = reorderArray (someArray, IPosition(2,1,3));
259 // </srcblock>
260 // Say that someArray is a 4D array with shape [3,4,5,6].
261 // The non-specified axes get appended to the axis order
262 // specification [1,3] resulting in [1,3,0,2].
263 // <br> This means that axis 1 gets axis 0, axis 3 gets axis 1, axis 0 gets
264 // axis 2, and axis 2 gets axis 3.
265 // Thus the resulting shape is [4,6,3,5] and the data are moved accordingly.
266 // </example>
267 
268 // <motivation>
269 // This function was needed for an efficient implementation of the
270 // functions partialMedians and partialFractiles.
271 // </motivation>
272 
273 // <group name=reorderArray>
274 template<class T>
275 Array<T> reorderArray (const Array<T>& array,
276  const IPosition& newAxisOrder,
277  Bool alwaysCopy = True);
278 // </group>
279 
280 
281 // <summary>
282 // Helper function for function reorderArray.
283 // </summary>
284 
285 // <use visibility=local>
286 
287 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil2.cc">
288 
289 // <synopsis>
290 // This is a specialized helper function for function reorderArray.
291 // It determines the shape of the resulting array and calculates the
292 // result increments when iterating linearly through the source array.
293 // It returns the number of the first non-reordered axes.
294 // </synopsis>
295 
296 // <motivation>
297 // Split off common non-templated code.
298 // </motivation>
299 
300 // <group name=reorderArrayHelper>
301 uInt reorderArrayHelper (IPosition& newShape, IPosition& incr,
302  const IPosition& shape, const IPosition& newAxisOrder);
303 // </group>
304 
305 
306 
307 } //# NAMESPACE CASACORE - END
308 
309 #ifndef CASACORE_NO_AUTO_TEMPLATES
310 #include <casacore/casa/Arrays/ArrayUtil.tcc>
311 #endif //# CASACORE_NO_AUTO_TEMPLATES
312 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
int Int
Definition: aipstype.h:50
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:2093
Regular expression class.
Definition: Regex.h:198
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:2151
template <class T, class U> class vector;
Definition: Array.h:169
String: the storage and methods of handling collections of characters.
Definition: String.h:223
const Bool True
Definition: aipstype.h:43
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51