/* * Copyright (C) 2014 The Android Open Source Project * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.lang.reflect; /** * The {@code Array} class provides static methods to dynamically create and * access Java arrays. * *

{@code Array} permits widening conversions to occur during a get or set * operation, but throws an {@code IllegalArgumentException} if a narrowing * conversion would occur. * * @author Nakul Saraiya */ public final class Array { /** * Constructor. Class Array is not instantiable. */ private Array() {} /** * Creates a new array with the specified component type and * length. * Invoking this method is equivalent to creating an array * as follows: *

*
     * int[] x = {length};
     * Array.newInstance(componentType, x);
     * 
*
* * @param componentType the {@code Class} object representing the * component type of the new array * @param length the length of the new array * @return the new array * @exception NullPointerException if the specified * {@code componentType} parameter is null * @exception IllegalArgumentException if componentType is {@link Void#TYPE} * @exception NegativeArraySizeException if the specified {@code length} * is negative */ public static Object newInstance(Class componentType, int length) throws NegativeArraySizeException { return newArray(componentType, length); } /** * Creates a new array * with the specified component type and dimensions. * If {@code componentType} * represents a non-array class or interface, the new array * has {@code dimensions.length} dimensions and * {@code componentType} as its component type. If * {@code componentType} represents an array class, the * number of dimensions of the new array is equal to the sum * of {@code dimensions.length} and the number of * dimensions of {@code componentType}. In this case, the * component type of the new array is the component type of * {@code componentType}. * *

The number of dimensions of the new array must not * exceed the number of array dimensions supported by the * implementation (typically 255). * * @param componentType the {@code Class} object representing the component * type of the new array * @param dimensions an array of {@code int} representing the dimensions of * the new array * @return the new array * @exception NullPointerException if the specified * {@code componentType} argument is null * @exception IllegalArgumentException if the specified {@code dimensions} * argument is a zero-dimensional array, or if the number of * requested dimensions exceeds the limit on the number of array dimensions * supported by the implementation (typically 255), or if componentType * is {@link Void#TYPE}. * @exception NegativeArraySizeException if any of the components in * the specified {@code dimensions} argument is negative. */ public static Object newInstance(Class componentType, int... dimensions) throws IllegalArgumentException, NegativeArraySizeException { if (dimensions.length <= 0 || dimensions.length > 255) { throw new IllegalArgumentException("Bad number of dimensions: " + dimensions.length); } if (componentType == void.class) { throw new IllegalArgumentException("Can't allocate an array of void"); } if (componentType == null) { throw new NullPointerException("componentType == null"); } return createMultiArray(componentType, dimensions); } /** * Returns the length of the specified array object, as an {@code int}. * * @param array the array * @return the length of the array * @exception IllegalArgumentException if the object argument is not * an array */ public static int getLength(Object array) { if (array instanceof Object[]) { return ((Object[]) array).length; } else if (array instanceof boolean[]) { return ((boolean[]) array).length; } else if (array instanceof byte[]) { return ((byte[]) array).length; } else if (array instanceof char[]) { return ((char[]) array).length; } else if (array instanceof double[]) { return ((double[]) array).length; } else if (array instanceof float[]) { return ((float[]) array).length; } else if (array instanceof int[]) { return ((int[]) array).length; } else if (array instanceof long[]) { return ((long[]) array).length; } else if (array instanceof short[]) { return ((short[]) array).length; } throw badArray(array); } /** * Returns the value of the indexed component in the specified * array object. The value is automatically wrapped in an object * if it has a primitive type. * * @param array the array * @param index the index * @return the (possibly wrapped) value of the indexed component in * the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array */ public static Object get(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof Object[]) { return ((Object[]) array)[index]; } if (array instanceof boolean[]) { return ((boolean[]) array)[index] ? Boolean.TRUE : Boolean.FALSE; } if (array instanceof byte[]) { return Byte.valueOf(((byte[]) array)[index]); } if (array instanceof char[]) { return Character.valueOf(((char[]) array)[index]); } if (array instanceof short[]) { return Short.valueOf(((short[]) array)[index]); } if (array instanceof int[]) { return Integer.valueOf(((int[]) array)[index]); } if (array instanceof long[]) { return Long.valueOf(((long[]) array)[index]); } if (array instanceof float[]) { return new Float(((float[]) array)[index]); } if (array instanceof double[]) { return new Double(((double[]) array)[index]); } if (array == null) { throw new NullPointerException("array == null"); } throw notAnArray(array); } /** * Returns the value of the indexed component in the specified * array object, as a {@code boolean}. * * @param array the array * @param index the index * @return the value of the indexed component in the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array, or if the indexed element cannot be converted to the * return type by an identity or widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array * @see Array#get */ public static boolean getBoolean(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof boolean[]) { return ((boolean[]) array)[index]; } throw badArray(array); } /** * Returns the value of the indexed component in the specified * array object, as a {@code byte}. * * @param array the array * @param index the index * @return the value of the indexed component in the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array, or if the indexed element cannot be converted to the * return type by an identity or widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array * @see Array#get */ public static byte getByte(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof byte[]) { return ((byte[]) array)[index]; } throw badArray(array); } /** * Returns the value of the indexed component in the specified * array object, as a {@code char}. * * @param array the array * @param index the index * @return the value of the indexed component in the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array, or if the indexed element cannot be converted to the * return type by an identity or widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array * @see Array#get */ public static char getChar(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof char[]) { return ((char[]) array)[index]; } throw badArray(array); } /** * Returns the value of the indexed component in the specified * array object, as a {@code short}. * * @param array the array * @param index the index * @return the value of the indexed component in the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array, or if the indexed element cannot be converted to the * return type by an identity or widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array * @see Array#get */ public static short getShort(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof short[]) { return ((short[]) array)[index]; } else if (array instanceof byte[]) { return ((byte[]) array)[index]; } throw badArray(array); } /** * Returns the value of the indexed component in the specified * array object, as an {@code int}. * * @param array the array * @param index the index * @return the value of the indexed component in the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array, or if the indexed element cannot be converted to the * return type by an identity or widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array * @see Array#get */ public static int getInt(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof int[]) { return ((int[]) array)[index]; } else if (array instanceof byte[]) { return ((byte[]) array)[index]; } else if (array instanceof char[]) { return ((char[]) array)[index]; } else if (array instanceof short[]) { return ((short[]) array)[index]; } throw badArray(array); } /** * Returns the value of the indexed component in the specified * array object, as a {@code long}. * * @param array the array * @param index the index * @return the value of the indexed component in the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array, or if the indexed element cannot be converted to the * return type by an identity or widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array * @see Array#get */ public static long getLong(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof long[]) { return ((long[]) array)[index]; } else if (array instanceof byte[]) { return ((byte[]) array)[index]; } else if (array instanceof char[]) { return ((char[]) array)[index]; } else if (array instanceof int[]) { return ((int[]) array)[index]; } else if (array instanceof short[]) { return ((short[]) array)[index]; } throw badArray(array); } /** * Returns the value of the indexed component in the specified * array object, as a {@code float}. * * @param array the array * @param index the index * @return the value of the indexed component in the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array, or if the indexed element cannot be converted to the * return type by an identity or widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array * @see Array#get */ public static float getFloat(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof float[]) { return ((float[]) array)[index]; } else if (array instanceof byte[]) { return ((byte[]) array)[index]; } else if (array instanceof char[]) { return ((char[]) array)[index]; } else if (array instanceof int[]) { return ((int[]) array)[index]; } else if (array instanceof long[]) { return ((long[]) array)[index]; } else if (array instanceof short[]) { return ((short[]) array)[index]; } throw badArray(array); } /** * Returns the value of the indexed component in the specified * array object, as a {@code double}. * * @param array the array * @param index the index * @return the value of the indexed component in the specified array * @exception NullPointerException If the specified object is null * @exception IllegalArgumentException If the specified object is not * an array, or if the indexed element cannot be converted to the * return type by an identity or widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to the * length of the specified array * @see Array#get */ public static double getDouble(Object array, int index) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof double[]) { return ((double[]) array)[index]; } else if (array instanceof byte[]) { return ((byte[]) array)[index]; } else if (array instanceof char[]) { return ((char[]) array)[index]; } else if (array instanceof float[]) { return ((float[]) array)[index]; } else if (array instanceof int[]) { return ((int[]) array)[index]; } else if (array instanceof long[]) { return ((long[]) array)[index]; } else if (array instanceof short[]) { return ((short[]) array)[index]; } throw badArray(array); } /** * Sets the value of the indexed component of the specified array * object to the specified new value. The new value is first * automatically unwrapped if the array has a primitive component * type. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the array component type is primitive and * an unwrapping conversion fails * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array */ public static void set(Object array, int index, Object value) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (!array.getClass().isArray()) { throw notAnArray(array); } if (array instanceof Object[]) { if (value != null && !array.getClass().getComponentType().isInstance(value)) { throw incompatibleType(array); } ((Object[]) array)[index] = value; } else { if (value == null) { throw new IllegalArgumentException("Primitive array can't take null values."); } if (value instanceof Boolean) { setBoolean(array, index, ((Boolean) value).booleanValue()); } else if (value instanceof Byte) { setByte(array, index, ((Byte) value).byteValue()); } else if (value instanceof Character) { setChar(array, index, ((Character) value).charValue()); } else if (value instanceof Short) { setShort(array, index, ((Short) value).shortValue()); } else if (value instanceof Integer) { setInt(array, index, ((Integer) value).intValue()); } else if (value instanceof Long) { setLong(array, index, ((Long) value).longValue()); } else if (value instanceof Float) { setFloat(array, index, ((Float) value).floatValue()); } else if (value instanceof Double) { setDouble(array, index, ((Double) value).doubleValue()); } } } /** * Sets the value of the indexed component of the specified array * object to the specified {@code boolean} value. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the specified value cannot be converted * to the underlying array's component type by an identity or a * primitive widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array * @see Array#set */ // Android changed param name s/z/value public static void setBoolean(Object array, int index, boolean value) { if (array instanceof boolean[]) { ((boolean[]) array)[index] = value; } else { throw badArray(array); } } /** * Sets the value of the indexed component of the specified array * object to the specified {@code byte} value. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the specified value cannot be converted * to the underlying array's component type by an identity or a * primitive widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array * @see Array#set */ // Android changed param name s/b/value public static void setByte(Object array, int index, byte value) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof byte[]) { ((byte[]) array)[index] = value; } else if (array instanceof double[]) { ((double[]) array)[index] = value; } else if (array instanceof float[]) { ((float[]) array)[index] = value; } else if (array instanceof int[]) { ((int[]) array)[index] = value; } else if (array instanceof long[]) { ((long[]) array)[index] = value; } else if (array instanceof short[]) { ((short[]) array)[index] = value; } else { throw badArray(array); } } /** * Sets the value of the indexed component of the specified array * object to the specified {@code char} value. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the specified value cannot be converted * to the underlying array's component type by an identity or a * primitive widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array * @see Array#set */ // Android changed param name s/c/value public static void setChar(Object array, int index, char value) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof char[]) { ((char[]) array)[index] = value; } else if (array instanceof double[]) { ((double[]) array)[index] = value; } else if (array instanceof float[]) { ((float[]) array)[index] = value; } else if (array instanceof int[]) { ((int[]) array)[index] = value; } else if (array instanceof long[]) { ((long[]) array)[index] = value; } else { throw badArray(array); } } /** * Sets the value of the indexed component of the specified array * object to the specified {@code short} value. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the specified value cannot be converted * to the underlying array's component type by an identity or a * primitive widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array * @see Array#set */ // Android changed param name s/s/value public static void setShort(Object array, int index, short value) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof short[]) { ((short[]) array)[index] = value; } else if (array instanceof double[]) { ((double[]) array)[index] = value; } else if (array instanceof float[]) { ((float[]) array)[index] = value; } else if (array instanceof int[]) { ((int[]) array)[index] = value; } else if (array instanceof long[]) { ((long[]) array)[index] = value; } else { throw badArray(array); } } /** * Sets the value of the indexed component of the specified array * object to the specified {@code int} value. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the specified value cannot be converted * to the underlying array's component type by an identity or a * primitive widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array * @see Array#set */ // Android changed param name s/i/value public static void setInt(Object array, int index, int value) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof int[]) { ((int[]) array)[index] = value; } else if (array instanceof double[]) { ((double[]) array)[index] = value; } else if (array instanceof float[]) { ((float[]) array)[index] = value; } else if (array instanceof long[]) { ((long[]) array)[index] = value; } else { throw badArray(array); } } /** * Sets the value of the indexed component of the specified array * object to the specified {@code long} value. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the specified value cannot be converted * to the underlying array's component type by an identity or a * primitive widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array * @see Array#set */ // Android changed param name s/l/value public static void setLong(Object array, int index, long value) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof long[]) { ((long[]) array)[index] = value; } else if (array instanceof double[]) { ((double[]) array)[index] = value; } else if (array instanceof float[]) { ((float[]) array)[index] = value; } else { throw badArray(array); } } /** * Sets the value of the indexed component of the specified array * object to the specified {@code float} value. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the specified value cannot be converted * to the underlying array's component type by an identity or a * primitive widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array * @see Array#set */ // Android changed param name s/f/value public static void setFloat(Object array, int index, float value) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof float[]) { ((float[]) array)[index] = value; } else if (array instanceof double[]) { ((double[]) array)[index] = value; } else { throw badArray(array); } } /** * Sets the value of the indexed component of the specified array * object to the specified {@code double} value. * @param array the array * @param index the index into the array * @param value the new value of the indexed component * @exception NullPointerException If the specified object argument * is null * @exception IllegalArgumentException If the specified object argument * is not an array, or if the specified value cannot be converted * to the underlying array's component type by an identity or a * primitive widening conversion * @exception ArrayIndexOutOfBoundsException If the specified {@code index} * argument is negative, or if it is greater than or equal to * the length of the specified array * @see Array#set */ // Android changed param name s/d/value public static void setDouble(Object array, int index, double value) throws IllegalArgumentException, ArrayIndexOutOfBoundsException { if (array instanceof double[]) { ((double[]) array)[index] = value; } else { throw badArray(array); } } /* * Create a multi-dimensional array of objects with the specified type. */ private static native Object createMultiArray(Class componentType, int[] dimensions) throws NegativeArraySizeException; /** * Returns a new array of the specified component type and length. * Equivalent to {@code new componentType[size]}. * * @throws NullPointerException * if the component type is null * @throws NegativeArraySizeException * if {@code size < 0} */ private static Object newArray(Class componentType, int size) throws NegativeArraySizeException { if (!componentType.isPrimitive()) { return createObjectArray(componentType, size); } else if (componentType == char.class) { return new char[size]; } else if (componentType == int.class) { return new int[size]; } else if (componentType == byte.class) { return new byte[size]; } else if (componentType == boolean.class) { return new boolean[size]; } else if (componentType == short.class) { return new short[size]; } else if (componentType == long.class) { return new long[size]; } else if (componentType == float.class) { return new float[size]; } else if (componentType == double.class) { return new double[size]; } else if (componentType == void.class) { throw new IllegalArgumentException("Can't allocate an array of void"); } throw new AssertionError(); } /* * Create a one-dimensional array of objects with the specified type. */ private static native Object createObjectArray(Class componentType, int length) throws NegativeArraySizeException; private static IllegalArgumentException notAnArray(Object o) { throw new IllegalArgumentException("Not an array: " + o.getClass()); } private static IllegalArgumentException incompatibleType(Object o) { throw new IllegalArgumentException("Array has incompatible type: " + o.getClass()); } private static RuntimeException badArray(Object array) { if (array == null) { throw new NullPointerException("array == null"); } else if (!array.getClass().isArray()) { throw notAnArray(array); } else { throw incompatibleType(array); } } }