ArrayUtil.h

Go to the documentation of this file.

// # ArrayUtil.h: Utility functions for arrays
// # Copyright (C) 1995,1999,2000,2001
// # Associated Universities, Inc. Washington DC, USA.
// #
// # This library is free software; you can redistribute it and/or modify it
// # under the terms of the GNU Library General Public License as published by
// # the Free Software Foundation; either version 2 of the License, or (at your
// # option) any later version.
// #
// # This library is distributed in the hope that it will be useful, but WITHOUT
// # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
// # License for more details.
// #
// # You should have received a copy of the GNU Library General Public License
// # along with this library; if not, write to the Free Software Foundation,
// # Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
// #
// # Correspondence concerning AIPS++ should be addressed as follows:
// #        Internet email: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef CASA_ARRAYUTIL_2_H
#define CASA_ARRAYUTIL_2_H
 
// # Includes
#include "Vector.h"
 
#include <regex>
#include <string>
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// <summary>
// Split a std::string into its elements.
// </summary>
 
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil">
 
// <prerequisite>
//   <li> <linkto class=Vector>Vector</linkto>
//   <li> std::string
// </prerequisite>
 
// <etymology>
// stringToVector converts a std::string to a Vector of Strings.
// </etymology>
 
// <synopsis>
// The function stringToVector splits a string into its elements
// using the given delimiter and returns them in a <src>Vector<std::string></src>.
// The default delimiter is a comma (,).
// It is very useful when using a function taking a vector of strings
// as shown in the example.
// <p>
// A more advanced way of splitting a string is by using a
// regular expression as delimiter.
// It makes it, for example, possible to treat whitespace around a comma
// as part of the delimiter (as shown in an example below).
// <p>
// A string with length 0 results in a zero-length vector.
// </synopsis>
 
// <motivation>
// As shown in the example, the function stringToVector makes
// passing a Vector of Strings far easier.
// </motivation>
 
// <example>
// <srcblock>
// someFunction (stringToVector ("abc,def ,,gh"));
// </srcblock>
// This results in a vector with 4 elements containing the values
// "abc", "def ", "", and "gh". The vector is passed to someFunction.
// This is far easier than having to do it as:
// <srcblock>
// Vector<std::string> vector(4);
// vector(0) = "abc";
// vector(1) = "def ";
// vector(2) = "";
// vector(3) = "gh";
// someFunction (vector);
// </srcblock>
//
// The following example shows how to use a delimiter consisting of a comma
// surrounded by possible whitespace.
// <srcblock>
// Vector<std::string> result = stringToVector (source, Regex(" *, *"));
// </srcblock>
// <example>
 
// <group name=stringToVector>
Vector<std::string> strToVector(const std::string& string, char delim = ',');
Vector<std::string> strToVector(const std::string& string, const std::regex& delim);
// </group>
 
// <summary>
// Concatenate two Arrays.
// </summary>
 
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil">
 
// <prerequisite>
//   <li> <linkto class=Array>Array</linkto>
// </prerequisite>
 
// <etymology>
// concatenateArray concatenates two Arrays into a new Array.
// </etymology>
 
// <synopsis>
// The function concatenates two Arrays into a new Array.
// The shape of both arrays must match except for the last dimension.
// The shape of the resulting array is equal to that of the input
// arrays with its last dimension as the sum of both last dimensions.
// <p>
// An exception ArrayConformanceError is thrown when the shapes
// do not match.
// </synopsis>
 
// <motivation>
// The table system needed this function.
// </motivation>
 
// <example>
// <srcblock>
// Vector<int> vector1(5);
// Vector<int> vector2(10);
// indgen (vector1);             // fill with values 0..4
// indgen (vector2);             // fill with values 0..9
// Vector<int> result = concatenateVector (vector1, vector2);
// </srcblock>
// The example above results in a vector with length 15 and values
// 0,1,2,3,4,0,1,2,3,4,5,6,7,8,9.
// <p>
// It can also be used with matrices or arrays with higher dimensionality
// as long as all dimensions but the last one have equal length.
// <srcblock>
// Matrix<int> matrix1 (3,4);
// Matrix<int> matrix2 (3,5);
// Matrix<int> matrix3 (4,4);
// // Concatenation of matrix1 and matrix 2 will succeed and result
// // in a 3x9 matrix.
// Matrix<int> matrixConc = concatenateArray (matrix1, matrix2);
// if (matrixConc.shape() != IPosition(2,3,9)) {
//     cout << "Error in shape of concatenated matrices" << endl;
// }
// // Concatenation of matrix1 and matrix3 will fail, because the
// // first dimensions have a different length (3 vs. 4).
// try {
//     concatenateArray (matrix1, matrix2);
// } catch (ArrayConformanceError x) {
//     cout << x.what() << endl;
// }
// </srcblock>
// <example>
 
// <group name=concatenateArray>
template <class T>
Array<T> concatenateArray(const Array<T>& left, const Array<T>& right);
// </group>
 
// <summary> Helper function for partialX functions </summary>
// <use visibility=export>
// <synopsis>
// This is a specialized helper function for functions like partialSums.
// It determines the shape of the resulting array and calculates the
// result increments when iterating linearly through the source array.
// It returns the first result axis which indicates the number of the first
// contiguous collapse axes. The number of contiguous data points is
// returned in nelemCont.
// </synopsis>
// <group name=partialFuncHelper>
size_t partialFuncHelper(int& nelemCont, IPosition& resultShape, IPosition& incr,
                         const IPosition& sourceShape, const IPosition& collapseAxes);
// </group>
 
// <summary>
// Reverse the order of one or more axes of an array.
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil2.cc">
 
// <synopsis>
// This function makes it possible to reverse one or more axes of an array by
// swapping around the elements of each axis.
// The resulting array is a copy of the input array with its data
// moved around according to the new order.
// If the order does not change, a copy is returned if the
// <src>alwaysCopy</src> is true. Otherwise a reference of the
// input array is returned.
// </synopsis>
 
// <example>
// Reversing axis 0 of a Vector means that the Vector is reversed.
// Reversing axis 1 of a Matrix means that its rows are reversed.
// Reversing axis 0 of an N-dim array means that the elements of each Vector
// in that array are reversed.
// </example>
 
// <group name=reverseArray>
template <class T>
Array<T> reverseArray(const Array<T>& array, const IPosition& reversedAxes, bool alwaysCopy = true);
template <class T>
Array<T> reverseArray(const Array<T>& array, size_t axis, bool alwaysCopy = true);
// </group>
 
// <summary>
// Reorder the axes of an array.
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil2.cc">
 
// <synopsis>
// This function makes it possible to reorder the axes of an array.
// The resulting array is a copy of the input array with its data
// moved around according to the new array order.
// If the order does not change, a copy is returned if the
// <src>alwaysCopy</src> is true. Otherwise a reference of the
// input array is returned.
// <p>
// The <src>newAxisOrder</src> defines the new axes order.
// Its length can be less than the dimensionality of the input array.
// It is appended with the non-specified axes in their natural order.
// <src>newAxisOrder(i)</src> gives the axis in the original array
// which will now get axis <src>i</src>.
// </synopsis>
 
// <example>
// <srcblock>
//   Array<int> result = reorderArray (someArray, IPosition(2,1,3));
// </srcblock>
// Say that someArray is a 4D array with shape [3,4,5,6].
// The non-specified axes get appended to the axis order
// specification [1,3] resulting in [1,3,0,2].
// <br> This means that axis 1 gets axis 0, axis 3 gets axis 1, axis 0 gets
// axis 2, and axis 2 gets axis 3.
// Thus the resulting shape is [4,6,3,5] and the data are moved accordingly.
// </example>
 
// <motivation>
// This function was needed for an efficient implementation of the
// functions partialMedians and partialFractiles.
// </motivation>
 
// <group name=reorderArray>
template <class T>
Array<T> reorderArray(const Array<T>& array, const IPosition& newAxisOrder, bool alwaysCopy = true);
// </group>
 
// <summary>
// Helper function for function reorderArray.
// </summary>
 
// <use visibility=local>
 
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArrayUtil2.cc">
 
// <synopsis>
// This is a specialized helper function for function reorderArray.
// It determines the shape of the resulting array and calculates the
// result increments when iterating linearly through the source array.
// It returns the number of the first non-reordered axes.
// </synopsis>
 
// <motivation>
// Split off common non-templated code.
// </motivation>
 
// <group name=reorderArrayHelper>
size_t reorderArrayHelper(IPosition& newShape, IPosition& incr, const IPosition& shape,
                          const IPosition& newAxisOrder);
// </group>
 
}  // namespace casacore
 
#include "ArrayUtil.tcc"
 
#endif