Package nom.tam.util

Class ArrayFuncs

java.lang.Object
nom.tam.util.ArrayFuncs
public final class ArrayFuncs extends Object
(for internal use) Varioys static functions for handling arrays. Generally these routines attempt to complete without throwing errors by ignoring data they cannot understand.

  • Method Details

    • getReversed

      public static int[] getReversed(int... index)
      Retuens a copy of the input array with the order of elements reversed.
      Parameters:
      index - the input array
      Returns:
      a copy of the input array in reversed order

    • copy

      public static void copy(Object src, int srcPos, Object dest, int destPos, int length, int step)
      Perform an array copy with an API similar to System.arraycopy(), specifying the number of values to jump to the next read.
      Parameters:
      src - The source array.
      srcPos - Starting position in the source array.
      dest - The destination array.
      destPos - Starting position in the destination data.
      length - The number of array elements to be read.
      step - The number of jumps to the next read.
      Since:
      1.18

    • arrayDescription

      public static String arrayDescription(Object o)
      Parameters:
      o - The array to be described.
      Returns:
      a description of an array (presumed rectangular).

    • computeLSize

      @Deprecated public static long computeLSize(Object o)
      Deprecated.
      Use FitsEncoder.computeSize(Object) instead.
      Parameters:
      o - the object
      Returns:
      the number of bytes in the FITS binary representation of the object or 0 if the object has no FITS representation. (Also elements not known to FITS will count as 0 sized).

    • computeSize

      @Deprecated public static int computeSize(Object o)
      Deprecated.
      Use FitsEncoder.computeSize(Object) instead.
      Parameters:
      o - the object
      Returns:
      the number of bytes in the FITS binary representation of the object or 0 if the object has no FITS representation. (Also elements not known to FITS will count as 0 sized).

    • convertArray

      public static Object convertArray(Object array, Class<?> newType)
      Converts a numerical array to a specified element type. This method supports conversions only among the primitive numeric types, and ComplexValue types (as of version 1.20). When converting primitive arrays to complex values, the trailing dimension must be 2, corresponding to the real and imaginary components of the complex values stored.
      Parameters:
      array - a numerical array of one or more dimensions
      newType - the desired output type. This should be one of the class descriptors for primitive numeric data, e.g., double.class, or else a ComplexValue type (also supported as of 1.20).
      Returns:
      a new array with the requested element type, which may also be composed of ComplexValue types as of version 1.20.
      See Also:

    • convertArray

      public static Object convertArray(Object array, Class<?> newType, boolean reuse)
      Converts a numerical array to a specified element type, returning the original if type conversion is not needed. This method supports conversions only among the primitive numeric types originally. Support for ComplexValue types was added as of version 1.20. When converting primitive arrays to complex values, the trailing dimension must be 2, corresponding to the real and imaginary components of the complex values stored.
      Parameters:
      array - a numerical array of one or more dimensions
      newType - the desired output type. This should be one of the class descriptors for primitive numeric data, e.g., double.class r else a ComplexValue type (also supported as of 1.20).
      reuse - If the original (rather than a copy) should be returned when possible for the same type.
      Returns:
      a new array with the requested element type, or possibly the original array if it readily matches the type and reuse is enabled.
      See Also:

    • copyArray

      @Deprecated public static void copyArray(Object original, Object copy) throws IllegalArgumentException
      Deprecated.
      (for internal use)
      Copy one array into another. This function copies the contents of one array into a previously allocated array. The arrays must agree in type and size.
      Parameters:
      original - The array to be copied.
      copy - The array to be copied into. This array must already be fully allocated.
      Throws:
      IllegalArgumentException - if the two arrays do not match in type or size.

    • copyInto

      public static void copyInto(Object array, Object mimic)
      Copy an array into an array of a different type. The dimensions and dimensionalities of the two arrays should be the same.
      Parameters:
      array - The original array.
      mimic - The array mimicking the original.

    • curl

      public static Object curl(Object input, int... dimens) throws IllegalStateException
      Curl an input array up into a multi-dimensional array.
      Parameters:
      input - The one dimensional array to be curled.
      dimens - The desired dimensions
      Returns:
      The curled array.
      Throws:
      IllegalStateException - if the size of the input does not match the specified dimensions.

    • deepClone

      public static Object deepClone(Object o)
      Returns a deep clone of an array (in one or more dimensions) or a standard clone of a scalar. The object may comprise arrays of any primitive type or any Object type which implements Cloneable. However, if the Object is some kind of collection, such as a List, then only a shallow copy of that object is made. I.e., deep refers only to arrays.
      Parameters:
      o - The object (usually an array) to be copied.
      Returns:
      a new object, with a copy of the original.

    • flatten

      public static Object flatten(Object input)
      Given an array of arbitrary dimensionality .
      Parameters:
      input - The input array.
      Returns:
      the array flattened into a single dimension.

    • genericClone

      public static Object genericClone(Object o)
      Clone an Object if possible. This method returns an Object which is a clone of the input object. It checks if the method implements the Cloneable interface and then uses reflection to invoke the clone method. This can't be done directly since as far as the compiler is concerned the clone method for Object is protected and someone could implement Cloneable but leave the clone method protected. The cloning can fail in a variety of ways which are trapped so that it returns null instead. This method will generally create a shallow clone. If you wish a deep copy of an array the method deepClone should be used.
      Parameters:
      o - The object to be cloned.
      Returns:
      the clone

    • getBaseArray

      public static Object getBaseArray(Object o)
      This routine returns the base array of a multi-dimensional array. I.e., a one-d array of whatever the array is composed of. Note that arrays are not guaranteed to be rectangular, so this returns o[0][0]....
      Parameters:
      o - the multi-dimensional array
      Returns:
      base array of a multi-dimensional array.

    • getBaseClass

      public static Class<?> getBaseClass(Object o)
      This routine returns the base class of an object. This is just the class of the object for non-arrays.
      Parameters:
      o - array to get the base class from
      Returns:
      the base class of an array

    • getBaseLength

      public static int getBaseLength(Object o)
      This routine returns the size of the base element of an array.
      Parameters:
      o - The array object whose base length is desired.
      Returns:
      the size of the object in bytes, 0 if null, or -1 if not a primitive array.

    • getDimensions

      public static int[] getDimensions(Object o)
      Find the dimensions of an object. This method returns an integer array with the dimensions of the object o which should usually be an array. It returns an array of dimension 0 for scalar objects and it returns -1 for dimension which have not been allocated, e.g., int[][][] x = new int[100][][]; should return [100,-1,-1].
      Parameters:
      o - The object to get the dimensions of.
      Returns:
      the dimensions of an object

    • mimicArray

      public static Object mimicArray(Object array, Class<?> newType)
      Create an array of a type given by new type with the dimensionality given in array.
      Parameters:
      array - A possibly multidimensional array to be converted.
      newType - The desired output type. This should be one of the class descriptors for primitive numeric data, e.g., double.type.
      Returns:
      the new array with same dimensions

    • isEmpty

      public static boolean isEmpty(Object o)
      Convenience method to check a generic Array object.
      Parameters:
      o - The Array to check.
      Returns:
      True if it's empty, False otherwise.
      Since:
      1.18

    • nElements

      @Deprecated public static int nElements(Object o)
      Deprecated.
      May silently underestimate size if number is > 2 G.
      Parameters:
      o - the array to count the elements
      Returns:
      Count the number of elements in an array.

    • newInstance

      public static Object newInstance(Class<?> cl, int... dims)
      Allocate an array dynamically. The Array.newInstance method does not throw an error and silently returns a null.throws an OutOfMemoryError if insufficient space is available.
      Parameters:
      cl - The class of the array.
      dims - The dimensions of the array.
      Returns:
      The allocated array.

    • nLElements

      public static long nLElements(Object o)
      Deprecated.
      Use the more aptly named countElements(Object) instead.
      Parameters:
      o - the array to count elements in
      Returns:
      Count the number of elements in an array.

    • countElements

      public static long countElements(Object o)
      Parameters:
      o - the array to count elements in
      Returns:
      Count the number of elements in an array.
      Since:
      1.18

    • reverseIndices

      public static int[] reverseIndices(int... indices)
      Reverse an integer array. This can be especially useful when dealing with an array of indices in FITS order that you wish to have in Java order.
      Parameters:
      indices - the array to reverse
      Returns:
      the reversed array.

    • checkRegularArray

      public static int[] checkRegularArray(Object o, boolean allowNulls) throws NullPointerException, IllegalArgumentException, ClassCastException
      Checks that an array has a regular structure, with a consistent shape and element types, and returns the regular array size or else throws an exeption. Optionally, it will also throw an exception if any or all all elements are null.
      Parameters:
      o - An array object
      allowNulls - If we should tolerate null entries.
      Returns:
      the regular shape of the array with sizes along each array dimension.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the array contains mismatched elements in size, or contains null values.
      ClassCastException - if the array contain a heterogeneous collection of different element types.
      Since:
      1.18

    • complexToDecimals

      public static Object complexToDecimals(Object o, Class<?> decimalType)
      Converts complex value(s) count to float[2] or double[2] or arrays thereof, which maintain the shape of the original input array (if applicable).
      Parameters:
      o - one of more complex values
      decimalType - float.class or double.class (all other values default to as if double.class was used.
      Returns:
      an array of float[2] or double[2], or arrays thereof.
      Throws:
      IllegalArgumentException - if the argument is not suitable for conversion to complex values.
      Since:
      1.18
      See Also:

    • decimalsToComplex

      public static Object decimalsToComplex(Object array) throws IllegalArgumentException
      Converts real-valued arrays of even element count to a ComplexValue or arrays thereof. The size and shape is otherwise maintained, apart from coalescing pairs of real values into ComplexValue objects.
      Parameters:
      array - an array of float or double elements containing an even number of elements at the last dimension
      Returns:
      one of more complex values
      Throws:
      IllegalArgumentException - if the argument is not suitable for conversion to complex values.
      Since:
      1.18
      See Also:

    • decimalsToComplex

      public static Object decimalsToComplex(Object re, Object im)
      Converts separate but matched real valued arrays, containing the real an imaginary parts respectively, to ComplexValue or arrays thereof. The size and shape of the matching input arrays is otherwise maintained, apart from coalescing pairs of real values into ComplexValue objects.
      Parameters:
      re - an array of float or double elements containing the real parts of the complex values.
      im - a matching array of the same type and shape as the real parts which contains the imaginary parts of the complex values.
      Returns:
      one of more complex values
      Throws:
      IllegalArgumentException - if the argument is not suitable for conversion to complex values.
      Since:
      1.20
      See Also:

    • convertArray

      public static Object convertArray(Object array, Class<?> newType, Quantizer quant) throws IllegalArgumentException
      Converts a numerical array to a specified element type, returning the original if type conversion is not needed. If the conversion is from decimal to integer type, or vice-versa, an optional quantization may be supplied to to perform the integer-decimal conversion of the elements. This method supports conversions only among the primitive numeric types and also ComplexValue type.
      Parameters:
      array - a numerical array of one or more dimensions
      newType - the desired output type. This should be one of the class descriptors for primitive numeric data, e.g., double.class, or else a ComplexValue or ComplexValue.Float.
      quant - optional qunatizer for integer-decimal conversion, or null to use simply rounding.
      Returns:
      a new array with the requested element type, or possibly the original array if it readily matches the type and reuse is enabled.
      Throws:
      IllegalArgumentException - if the input is not an array, or its elements are not a supported type or if the new type is not supported.
      Since:
      1.20
      See Also:

    • sample

      public static Object sample(Object orig, int step) throws IndexOutOfBoundsException
      Obtains a sparse sampling of from an array of one or more dimensions.
      Parameters:
      orig - the original array
      step - the sampling step size along all dimensions for a subsampled slice. A negative value indicates that the sampling should proceed in the reverse direction along every axis.
      Returns:
      the requested sampling from the original. The returned array may share data with the original, and so modifications to either may affect the other. The orginal object is returned if it is not an array.
      Throws:
      IndexOutOfBoundsException - if any of the indices for the requested slice are out of bounds for the original. That is if the original does not fully contain the requested slice. Or, if the from and size arguments have differing lengths.
      Since:
      1.20
      See Also:

    • sample

      public static Object sample(Object orig, int[] step) throws IndexOutOfBoundsException
      Obtains a sparse sampling of from an array of one or more dimensions.
      Parameters:
      orig - the original array
      step - the sampling step size along each dimension for a subsampled slice. Negative values indicate that the sampling should proceed in the reverse direction along the given axis.
      Returns:
      the requested sampling from the original. The returned array may share data with the original, and so modifications to either may affect the other. The orginal object is returned if it is not an array.
      Throws:
      IndexOutOfBoundsException - if any of the indices for the requested slice are out of bounds for the original. That is if the original does not fully contain the requested slice. Or, if the from and size arguments have differing lengths.
      Since:
      1.20
      See Also:

    • slice

      public static Object slice(Object orig, int[] from) throws IndexOutOfBoundsException
      Obtains a slice (subarray) from an array of one or more dimensions.
      Parameters:
      orig - the original array
      from - the starting indices for the slice in the original array. It should have at most as many elements as there are array dimensions, but it can also have fewer.
      Returns:
      the requested slice from the original. The returned array may share data with the original, and so modifications to either may affect the other. The orginal object is returned if it is not an array.
      Throws:
      IndexOutOfBoundsException - if any of the indices for the requested slice are out of bounds for the original. That is if the original does not fully contain the requested slice. Or, if the from and size arguments have differing lengths.
      Since:
      1.20
      See Also:

    • slice

      public static Object slice(Object orig, int[] from, int[] size) throws IndexOutOfBoundsException
      Obtains a slice (subarray) from an array of one or more dimensions.
      Parameters:
      orig - the original array
      from - the starting indices for the slice in the original array. It should have at most as many elements as there are array dimensions, but it can also have fewer.
      size - the size of the slice. Negative values can indicate moving backwards in the original array (but forward in the slice -- resulting in a flipped axis). A null size argument can be used to sample the full original. The slice will end at index from[k] + size[k] in dimension k in the original (not including the ending index). It should have the same number of elements as the from argument.
      Returns:
      the requested slice from the original. The returned array may share data with the original, and so modifications to either may affect the other. The orginal object is returned if it is not an array.
      Throws:
      IndexOutOfBoundsException - if any of the indices for the requested slice are out of bounds for the original. That is if the original does not fully contain the requested slice. Or, if the from and size arguments have differing lengths.
      Since:
      1.20
      See Also:

    • sample

      public static Object sample(Object orig, int[] from, int[] size, int[] step) throws IndexOutOfBoundsException
      Obtains a sparse sampling from an array of one or more dimensions.
      Parameters:
      orig - the original array
      from - the starting indices in the original array at which to start sampling. It should have at most as many elements as there are array dimensions, but it can also have fewer. A null argument can be used to sample from the start or end of the array (depending on the direction).
      size - the size of the sampled area in the original along each dimension. The signature of the values is irrelevant as the direction of sampling is determined by the step argument. Zero entries can be used to indicate that the full array should be sampled along the given dimension, while a null argument will sample the full array in all dimensions.
      step - the sampling step size along each dimension for a subsampled slice. Negative values indicate sampling the original in the reverse direction along the given dimension. 0 values are are automatically bumped to 1 (full sampling), and a null argument is understood to mean full sampling along all dimensions.
      Returns:
      the requested sampling from the original. The returned array may share data with the original, and so modifications to either may affect the other. The orginal object is returned if it is not an array.
      Throws:
      IndexOutOfBoundsException - if any of the indices for the requested slice are out of bounds for the original. That is if the original does not fully contain the requested slice. Or, if the from and size arguments have differing lengths.
      Since:
      1.20
      See Also: