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