java.lang.reflect

Class Array

public final class Array extends Object

Array holds static helper functions that allow you to create and manipulate arrays by reflection. Operations know how to perform widening conversions, but throw {@link IllegalArgumentException} if you attempt a narrowing conversion. Also, when accessing primitive arrays, this class performs object wrapping and unwrapping as necessary.

Note: This class returns and accepts types as Classes, even primitive types; there are Class types defined that represent each different primitive type. They are java.lang.Boolean.TYPE, java.lang.Byte.TYPE,, also available as boolean.class, byte.class, etc. These are not to be confused with the classes java.lang.Boolean, java.lang.Byte, etc., which are real classes. Note also that the shorthand Object[].class is a convenient way to get array Classes.

Performance note: This class performs best when it does not have to convert primitive types. The further along the chain it has to convert, the worse performance will be. You're best off using the array as whatever type it already is, and then converting the result. You will do even worse if you do this and use the generic set() function.

Since: 1.1

See Also: TYPE TYPE TYPE TYPE TYPE TYPE TYPE TYPE

UNKNOWN: updated to 1.4

Method Summary
static Objectget(Object array, int index)
Gets an element of an array.
static booleangetBoolean(Object array, int index)
Gets an element of a boolean array.
static bytegetByte(Object array, int index)
Gets an element of a byte array.
static chargetChar(Object array, int index)
Gets an element of a char array.
static doublegetDouble(Object array, int index)
Gets an element of a double array.
static floatgetFloat(Object array, int index)
Gets an element of a float array.
static intgetInt(Object array, int index)
Gets an element of an int array.
static intgetLength(Object array)
Gets the array length.
static longgetLong(Object array, int index)
Gets an element of a long array.
static shortgetShort(Object array, int index)
Gets an element of a short array.
static ObjectnewInstance(Class<?> componentType, int length)
Creates a new single-dimensioned array.
static ObjectnewInstance(Class<?> componentType, int[] dimensions)
Creates a new multi-dimensioned array.
static voidset(Object array, int index, Object value)
Sets an element of an array.
static voidsetBoolean(Object array, int index, boolean value)
Sets an element of a boolean array.
static voidsetByte(Object array, int index, byte value)
Sets an element of a byte array.
static voidsetChar(Object array, int index, char value)
Sets an element of a char array.
static voidsetDouble(Object array, int index, double value)
Sets an element of a double array.
static voidsetFloat(Object array, int index, float value)
Sets an element of a float array.
static voidsetInt(Object array, int index, int value)
Sets an element of an int array.
static voidsetLong(Object array, int index, long value)
Sets an element of a long array.
static voidsetShort(Object array, int index, short value)
Sets an element of a short array.

Method Detail

get

public static Object get(Object array, int index)
Gets an element of an array. Primitive elements will be wrapped in the corresponding class type.

Parameters: array the array to access index the array index to access

Returns: the element at array[index]

Throws: IllegalArgumentException if array is not an array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array Array Array Array Array Array Array Array

getBoolean

public static boolean getBoolean(Object array, int index)
Gets an element of a boolean array.

Parameters: array the array to access index the array index to access

Returns: the boolean element at array[index]

Throws: IllegalArgumentException if array is not a boolean array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

getByte

public static byte getByte(Object array, int index)
Gets an element of a byte array.

Parameters: array the array to access index the array index to access

Returns: the byte element at array[index]

Throws: IllegalArgumentException if array is not a byte array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

getChar

public static char getChar(Object array, int index)
Gets an element of a char array.

Parameters: array the array to access index the array index to access

Returns: the char element at array[index]

Throws: IllegalArgumentException if array is not a char array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

getDouble

public static double getDouble(Object array, int index)
Gets an element of a double array.

Parameters: array the array to access index the array index to access

Returns: the double element at array[index]

Throws: IllegalArgumentException if array is not a byte, char, short, int, long, float, or double array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

getFloat

public static float getFloat(Object array, int index)
Gets an element of a float array.

Parameters: array the array to access index the array index to access

Returns: the float element at array[index]

Throws: IllegalArgumentException if array is not a byte, char, short, int, long, or float array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

getInt

public static int getInt(Object array, int index)
Gets an element of an int array.

Parameters: array the array to access index the array index to access

Returns: the int element at array[index]

Throws: IllegalArgumentException if array is not a byte, char, short, or int array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

getLength

public static int getLength(Object array)
Gets the array length.

Parameters: array the array

Returns: the length of the array

Throws: IllegalArgumentException if array is not an array NullPointerException if array is null

getLong

public static long getLong(Object array, int index)
Gets an element of a long array.

Parameters: array the array to access index the array index to access

Returns: the long element at array[index]

Throws: IllegalArgumentException if array is not a byte, char, short, int, or long array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

getShort

public static short getShort(Object array, int index)
Gets an element of a short array.

Parameters: array the array to access index the array index to access

Returns: the short element at array[index]

Throws: IllegalArgumentException if array is not a byte or char array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

newInstance

public static Object newInstance(Class<?> componentType, int length)
Creates a new single-dimensioned array.

Parameters: componentType the type of the array to create length the length of the array to create

Returns: the created array, cast to an Object

Throws: NullPointerException if componentType is null IllegalArgumentException if componentType is Void.TYPE NegativeArraySizeException when length is less than 0 OutOfMemoryError if memory allocation fails

newInstance

public static Object newInstance(Class<?> componentType, int[] dimensions)
Creates a new multi-dimensioned array. The new array has the same component type as the argument class, and the number of dimensions in the new array is the sum of the dimensions of the argument class and the length of the argument dimensions. Virtual Machine limitations forbid too many dimensions (usually 255 is the maximum); but even 50 dimensions of 2 elements in each dimension would exceed your memory long beforehand!

Parameters: componentType the type of the array to create. dimensions the dimensions of the array to create. Each element in dimensions makes another dimension of the new array. Thus, Array.newInstance(java.lang.Boolean, new int[]{1,2,3}) is the same as new java.lang.Boolean[1][2][3]

Returns: the created array, cast to an Object

Throws: NullPointerException if componentType or dimension is null IllegalArgumentException if the the size of dimensions is 0 or exceeds the maximum number of array dimensions in the VM; or if componentType is Void.TYPE NegativeArraySizeException when any of the dimensions is less than 0 OutOfMemoryError if memory allocation fails

set

public static void set(Object array, int index, Object value)
Sets an element of an array. If the array is primitive, then the new value is unwrapped and widened.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not an array, or the array is primitive and unwrapping value fails, or the value is not assignable to the array component type NullPointerException if array is null, or if array is primitive and value is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array Array Array Array Array Array Array Array

setBoolean

public static void setBoolean(Object array, int index, boolean value)
Sets an element of a boolean array.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not a boolean array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

setByte

public static void setByte(Object array, int index, byte value)
Sets an element of a byte array.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not a byte, short, int, long, float, or double array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

setChar

public static void setChar(Object array, int index, char value)
Sets an element of a char array.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not a char, int, long, float, or double array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

setDouble

public static void setDouble(Object array, int index, double value)
Sets an element of a double array.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not a double array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

setFloat

public static void setFloat(Object array, int index, float value)
Sets an element of a float array.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not a float or double array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

setInt

public static void setInt(Object array, int index, int value)
Sets an element of an int array.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not an int, long, float, or double array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

setLong

public static void setLong(Object array, int index, long value)
Sets an element of a long array.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not a long, float, or double array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array

setShort

public static void setShort(Object array, int index, short value)
Sets an element of a short array.

Parameters: array the array to set a value of index the array index to set the value to value the value to set

Throws: IllegalArgumentException if array is not a short, int, long, float, or double array NullPointerException if array is null ArrayIndexOutOfBoundsException if index is out of bounds

See Also: Array