org.apache.commons.math3.util

## Class MathArrays

- java.lang.Object
- - org.apache.commons.math3.util.MathArrays

-     public class MathArrays
      extends Object

  Arrays utilities.
  Since:
    3.0
  Version:
    $Id$

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `MathArrays.OrderDirection` Specification of ordering direction.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 double[]` | `copyOf(double[] source)` Creates a copy of the `source` array.
    `static double[]` | `copyOf(double[] source, int len)` Creates a copy of the `source` array.
    `static int[]` | `copyOf(int[] source)` Creates a copy of the `source` array.
    `static int[]` | `copyOf(int[] source, int len)` Creates a copy of the `source` array.
    `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 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(Comparable[] val, MathArrays.OrderDirection dir, boolean strict)` Check that an array is monotonically increasing or decreasing.
    `static boolean` | `isMonotonic(double[] val, MathArrays.OrderDirection dir, boolean strict)` Check that an array is monotonically increasing or decreasing.
    `static double` | `linearCombination(double[] a, double[] b)` Compute a linear combination accurately.
    `static double` | `linearCombination(double a1, double b1, double a2, double b2)` Compute a linear combination accurately.
    `static double` | `linearCombination(double a1, double b1, double a2, double b2, double a3, double b3)` Compute a linear combination accurately.
    `static double` | `linearCombination(double a1, double b1, double a2, double b2, double a3, double b3, double a4, double b4)` Compute a linear combination accurately.
    `static double[]` | `normalizeArray(double[] values, double normalizedSum)` Normalizes an array to make it sum to a specified value.
    `static double` | `safeNorm(double[] v)` Returns the Cartesian norm (2-norm), handling both overflow and underflow.
    `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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### distance1

          public static double distance1(double[] p1,
                         double[] p2)

      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

    - #### distance1

          public static int distance1(int[] p1,
                      int[] p2)

      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

    - #### distance

          public static double distance(double[] p1,
                        double[] p2)

      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

    - #### distance

          public static double distance(int[] p1,
                        int[] p2)

      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

    - #### distanceInf

          public static double distanceInf(double[] p1,
                           double[] p2)

      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

    - #### distanceInf

          public static int distanceInf(int[] p1,
                        int[] p2)

      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

    - #### isMonotonic

          public static boolean isMonotonic(Comparable[] 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.

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

    - #### checkOrder

          public static boolean checkOrder(double[] val,
                           MathArrays.OrderDirection dir,
                           boolean strict,
                           boolean abort)

      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)

      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)

      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

    - #### safeNorm

          public static double safeNorm(double[] v)

      Returns the Cartesian norm (2-norm), handling both overflow and underflow. Translation of the minpack enorm subroutine. The redistribution policy for MINPACK is available here, for convenience, it is reproduced below.

      Minpack Copyright Notice (1999) University of Chicago. All rights reserved
      Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: `This product includes software developed by the University of Chicago, as Operator of Argonne National Laboratory.` Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear. WARRANTY DISCLAIMER. THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE COPYRIGHT HOLDER, THE UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, AND THEIR EMPLOYEES: (1) DISCLAIM ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, (2) DO NOT ASSUME ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF THE SOFTWARE, (3) DO NOT REPRESENT THAT USE OF THE SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS, (4) DO NOT WARRANT THAT THE SOFTWARE WILL FUNCTION UNINTERRUPTED, THAT IT IS ERROR-FREE OR THAT ANY ERRORS WILL BE CORRECTED. LIMITATION OF LIABILITY. IN NO EVENT WILL THE COPYRIGHT HOLDER, THE UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, OR THEIR EMPLOYEES: BE LIABLE FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE, INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA, FOR ANY REASON WHATSOEVER, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE, EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGES.

      Parameters:
        `v` - Vector of doubles.
      Returns:
        the 2-norm of the vector.
      Since:
        2.2

    - #### sortInPlace

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

      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

    - #### copyOf

          public static int[] copyOf(int[] source)

      Creates a copy of the `source` array.
      Parameters:
        `source` - Array to be copied.
      Returns:
        the copied array.

    - #### copyOf

          public static double[] copyOf(double[] source)

      Creates a copy of the `source` array.
      Parameters:
        `source` - Array to be copied.
      Returns:
        the copied array.

    - #### copyOf

          public static int[] copyOf(int[] source,
                     int len)

      Creates a copy of the `source` array.
      Parameters:
        `source` - Array to be copied.
        `len` - Number of entries to copy. If smaller then the source length, the copy will be truncated, if larger it will padded with zeroes.
      Returns:
        the copied array.

    - #### copyOf

          public static double[] copyOf(double[] source,
                        int len)

      Creates a copy of the `source` array.
      Parameters:
        `source` - Array to be copied.
        `len` - Number of entries to copy. If smaller then the source length, the copy will be truncated, if larger it will padded with zeroes.
      Returns:
        the copied array.

    - #### linearCombination

          public static double linearCombination(double[] a,
                                 double[] b)

      Compute a linear combination accurately. This method computes the sum of the products `ai bi` to high accuracy. It does so by using specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects.
      It is based on the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.
      Parameters:
        `a` - Factors.
        `b` - Factors.
      Returns:
        `Σi ai bi`.

    - #### linearCombination

          public static double linearCombination(double a1,
                                 double b1,
                                 double a2,
                                 double b2)

      Compute a linear combination accurately.

      This method computes a1×b1 + a2×b2 to high accuracy. It does so by using specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects. It is based on the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.

      Parameters:
        `a1` - first factor of the first term
        `b1` - second factor of the first term
        `a2` - first factor of the second term
        `b2` - second factor of the second term
      Returns:
        a1×b1 + a2×b2
      See Also:
        `linearCombination(double, double, double, double, double, double)`, `linearCombination(double, double, double, double, double, double, double, double)`

    - #### linearCombination

          public static double linearCombination(double a1,
                                 double b1,
                                 double a2,
                                 double b2,
                                 double a3,
                                 double b3)

      Compute a linear combination accurately.

      This method computes a1×b1 + a2×b2 + a3×b3 to high accuracy. It does so by using specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects. It is based on the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.

      Parameters:
        `a1` - first factor of the first term
        `b1` - second factor of the first term
        `a2` - first factor of the second term
        `b2` - second factor of the second term
        `a3` - first factor of the third term
        `b3` - second factor of the third term
      Returns:
        a1×b1 + a2×b2 + a3×b3
      See Also:
        `linearCombination(double, double, double, double)`, `linearCombination(double, double, double, double, double, double, double, double)`

    - #### linearCombination

          public static double linearCombination(double a1,
                                 double b1,
                                 double a2,
                                 double b2,
                                 double a3,
                                 double b3,
                                 double a4,
                                 double b4)

      Compute a linear combination accurately.

      This method computes a1×b1 + a2×b2 + a3×b3 + a4×b4 to high accuracy. It does so by using specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects. It is based on the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.

      Parameters:
        `a1` - first factor of the first term
        `b1` - second factor of the first term
        `a2` - first factor of the second term
        `b2` - second factor of the second term
        `a3` - first factor of the third term
        `b3` - second factor of the third term
        `a4` - first factor of the third term
        `b4` - second factor of the third term
      Returns:
        a1×b1 + a2×b2 + a3×b3 + a4×b4
      See Also:
        `linearCombination(double, double, double, double)`, `linearCombination(double, double, double, double, double, double)`

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

      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

Copyright © 2003-2012 The Apache Software Foundation. All Rights Reserved.