org.apache.commons.math4.util

## Class MathArrays

• public class MathArrays
extends Object
Arrays utilities.
Since:
3.0
• ### Nested Class Summary

Nested Classes
Modifier and Type Class and Description
static interface  MathArrays.Function
Real-valued function that operate on an array or a part of it.
static class  MathArrays.OrderDirection
Specification of ordering direction.
• ### Method Summary

All Methods
Modifier and Type Method and Description
static <T> T[] buildArray(Field<T> field, int length)
Build an array of elements.
static <T> T[][] buildArray(Field<T> field, int rows, int columns)
Build a double dimension array of elements.
static void checkEqualLength(double[] a, double[] b)
Check that both arrays have the same length.
static boolean checkEqualLength(double[] a, double[] b, boolean abort)
Check that both arrays have the same length.
static void checkEqualLength(int[] a, int[] b)
Check that both arrays have the same length.
static boolean checkEqualLength(int[] a, int[] b, boolean abort)
Check that both arrays have the same length.
static void checkNonNegative(long[] in)
Check that all entries of the input array are >= 0.
static void checkNonNegative(long[][] in)
Check all entries of the input array are >= 0.
static void checkNotNaN(double[] in)
Check that no entry of the input array is NaN.
static void checkOrder(double[] val)
Check that the given array is sorted in strictly increasing order.
static void checkOrder(double[] val, MathArrays.OrderDirection dir, boolean strict)
Check that the given array is sorted.
static boolean checkOrder(double[] val, MathArrays.OrderDirection dir, boolean strict, boolean abort)
Check that the given array is sorted.
static void checkPositive(double[] in)
Check that all entries of the input array are strictly positive.
static void checkRectangular(long[][] in)
Throws DimensionMismatchException if the input array is not rectangular.
static double[] concatenate(double[]... x)
Concatenates a sequence of arrays.
static double[] convolve(double[] x, double[] h)
Calculates the convolution between two sequences.
static double distance(double[] p1, double[] p2)
Calculates the L2 (Euclidean) distance between two points.
static double distance(int[] p1, int[] p2)
Calculates the L2 (Euclidean) distance between two points.
static double distance1(double[] p1, double[] p2)
Calculates the L1 (sum of abs) distance between two points.
static int distance1(int[] p1, int[] p2)
Calculates the L1 (sum of abs) distance between two points.
static double distanceInf(double[] p1, double[] p2)
Calculates the L (max of abs) distance between two points.
static int distanceInf(int[] p1, int[] p2)
Calculates the L (max of abs) distance between two points.
static double[] ebeAdd(double[] a, double[] b)
Creates an array whose contents will be the element-by-element addition of the arguments.
static double[] ebeDivide(double[] a, double[] b)
Creates an array whose contents will be the element-by-element division of the first argument by the second.
static double[] ebeMultiply(double[] a, double[] b)
Creates an array whose contents will be the element-by-element multiplication of the arguments.
static double[] ebeSubtract(double[] a, double[] b)
Creates an array whose contents will be the element-by-element subtraction of the second argument from the first.
static boolean equals(double[] x, double[] y)
Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by Precision.equals(double,double).
static boolean equals(float[] x, float[] y)
Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by Precision.equals(float,float).
static boolean equalsIncludingNaN(double[] x, double[] y)
Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by this method.
static boolean equalsIncludingNaN(float[] x, float[] y)
Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by this method.
static boolean isMonotonic(double[] val, MathArrays.OrderDirection dir, boolean strict)
Check that an array is monotonically increasing or decreasing.
static <T extends Comparable<? super T>>boolean isMonotonic(T[] val, MathArrays.OrderDirection dir, boolean strict)
Check that an array is monotonically increasing or decreasing.
static int[] natural(int n)
Returns an array representing the natural number n.
static double[] normalizeArray(double[] values, double normalizedSum)
Normalizes an array to make it sum to a specified value.
static double[] scale(double val, double[] arr)
Create a copy of an array scaled by a value.
static void scaleInPlace(double val, double[] arr)
Multiply each element of an array by a value.
static int[] sequence(int size, int start, int stride)
Returns an array of size integers starting at start, skipping stride numbers.
static void sortInPlace(double[] x, double[]... yList)
Sort an array in ascending order in place and perform the same reordering of entries on other arrays.
static void sortInPlace(double[] x, MathArrays.OrderDirection dir, double[]... yList)
Sort an array in place and perform the same reordering of entries on other arrays.
static double[] unique(double[] data)
Returns an array consisting of the unique values in data.
static boolean verifyValues(double[] values, double[] weights, int begin, int length)
This method is used to verify that the begin and length parameters designate a subarray of positive length and the weights are all non-negative, non-NaN, finite, and not all zero.
static boolean verifyValues(double[] values, double[] weights, int begin, int length, boolean allowEmpty)
This method is used to verify that the begin and length parameters designate a subarray of positive length and the weights are all non-negative, non-NaN, finite, and not all zero.
static boolean verifyValues(double[] values, int begin, int length)
This method is used to verify that the input parameters designate a subarray of positive length.
static boolean verifyValues(double[] values, int begin, int length, boolean allowEmpty)
This method is used to verify that the input parameters designate a subarray of positive length.
• ### Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
• ### Method Detail

• #### scale

public static double[] scale(double val,
double[] arr)
Create a copy of an array scaled by a value.
Parameters:
arr - Array to scale.
val - Scalar.
Returns:
scaled copy of array with each entry multiplied by val.
Since:
3.2
• #### scaleInPlace

public static void scaleInPlace(double val,
double[] arr)

Multiply each element of an array by a value.

The array is modified in place (no copy is created).

Parameters:
arr - Array to scale
val - Scalar
Since:
3.2

public static double[] ebeAdd(double[] a,
double[] b)
throws DimensionMismatchException
Creates an array whose contents will be the element-by-element addition of the arguments.
Parameters:
a - First term of the addition.
b - Second term of the addition.
Returns:
a new array r where r[i] = a[i] + b[i].
Throws:
DimensionMismatchException - if the array lengths differ.
Since:
3.1
• #### ebeSubtract

public static double[] ebeSubtract(double[] a,
double[] b)
throws DimensionMismatchException
Creates an array whose contents will be the element-by-element subtraction of the second argument from the first.
Parameters:
a - First term.
b - Element to be subtracted.
Returns:
a new array r where r[i] = a[i] - b[i].
Throws:
DimensionMismatchException - if the array lengths differ.
Since:
3.1
• #### ebeMultiply

public static double[] ebeMultiply(double[] a,
double[] b)
throws DimensionMismatchException
Creates an array whose contents will be the element-by-element multiplication of the arguments.
Parameters:
a - First factor of the multiplication.
b - Second factor of the multiplication.
Returns:
a new array r where r[i] = a[i] * b[i].
Throws:
DimensionMismatchException - if the array lengths differ.
Since:
3.1
• #### ebeDivide

public static double[] ebeDivide(double[] a,
double[] b)
throws DimensionMismatchException
Creates an array whose contents will be the element-by-element division of the first argument by the second.
Parameters:
a - Numerator of the division.
b - Denominator of the division.
Returns:
a new array r where r[i] = a[i] / b[i].
Throws:
DimensionMismatchException - if the array lengths differ.
Since:
3.1
• #### distance1

public static double distance1(double[] p1,
double[] p2)
throws DimensionMismatchException
Calculates the L1 (sum of abs) distance between two points.
Parameters:
p1 - the first point
p2 - the second point
Returns:
the L1 distance between the two points
Throws:
DimensionMismatchException - if the array lengths differ.
• #### distance1

public static int distance1(int[] p1,
int[] p2)
throws DimensionMismatchException
Calculates the L1 (sum of abs) distance between two points.
Parameters:
p1 - the first point
p2 - the second point
Returns:
the L1 distance between the two points
Throws:
DimensionMismatchException - if the array lengths differ.
• #### distance

public static double distance(double[] p1,
double[] p2)
throws DimensionMismatchException
Calculates the L2 (Euclidean) distance between two points.
Parameters:
p1 - the first point
p2 - the second point
Returns:
the L2 distance between the two points
Throws:
DimensionMismatchException - if the array lengths differ.
• #### distance

public static double distance(int[] p1,
int[] p2)
throws DimensionMismatchException
Calculates the L2 (Euclidean) distance between two points.
Parameters:
p1 - the first point
p2 - the second point
Returns:
the L2 distance between the two points
Throws:
DimensionMismatchException - if the array lengths differ.
• #### distanceInf

public static double distanceInf(double[] p1,
double[] p2)
throws DimensionMismatchException
Calculates the L (max of abs) distance between two points.
Parameters:
p1 - the first point
p2 - the second point
Returns:
the L distance between the two points
Throws:
DimensionMismatchException - if the array lengths differ.
• #### distanceInf

public static int distanceInf(int[] p1,
int[] p2)
throws DimensionMismatchException
Calculates the L (max of abs) distance between two points.
Parameters:
p1 - the first point
p2 - the second point
Returns:
the L distance between the two points
Throws:
DimensionMismatchException - if the array lengths differ.
• #### isMonotonic

public static <T extends Comparable<? super T>> boolean isMonotonic(T[] val,
MathArrays.OrderDirection dir,
boolean strict)
Check that an array is monotonically increasing or decreasing.
Type Parameters:
T - the type of the elements in the specified array
Parameters:
val - Values.
dir - Ordering direction.
strict - Whether the order should be strict.
Returns:
true if sorted, false otherwise.
• #### isMonotonic

public static boolean isMonotonic(double[] val,
MathArrays.OrderDirection dir,
boolean strict)
Check that an array is monotonically increasing or decreasing.
Parameters:
val - Values.
dir - Ordering direction.
strict - Whether the order should be strict.
Returns:
true if sorted, false otherwise.
• #### checkEqualLength

public static boolean checkEqualLength(double[] a,
double[] b,
boolean abort)
Check that both arrays have the same length.
Parameters:
a - Array.
b - Array.
abort - Whether to throw an exception if the check fails.
Returns:
true if the arrays have the same length.
Throws:
DimensionMismatchException - if the lengths differ and abort is true.
Since:
3.6
• #### checkEqualLength

public static void checkEqualLength(double[] a,
double[] b)
Check that both arrays have the same length.
Parameters:
a - Array.
b - Array.
Throws:
DimensionMismatchException - if the lengths differ.
Since:
3.6
• #### checkEqualLength

public static boolean checkEqualLength(int[] a,
int[] b,
boolean abort)
Check that both arrays have the same length.
Parameters:
a - Array.
b - Array.
abort - Whether to throw an exception if the check fails.
Returns:
true if the arrays have the same length.
Throws:
DimensionMismatchException - if the lengths differ and abort is true.
Since:
3.6
• #### checkEqualLength

public static void checkEqualLength(int[] a,
int[] b)
Check that both arrays have the same length.
Parameters:
a - Array.
b - Array.
Throws:
DimensionMismatchException - if the lengths differ.
Since:
3.6
• #### checkOrder

public static boolean checkOrder(double[] val,
MathArrays.OrderDirection dir,
boolean strict,
boolean abort)
throws NonMonotonicSequenceException
Check that the given array is sorted.
Parameters:
val - Values.
dir - Ordering direction.
strict - Whether the order should be strict.
abort - Whether to throw an exception if the check fails.
Returns:
true if the array is sorted.
Throws:
NonMonotonicSequenceException - if the array is not sorted and abort is true.
• #### checkOrder

public static void checkOrder(double[] val,
MathArrays.OrderDirection dir,
boolean strict)
throws NonMonotonicSequenceException
Check that the given array is sorted.
Parameters:
val - Values.
dir - Ordering direction.
strict - Whether the order should be strict.
Throws:
NonMonotonicSequenceException - if the array is not sorted.
Since:
2.2
• #### checkOrder

public static void checkOrder(double[] val)
throws NonMonotonicSequenceException
Check that the given array is sorted in strictly increasing order.
Parameters:
val - Values.
Throws:
NonMonotonicSequenceException - if the array is not sorted.
Since:
2.2
• #### checkRectangular

public static void checkRectangular(long[][] in)
throws NullArgumentException,
DimensionMismatchException
Throws DimensionMismatchException if the input array is not rectangular.
Parameters:
in - array to be tested
Throws:
NullArgumentException - if input array is null
DimensionMismatchException - if input array is not rectangular
Since:
3.1
• #### checkPositive

public static void checkPositive(double[] in)
throws NotStrictlyPositiveException
Check that all entries of the input array are strictly positive.
Parameters:
in - Array to be tested
Throws:
NotStrictlyPositiveException - if any entries of the array are not strictly positive.
Since:
3.1
• #### checkNotNaN

public static void checkNotNaN(double[] in)
throws NotANumberException
Check that no entry of the input array is NaN.
Parameters:
in - Array to be tested.
Throws:
NotANumberException - if an entry is NaN.
Since:
3.4
• #### checkNonNegative

public static void checkNonNegative(long[] in)
throws NotPositiveException
Check that all entries of the input array are >= 0.
Parameters:
in - Array to be tested
Throws:
NotPositiveException - if any array entries are less than 0.
Since:
3.1
• #### checkNonNegative

public static void checkNonNegative(long[][] in)
throws NotPositiveException
Check all entries of the input array are >= 0.
Parameters:
in - Array to be tested
Throws:
NotPositiveException - if any array entries are less than 0.
Since:
3.1
• #### sortInPlace

public static void sortInPlace(double[] x,
double[]... yList)
throws DimensionMismatchException,
NullArgumentException
Sort an array in ascending order in place and perform the same reordering of entries on other arrays. For example, if x = [3, 1, 2], y = [1, 2, 3] and z = [0, 5, 7], then sortInPlace(x, y, z) will update x to [1, 2, 3], y to [2, 3, 1] and z to [5, 7, 0].
Parameters:
x - Array to be sorted and used as a pattern for permutation of the other arrays.
yList - Set of arrays whose permutations of entries will follow those performed on x.
Throws:
DimensionMismatchException - if any y is not the same size as x.
NullArgumentException - if x or any y is null.
Since:
3.0
• #### sortInPlace

public static void sortInPlace(double[] x,
MathArrays.OrderDirection dir,
double[]... yList)
throws NullArgumentException,
DimensionMismatchException
Sort an array in place and perform the same reordering of entries on other arrays. This method works the same as the other sortInPlace method, but allows the order of the sort to be provided in the dir parameter.
Parameters:
x - Array to be sorted and used as a pattern for permutation of the other arrays.
dir - Order direction.
yList - Set of arrays whose permutations of entries will follow those performed on x.
Throws:
DimensionMismatchException - if any y is not the same size as x.
NullArgumentException - if x or any y is null
Since:
3.0
• #### equals

public static boolean equals(float[] x,
float[] y)
Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by Precision.equals(float,float).
Parameters:
x - first array
y - second array
Returns:
true if the values are both null or have same dimension and equal elements.
• #### equalsIncludingNaN

public static boolean equalsIncludingNaN(float[] x,
float[] y)
Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by this method.
Parameters:
x - first array
y - second array
Returns:
true if the values are both null or have same dimension and equal elements
Since:
2.2
• #### equals

public static boolean equals(double[] x,
double[] y)
Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by Precision.equals(double,double).
Parameters:
x - First array.
y - Second array.
Returns:
true if the values are both null or have same dimension and equal elements.
• #### equalsIncludingNaN

public static boolean equalsIncludingNaN(double[] x,
double[] y)
Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by this method.
Parameters:
x - First array.
y - Second array.
Returns:
true if the values are both null or have same dimension and equal elements.
Since:
2.2
• #### normalizeArray

public static double[] normalizeArray(double[] values,
double normalizedSum)
throws MathIllegalArgumentException,
MathArithmeticException
Normalizes an array to make it sum to a specified value. Returns the result of the transformation
    x |-> x * normalizedSum / sum

applied to each non-NaN element x of the input array, where sum is the sum of the non-NaN entries in the input array.

Throws IllegalArgumentException if normalizedSum is infinite or NaN and ArithmeticException if the input array contains any infinite elements or sums to 0.

Ignores (i.e., copies unchanged to the output array) NaNs in the input array.

Parameters:
values - Input array to be normalized
normalizedSum - Target sum for the normalized array
Returns:
the normalized array.
Throws:
MathArithmeticException - if the input array contains infinite elements or sums to zero.
MathIllegalArgumentException - if the target sum is infinite or NaN.
Since:
2.1
• #### buildArray

public static <T> T[] buildArray(Field<T> field,
int length)
Build an array of elements.

Arrays are filled with field.getZero()

Type Parameters:
T - the type of the field elements
Parameters:
field - field to which array elements belong
length - of the array
Returns:
a new array
Since:
3.2
• #### buildArray

public static <T> T[][] buildArray(Field<T> field,
int rows,
int columns)
Build a double dimension array of elements.

Arrays are filled with field.getZero()

Type Parameters:
T - the type of the field elements
Parameters:
field - field to which array elements belong
rows - number of rows in the array
columns - number of columns (may be negative to build partial arrays in the same way new Field[rows][] works)
Returns:
a new array
Since:
3.2
• #### convolve

public static double[] convolve(double[] x,
double[] h)
throws NullArgumentException,
NoDataException
Calculates the convolution between two sequences.

The solution is obtained via straightforward computation of the convolution sum (and not via FFT). Whenever the computation needs an element that would be located at an index outside the input arrays, the value is assumed to be zero.

Parameters:
x - First sequence. Typically, this sequence will represent an input signal to a system.
h - Second sequence. Typically, this sequence will represent the impulse response of the system.
Returns:
the convolution of x and h. This array's length will be x.length + h.length - 1.
Throws:
NullArgumentException - if either x or h is null.
NoDataException - if either x or h is empty.
Since:
3.3
• #### natural

public static int[] natural(int n)
Returns an array representing the natural number n.
Parameters:
n - Natural number.
Returns:
an array whose entries are the numbers 0, 1, ..., n-1. If n == 0, the returned array is empty.
• #### sequence

public static int[] sequence(int size,
int start,
int stride)
Returns an array of size integers starting at start, skipping stride numbers.
Parameters:
size - Natural number.
start - Natural number.
stride - Natural number.
Returns:
an array whose entries are the numbers start, start + stride, ..., start + (size - 1) * stride. If size == 0, the returned array is empty.
Since:
3.4
• #### verifyValues

public static boolean verifyValues(double[] values,
int begin,
int length)
throws MathIllegalArgumentException
This method is used to verify that the input parameters designate a subarray of positive length.
• returns true iff the parameters designate a subarray of positive length
• throws MathIllegalArgumentException if the array is null or or the indices are invalid
• returns false if the array is non-null, but length is 0.
Parameters:
values - the input array
begin - index of the first array element to include
length - the number of elements to include
Returns:
true if the parameters are valid and designate a subarray of positive length
Throws:
MathIllegalArgumentException - if the indices are invalid or the array is null
Since:
3.3
• #### verifyValues

public static boolean verifyValues(double[] values,
int begin,
int length,
boolean allowEmpty)
throws MathIllegalArgumentException
This method is used to verify that the input parameters designate a subarray of positive length.
• returns true iff the parameters designate a subarray of non-negative length
• throws IllegalArgumentException if the array is null or or the indices are invalid
• returns false if the array is non-null, but length is 0 unless allowEmpty is true
Parameters:
values - the input array
begin - index of the first array element to include
length - the number of elements to include
allowEmpty - if true then zero length arrays are allowed
Returns:
true if the parameters are valid
Throws:
MathIllegalArgumentException - if the indices are invalid or the array is null
Since:
3.3
• #### verifyValues

public static boolean verifyValues(double[] values,
double[] weights,
int begin,
int length)
throws MathIllegalArgumentException
This method is used to verify that the begin and length parameters designate a subarray of positive length and the weights are all non-negative, non-NaN, finite, and not all zero.
• returns true iff the parameters designate a subarray of positive length and the weights array contains legitimate values.
• throws IllegalArgumentException if any of the following are true:
• the values array is null
• the weights array is null
• the weights array does not have the same length as the values array
• the weights array contains one or more infinite values
• the weights array contains one or more NaN values
• the weights array contains negative values
• the start and length arguments do not determine a valid array
• returns false if the array is non-null, but length is 0.
Parameters:
values - the input array
weights - the weights array
begin - index of the first array element to include
length - the number of elements to include
Returns:
true if the parameters are valid and designate a subarray of positive length
Throws:
MathIllegalArgumentException - if the indices are invalid or the array is null
Since:
3.3
• #### verifyValues

public static boolean verifyValues(double[] values,
double[] weights,
int begin,
int length,
boolean allowEmpty)
throws MathIllegalArgumentException
This method is used to verify that the begin and length parameters designate a subarray of positive length and the weights are all non-negative, non-NaN, finite, and not all zero.
• returns true iff the parameters designate a subarray of non-negative length and the weights array contains legitimate values.
• throws MathIllegalArgumentException if any of the following are true:
• the values array is null
• the weights array is null
• the weights array does not have the same length as the values array
• the weights array contains one or more infinite values
• the weights array contains one or more NaN values
• the weights array contains negative values
• the start and length arguments do not determine a valid array
• returns false if the array is non-null, but length is 0 unless allowEmpty is true.
Parameters:
values - the input array.
weights - the weights array.
begin - index of the first array element to include.
length - the number of elements to include.
allowEmpty - if true than allow zero length arrays to pass.
Returns:
true if the parameters are valid.
Throws:
NullArgumentException - if either of the arrays are null
MathIllegalArgumentException - if the array indices are not valid, the weights array contains NaN, infinite or negative elements, or there are no positive weights.
Since:
3.3
• #### concatenate

public static double[] concatenate(double[]... x)
Concatenates a sequence of arrays. The return array consists of the entries of the input arrays concatenated in the order they appear in the argument list. Null arrays cause NullPointerExceptions; zero length arrays are allowed (contributing nothing to the output array).
Parameters:
x - list of double[] arrays to concatenate
Returns:
a new array consisting of the entries of the argument arrays
Throws:
NullPointerException - if any of the arrays are null
Since:
3.6
• #### unique

public static double[] unique(double[] data)
Returns an array consisting of the unique values in data. The return array is sorted in descending order. Empty arrays are allowed, but null arrays result in NullPointerException. Infinities are allowed. NaN values are allowed with maximum sort order - i.e., if there are NaN values in data, Double.NaN will be the first element of the output array, even if the array also contains Double.POSITIVE_INFINITY.
Parameters:
data - array to scan
Returns:
descending list of values included in the input array
Throws:
NullPointerException - if data is null
Since:
3.6