Class ArrayMetaData

java.lang.Object
org.klojang.util.ArrayMetaData
public final class ArrayMetaData extends Object

Provides metadata about an array or array type and allows you to generate arrays with a different base type or dimensionality. The base type is the component type of the innermost array of an n-dimensional array. So for int[][][] that would be int. int[][] is the component type of int[][][]; int is its base type. In other words: the base type of an array always is a non-array type. (NB while component type is standard terminology, there is no commonly accepted term for the type of objects that ultimately occupy the slots in the array — in any dimension. Here we use the term base type. Element type would another reasonable option.)

Example usage: 


 ArrayMetaData metadata = ArrayMetaData.of(int[][].class);
 Integer[][][] cube = metadata.box().addDimension().newHyperCube(10);

  • Method Summary

    Modifier and Type
    Method
    Description
    ArrayMetaData
    addDimension()
    Returns an ArrayMetaData instance with one more dimension than this instance.
    ArrayMetaData
    box()
    Returns an ArrayMetaData instance for the boxed version of the base type.
    static int
    countDimensions(Class<?> clazz)
    Returns zero for non-array types, and the number of dimensions for array types.
    static int
    countDimensions(Object obj)
    Returns zero for non-array objects, and the number of dimensions for arrays.
    static String
    describe(Object array)
    Returns a description of the provided array.
    boolean
    equals(Object obj)
     
    static ArrayMetaData
    forArray(Object array)
    Returns an ArrayMetaData instance corresponding to the specified array object.
    Class<?>
    getArrayClass()
    Returns the Class object corresponding to this instance.
    String
    getArrayClassName()
    Returns the class name of the array type represented by this instance.
    Class<?>
    getBaseType()
    Returns the base type of the array represented by this instance.
    static Class<?>
    getBaseType(Class<?> arrayType)
    Returns the base type of the specified array type.
    static Class<?>
    getBaseType(Object array)
    Returns the base type of the specified array.
    int
    getDimensions()
    Returns the number of dimensions of the array represented by this instance.
    int
    hashCode()
     
    <T> T
    newArray(int length, int... lengths)
    Creates a new array with the specified length, using the base type and number of dimensions of this ArrayMetaData instance.
    <T> T
    newHyperCube(int length)
    Creates a "hyper cube" in which all arrays in all dimensions have the same length (as in new int[10][10][10]).
    static ArrayMetaData
    of(Class<?> arrayType)
    Returns a ArrayMetaData instance corresponding to the specified array type.
    static ArrayMetaData
    of(Class<?> type, int dimensions)
    Creates a new ArrayMetaData instance.
    ArrayMetaData
    removeDimension()
    Returns an ArrayMetaData instance with one dimension less than this instance.
    String
    toString()
    Returns the simple class name of the array type represented by this instance.
    ArrayMetaData
    unbox()
    Returns the ArrayMetaData for the unboxed version of the base type.
    ArrayMetaData
    withBaseType(Class<?> elementType)
    Returns an ArrayMetaData instance with the same number of dimensions as this instance, and with the specified base type.
    ArrayMetaData
    withDimensions(int dimensions)
    Returns an ArrayMetaData instance with the same base type as this instance, and with the specified number of dimensions.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • describe

      public static String describe(Object array)
      Returns a description of the provided array. It contains the base type's simple class name and the length of the outermost array. For example, for an array defined as new Double[4][12], this method would return "Double[4][]".
      Parameters:
      array - the array to describe
      Returns:
      a description of the array

    • getBaseType

      public static Class<?> getBaseType(Class<?> arrayType)
      Returns the base type of the specified array type. An IllegalArgumentException is thrown if the provided class is not an array type.
      Parameters:
      arrayType - the array type to inspect
      Returns:
      the base type of the specified array type

    • getBaseType

      public static Class<?> getBaseType(Object array)
      Returns the base type of the specified array. An IllegalArgumentException is thrown if the provided object is not an array.
      Parameters:
      array - the array to inspect
      Returns:
      the base type of the specified array

    • countDimensions

      public static int countDimensions(Class<?> clazz)
      Returns zero for non-array types, and the number of dimensions for array types.
      Parameters:
      clazz - the type for which to get the number of dimensions
      Returns:
      the dimensionality of the type.

    • countDimensions

      public static int countDimensions(Object obj)
      Returns zero for non-array objects, and the number of dimensions for arrays.
      Parameters:
      obj - the object for which to get the number of dimensions
      Returns:
      the dimensionality of the object.

    • forArray

      public static ArrayMetaData forArray(Object array)
      Returns an ArrayMetaData instance corresponding to the specified array object. An IllegalArgumentException is thrown if the provided object is not an array.
      Parameters:
      array - the array
      Returns:
      the ArrayMetaData instance

    • of

      public static ArrayMetaData of(Class<?> arrayType)
      Returns a ArrayMetaData instance corresponding to the specified array type. An IllegalArgumentException is thrown if the provided class object does not represent an array type.
      Parameters:
      arrayType - the array class
      Returns:
      the ArrayMetaData instance

    • of

      public static ArrayMetaData of(Class<?> type, int dimensions)
      Creates a new ArrayMetaData instance. The provided type may or may not be an array type. If it is an array type, its base type will become the base type of the ArrayMetaData instance and its dimension count will be added to the provided number of dimensions. If the provided type is not an array type, the type itself will become the base type of the ArrayMetaData instance. The specified number of dimensions may be zero or negative, as long as the sum of the dimensions remains positive: 
      
 var twoDimensional = float[][].class; // base type: float
 var threeDimensional = ArrayMetaData.of(twoDimensional, 1); // represents float[][][].class
 var oneDimensional = ArrayMetaData.of(twoDimensional, -1);  // represents float[].class
      Parameters:
      type - the type to inspect
      dimensions - the number of dimensions

    • getBaseType

      public Class<?> getBaseType()
      Returns the base type of the array represented by this instance.
      Returns:
      the base type of the array represented by this instance

    • getDimensions

      public int getDimensions()
      Returns the number of dimensions of the array represented by this instance.
      Returns:
      the number of dimensions of the array represented by this instance

    • getArrayClass

      public Class<?> getArrayClass()
      Returns the Class object corresponding to this instance. For example, if the base type of this instance is byte and the number of dimensions recorded by this instance is three, then this method will return byte[][][].class.
      Returns:
      a Class object

    • newArray

      public <T> T newArray(int length, int... lengths)

      Creates a new array with the specified length, using the base type and number of dimensions of this ArrayMetaData instance. For example, if the provided length is 10, the base type is short.class, and the number of dimensions is three, then calling this method amounts to calling new short[10][][]: 

      
 var expected = new short[10][][];
 ArrayMetaData metadata = ArrayMetaData.of(short.class, 3);
 var actual = metadata.newArray(10);
 assertArrayEquals(expected, actual);

      If this ArrayMetaData instance represents a multidimensional array, you may optionally specify the lengths of the arrays in the other dimensions (akin to calling new short[10][8][] or new short[10][8][15]).

      Type Parameters:
      T - the type of the array
      Parameters:
      length - the length of the array
      lengths - the lengths of the arrays in the other dimensions
      Returns:
      a new array

    • newHyperCube

      public <T> T newHyperCube(int length)
      Creates a "hyper cube" in which all arrays in all dimensions have the same length (as in new int[10][10][10]). Note that "hyper cube" is in fact a misnomer, because this method can also be used to create a two-dimensional array (new int[10][10), or even a one-dimensional array.
      Type Parameters:
      T - the type of the array
      Parameters:
      length - the array length in all dimensions
      Returns:
      a new array

    • withBaseType

      public ArrayMetaData withBaseType(Class<?> elementType)
      Returns an ArrayMetaData instance with the same number of dimensions as this instance, and with the specified base type.
      Parameters:
      elementType - the base type of the returned ArrayMetaData instance
      Returns:
      an ArrayMetaData instance with the same number of dimensions as this instance, and with the specified base type

    • withDimensions

      public ArrayMetaData withDimensions(int dimensions)
      Returns an ArrayMetaData instance with the same base type as this instance, and with the specified number of dimensions.
      Parameters:
      dimensions - the number of dimensions
      Returns:
      an ArrayMetaData instance with the same base type as this instance, and with the specified number of dimensions

    • addDimension

      public ArrayMetaData addDimension()
      Returns an ArrayMetaData instance with one more dimension than this instance.
      Returns:
      an ArrayMetaData instance with one more dimension than this instance

    • removeDimension

      public ArrayMetaData removeDimension()
      Returns an ArrayMetaData instance with one dimension less than this instance.
      Returns:
      an ArrayMetaData instance with one dimension less than this instance

    • box

      public ArrayMetaData box()
      Returns an ArrayMetaData instance for the boxed version of the base type. If the base type of this instance is not a primitive type, the instance itself is returned.
      Returns:
      an ArrayMetaData for the boxed version of the base type

    • unbox

      public ArrayMetaData unbox()
      Returns the ArrayMetaData for the unboxed version of the base type. If the base type of this instance is not a primitive wrapper type (like Double), the instance itself is returned.
      Returns:
      the ArrayMetaData for the unboxed version of the base type

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Returns the simple class name of the array type represented by this instance. The returned string is easier to understand than what you get from Class.getSimpleName(). For example the return value for int[][].class would be "int[][]".
      Overrides:
      toString in class Object
      Returns:
      the simple class name of the array type represented by this ArrayMetaData

    • getArrayClassName

      public String getArrayClassName()
      Returns the class name of the array type represented by this instance. The returned string is easier to understand than what you get from Class.getName(). For example, the return value for String[][].class would be "String[][]". For types outside the java.lang package, the fully-qualified class name is used (e.g. "java.io.File[][]").
      Returns:
      the class name of the array type represented by this ArrayMetaData