Loading...
Searching...
No Matches
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 - END
#include "ArrayUtil.tcc"
#endif
Vector.h
casacore::Array
Definition Array.h:155
casacore::IPosition
Definition IPosition.h:117
casacore::Vector
Definition Vector.h:82
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::array
T * array
The actual storage.
Definition Block.h:689
casacore::shape
IPosition shape(const RecordFieldId &) const
Get the actual shape of this field.
casacore::ArrayUtil_global_functions_concatenateArray
Concatenate two Arrays.
Definition ArrayUtil.h:165
casacore::ArrayUtil_global_functions_concatenateArray::concatenateArray
Array< T > concatenateArray(const Array< T > &left, const Array< T > &right)
casacore::ArrayUtil_global_functions_partialFuncHelper
Helper function for partialX functions.
Definition ArrayUtil.h:182
casacore::ArrayUtil_global_functions_partialFuncHelper::partialFuncHelper
size_t partialFuncHelper(int &nelemCont, IPosition &resultShape, IPosition &incr, const IPosition &sourceShape, const IPosition &collapseAxes)
casacore::ArrayUtil_global_functions_reorderArrayHelper
Helper function for function reorderArray.
Definition ArrayUtil.h:293
casacore::ArrayUtil_global_functions_reorderArrayHelper::reorderArrayHelper
size_t reorderArrayHelper(IPosition &newShape, IPosition &incr, const IPosition &shape, const IPosition &newAxisOrder)
casacore::ArrayUtil_global_functions_reorderArray
Reorder the axes of an array.
Definition ArrayUtil.h:266
casacore::ArrayUtil_global_functions_reorderArray::reorderArray
Array< T > reorderArray(const Array< T > &array, const IPosition &newAxisOrder, bool alwaysCopy=true)
casacore::ArrayUtil_global_functions_reverseArray
Reverse the order of one or more axes of an array.
Definition ArrayUtil.h:215
casacore::ArrayUtil_global_functions_reverseArray::reverseArray
Array< T > reverseArray(const Array< T > &array, size_t axis, bool alwaysCopy=true)
casacore::ArrayUtil_global_functions_reverseArray::reverseArray
Array< T > reverseArray(const Array< T > &array, const IPosition &reversedAxes, bool alwaysCopy=true)
casacore::ArrayUtil_global_functions_stringToVector
Definition ArrayUtil.h:97
casacore::ArrayUtil_global_functions_stringToVector::strToVector
Vector< std::string > strToVector(const std::string &string, char delim=',')
casacore::ArrayUtil_global_functions_stringToVector::strToVector
Vector< std::string > strToVector(const std::string &string, const std::regex &delim)