ArrayUtil.h

Classes

Global Functions -- Split a String into its elements. (full description)
Global Functions -- Concatenate two Arrays. (full description)
Global Functions -- Reorder the axes of an array. (full description)
Global Functions -- Helper function for function reorderArray.. (full description)

Split a String into its elements. (source)

Interface

Vector<String> stringToVector (const String& string, char delim = ',')
Vector<String> stringToVector (const String& string, const Regex& delim)

Description

Review Status

Programs:
Tests:

Prerequisite

Etymology

stringToVector converts a String to a Vector of Strings.

Synopsis

The function stringToVector splits a string into its elements using the given delimiter and returns them in a Vector<String>. The default delimiter is a comma (,). It is very useful when using a function taking a vector of strings as shown in the example.

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).

A string with length 0 results in a zero-length vector.

Motivation

As shown in the example, the function stringToVector makes passing a Vector of Strings far easier.

Example

    someFunction (stringToVector ("abc,def ,,gh"));
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: 
    Vector<String> vector(4);
    vector(0) = "abc";
    vector(1) = "def ";
    vector(2) = "";
    vector(3) = "gh";
    someFunction (vector);

The following example shows how to use a delimiter consisting of a comma surrounded by possible whitespace. 

    Vector<String> result = stringToVector (source, Regex(" *, *"));

Example

Member Description

Vector<String> stringToVector (const String& string, char delim = ',')

Vector<String> stringToVector (const String& string, const Regex& delim)

Concatenate two Arrays. (source)

Interface

Array<T> concatenateArray (const Array<T>& left, const Array<T>& right)

Description

Review Status

Programs:
Tests:

Prerequisite

Etymology

concatenateArray concatenates two Arrays into a new Array.

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.

An exception ArrayConformanceError is thrown when the shapes do not match.

Motivation

The table system needed this function.

Example

    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);
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.

It can also be used with matrices or arrays with higher dimensionality as long as all dimensions but the last one have equal length. 

    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.getMesg() << endl;
    }

Example

Member Description

Array<T> concatenateArray (const Array<T>& left, const Array<T>& right)

Reorder the axes of an array. (source)

Interface

Array<T> reorderArray (const Array<T>& array, const IPosition& newAxisOrder, Bool alwaysCopy = True)

Description

Review Status

Programs:
Tests:

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 alwaysCopy is true. Otherwise a reference of the input array is returned.

The newAxisOrder 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. newAxisOrder(i) gives the axis in the original array which will now get axis i.

Example

   Array<Int> result = reorderArray (someArray, IPosition(2,1,3));
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].
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.

Motivation

This function was needed for an efficient implementation of the functions partialMedians and partialFractiles.

Member Description

Array<T> reorderArray (const Array<T>& array, const IPosition& newAxisOrder, Bool alwaysCopy = True)

Helper function for function reorderArray.. (source)

Interface

uInt reorderArrayHelper (IPosition& newShape, IPosition& incr, const IPosition& shape, const IPosition& newAxisOrder)

Description

Review Status

Programs:
Tests:

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.

Motivation

Split off common non-templated code.

Member Description

uInt reorderArrayHelper (IPosition& newShape, IPosition& incr, const IPosition& shape, const IPosition& newAxisOrder)