casacore
Loading...
Searching...
No Matches
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
38namespace 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>
99Vector<std::string> strToVector (const std::string& string, char delim = ',');
100Vector<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>
167template<class T>
168Array<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>
184size_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>
217template<class T>
218Array<T> reverseArray (const Array<T>& array,
219 const IPosition& reversedAxes,
220 bool alwaysCopy = true);
221template<class T>
222Array<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>
268template<class T>
269Array<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>
295size_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
Array< T > concatenateArray(const Array< T > &left, const Array< T > &right)
Helper function for partialX functions.
Definition ArrayUtil.h:184
size_t partialFuncHelper(int &nelemCont, IPosition &resultShape, IPosition &incr, const IPosition &sourceShape, const IPosition &collapseAxes)
Helper function for function reorderArray.
Definition ArrayUtil.h:295
size_t reorderArrayHelper(IPosition &newShape, IPosition &incr, const IPosition &shape, const IPosition &newAxisOrder)
Array< T > reorderArray(const Array< T > &array, const IPosition &newAxisOrder, bool alwaysCopy=true)
Reverse the order of one or more axes of an array.
Definition ArrayUtil.h:217
Array< T > reverseArray(const Array< T > &array, size_t axis, bool alwaysCopy=true)
Array< T > reverseArray(const Array< T > &array, const IPosition &reversedAxes, bool alwaysCopy=true)
Vector< std::string > strToVector(const std::string &string, char delim=',')
Vector< std::string > strToVector(const std::string &string, const std::regex &delim)