libjava/java/lang/reflect/Array.java

   1 /* java.lang.reflect.Array - manipulate arrays by reflection
   2    Copyright (C) 1998, 1999, 2001, 2003, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.lang.reflect;
  40
  41 import gnu.classpath.Configuration;
  42
  43 /**
  44  * Array holds static helper functions that allow you to create and
  45  * manipulate arrays by reflection. Operations know how to perform widening
  46  * conversions, but throw {@link IllegalArgumentException} if you attempt
  47  * a narrowing conversion. Also, when accessing primitive arrays, this
  48  * class performs object wrapping and unwrapping as necessary.<p>
  49  *
  50  * <B>Note:</B> This class returns and accepts types as Classes, even
  51  * primitive types; there are Class types defined that represent each
  52  * different primitive type.  They are <code>java.lang.Boolean.TYPE,
  53  * java.lang.Byte.TYPE,</code>, also available as <code>boolean.class,
  54  * byte.class</code>, etc.  These are not to be confused with the
  55  * classes <code>java.lang.Boolean, java.lang.Byte</code>, etc., which are
  56  * real classes. Note also that the shorthand <code>Object[].class</code>
  57  * is a convenient way to get array Classes.<p>
  58  *
  59  * <B>Performance note:</B> This class performs best when it does not have
  60  * to convert primitive types.  The further along the chain it has to convert,
  61  * the worse performance will be.  You're best off using the array as whatever
  62  * type it already is, and then converting the result.  You will do even
  63  * worse if you do this and use the generic set() function.
  64  *
  65  * @author John Keiser
  66  * @author Eric Blake (ebb9@email.byu.edu)
  67  * @author Per Bothner (bothner@cygnus.com)
  68  * @see java.lang.Boolean#TYPE
  69  * @see java.lang.Byte#TYPE
  70  * @see java.lang.Short#TYPE
  71  * @see java.lang.Character#TYPE
  72  * @see java.lang.Integer#TYPE
  73  * @see java.lang.Long#TYPE
  74  * @see java.lang.Float#TYPE
  75  * @see java.lang.Double#TYPE
  76  * @since 1.1
  77  * @status updated to 1.4
  78  */
  79 public final class Array
  80 {
  81   static
  82   {
  83     if (Configuration.INIT_LOAD_LIBRARY)
  84       {
  85         System.loadLibrary("javalangreflect");
  86       }
  87   }
  88
  89   /**
  90    * This class is uninstantiable.
  91    */
  92   private Array()
  93   {
  94   }
  95
  96   /**
  97    * Creates a new single-dimensioned array.
  98    * @param componentType the type of the array to create
  99    * @param length the length of the array to create
 100    * @return the created array, cast to an Object
 101    * @throws NullPointerException if <code>componentType</code> is null
 102    * @throws IllegalArgumentException if <code>componentType</code> is
 103    *         <code>Void.TYPE</code>
 104    * @throws NegativeArraySizeException when length is less than 0
 105    * @throws OutOfMemoryError if memory allocation fails
 106    */
 107   public static native Object newInstance(Class componentType, int length);
 108
 109   /**
 110    * Creates a new multi-dimensioned array.  The new array has the same
 111    * component type as the argument class, and the number of dimensions
 112    * in the new array is the sum of the dimensions of the argument class
 113    * and the length of the argument dimensions. Virtual Machine limitations
 114    * forbid too many dimensions (usually 255 is the maximum); but even
 115    * 50 dimensions of 2 elements in each dimension would exceed your memory
 116    * long beforehand!
 117    *
 118    * @param componentType the type of the array to create.
 119    * @param dimensions the dimensions of the array to create.  Each element
 120    *        in <code>dimensions</code> makes another dimension of the new
 121    *        array.  Thus, <code>Array.newInstance(java.lang.Boolean,
 122    *        new int[]{1,2,3})</code> is the same as
 123    *        <code>new java.lang.Boolean[1][2][3]</code>
 124    * @return the created array, cast to an Object
 125    * @throws NullPointerException if componentType or dimension is null
 126    * @throws IllegalArgumentException if the the size of
 127    *         <code>dimensions</code> is 0 or exceeds the maximum number of
 128    *         array dimensions in the VM; or if componentType is Void.TYPE
 129    * @throws NegativeArraySizeException when any of the dimensions is less
 130    *         than 0
 131    * @throws OutOfMemoryError if memory allocation fails
 132    */
 133   public static native Object newInstance(Class elementType, int[] dimensions);
 134
 135   /**
 136    * Gets the array length.
 137    * @param array the array
 138    * @return the length of the array
 139    * @throws IllegalArgumentException if <code>array</code> is not an array
 140    * @throws NullPointerException if <code>array</code> is null
 141    */
 142   public static native int getLength(Object array);
 143
 144   /**
 145    * Gets an element of an array.  Primitive elements will be wrapped in
 146    * the corresponding class type.
 147    *
 148    * @param array the array to access
 149    * @param index the array index to access
 150    * @return the element at <code>array[index]</code>
 151    * @throws IllegalArgumentException if <code>array</code> is not an array
 152    * @throws NullPointerException if <code>array</code> is null
 153    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 154    *         bounds
 155    * @see #getBoolean(Object, int)
 156    * @see #getByte(Object, int)
 157    * @see #getChar(Object, int)
 158    * @see #getShort(Object, int)
 159    * @see #getInt(Object, int)
 160    * @see #getLong(Object, int)
 161    * @see #getFloat(Object, int)
 162    * @see #getDouble(Object, int)
 163    */
 164   public static native Object get(Object array, int index);
 165
 166   /**
 167    * Gets an element of a boolean array.
 168    *
 169    * @param array the array to access
 170    * @param index the array index to access
 171    * @return the boolean element at <code>array[index]</code>
 172    * @throws IllegalArgumentException  if <code>array</code> is not a boolean
 173    *         array
 174    * @throws NullPointerException if <code>array</code> is null
 175    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 176    *         bounds
 177    * @see #get(Object, int)
 178    */
 179   public static native boolean getBoolean(Object array, int index);
 180
 181   /**
 182    * Gets an element of a byte array.
 183    *
 184    * @param array the array to access
 185    * @param index the array index to access
 186    * @return the byte element at <code>array[index]</code>
 187    * @throws IllegalArgumentException  if <code>array</code> is not a byte
 188    *         array
 189    * @throws NullPointerException if <code>array</code> is null
 190    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 191    *         bounds
 192    * @see #get(Object, int)
 193    */
 194   public static native byte getByte(Object array, int index);
 195
 196   /**
 197    * Gets an element of a char array.
 198    *
 199    * @param array the array to access
 200    * @param index the array index to access
 201    * @return the char element at <code>array[index]</code>
 202    * @throws IllegalArgumentException  if <code>array</code> is not a char
 203    *         array
 204    * @throws NullPointerException if <code>array</code> is null
 205    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 206    *         bounds
 207    * @see #get(Object, int)
 208    */
 209   public static native char getChar(Object array, int index);
 210
 211   /**
 212    * Gets an element of a short array.
 213    *
 214    * @param array the array to access
 215    * @param index the array index to access
 216    * @return the short element at <code>array[index]</code>
 217    * @throws IllegalArgumentException  if <code>array</code> is not a byte
 218    *         or char array
 219    * @throws NullPointerException if <code>array</code> is null
 220    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 221    *         bounds
 222    * @see #get(Object, int)
 223    */
 224   public static native short getShort(Object array, int index);
 225
 226   /**
 227    * Gets an element of an int array.
 228    *
 229    * @param array the array to access
 230    * @param index the array index to access
 231    * @return the int element at <code>array[index]</code>
 232    * @throws IllegalArgumentException  if <code>array</code> is not a byte,
 233    *         char, short, or int array
 234    * @throws NullPointerException if <code>array</code> is null
 235    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 236    *         bounds
 237    * @see #get(Object, int)
 238    */
 239   public static native int getInt(Object array, int index);
 240
 241   /**
 242    * Gets an element of a long array.
 243    *
 244    * @param array the array to access
 245    * @param index the array index to access
 246    * @return the long element at <code>array[index]</code>
 247    * @throws IllegalArgumentException  if <code>array</code> is not a byte,
 248    *         char, short, int, or long array
 249    * @throws NullPointerException if <code>array</code> is null
 250    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 251    *         bounds
 252    * @see #get(Object, int)
 253    */
 254   public static native long getLong(Object array, int index);
 255
 256   /**
 257    * Gets an element of a float array.
 258    *
 259    * @param array the array to access
 260    * @param index the array index to access
 261    * @return the float element at <code>array[index]</code>
 262    * @throws IllegalArgumentException  if <code>array</code> is not a byte,
 263    *         char, short, int, long, or float array
 264    * @throws NullPointerException if <code>array</code> is null
 265    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 266    *         bounds
 267    * @see #get(Object, int)
 268    */
 269   public static native float getFloat(Object array, int index);
 270
 271   /**
 272    * Gets an element of a double array.
 273    *
 274    * @param array the array to access
 275    * @param index the array index to access
 276    * @return the double element at <code>array[index]</code>
 277    * @throws IllegalArgumentException  if <code>array</code> is not a byte,
 278    *         char, short, int, long, float, or double array
 279    * @throws NullPointerException if <code>array</code> is null
 280    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 281    *         bounds
 282    * @see #get(Object, int)
 283    */
 284   public static native double getDouble(Object array, int index);
 285
 286   private static native Class getElementType(Object array, int index);
 287
 288   private static native void set(Object array, int index,
 289                                   Object value, Class elType);
 290
 291   /**
 292    * Sets an element of an array. If the array is primitive, then the new
 293    * value is unwrapped and widened.
 294    *
 295    * @param array the array to set a value of
 296    * @param index the array index to set the value to
 297    * @param value the value to set
 298    * @throws IllegalArgumentException if <code>array</code> is not an array,
 299    *         or the array is primitive and unwrapping value fails, or the
 300    *         value is not assignable to the array component type
 301    * @throws NullPointerException if array is null, or if array is primitive
 302    *         and value is null
 303    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 304    *         bounds
 305    * @see #setBoolean(Object, int, boolean)
 306    * @see #setByte(Object, int, byte)
 307    * @see #setChar(Object, int, char)
 308    * @see #setShort(Object, int, short)
 309    * @see #setInt(Object, int, int)
 310    * @see #setLong(Object, int, long)
 311    * @see #setFloat(Object, int, float)
 312    * @see #setDouble(Object, int, double)
 313    */
 314   public static void set(Object array, int index, Object value)
 315   {
 316     Class elType = getElementType(array, index);
 317     if (! elType.isPrimitive())
 318       set(array, index, value, elType);
 319     else if (value instanceof Byte)
 320       setByte(array, index, ((Byte) value).byteValue());
 321     else if (value instanceof Short)
 322       setShort(array, index, ((Short) value).shortValue());
 323     else if (value instanceof Integer)
 324       setInt(array, index, ((Integer) value).intValue());
 325     else if (value instanceof Long)
 326       setLong(array, index, ((Long) value).longValue());
 327     else if (value instanceof Float)
 328       setFloat(array, index, ((Float) value).floatValue());
 329     else if (value instanceof Double)
 330       setDouble(array, index, ((Double) value).doubleValue());
 331     else if (value instanceof Character)
 332       setChar(array, index, ((Character) value).charValue());
 333     else if (value instanceof Boolean)
 334       setBoolean(array, index, ((Boolean) value).booleanValue());
 335     else
 336       throw new IllegalArgumentException();
 337   }
 338
 339   /**
 340    * Sets an element of a boolean array.
 341    *
 342    * @param array the array to set a value of
 343    * @param index the array index to set the value to
 344    * @param value the value to set
 345    * @throws IllegalArgumentException if <code>array</code> is not a boolean
 346    *         array
 347    * @throws NullPointerException if <code>array</code> is null
 348    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 349    *         bounds
 350    * @see #set(Object, int, Object)
 351    */
 352   public static native void setBoolean(Object array, int index, boolean value);
 353
 354   /**
 355    * Sets an element of a byte array.
 356    *
 357    * @param array the array to set a value of
 358    * @param index the array index to set the value to
 359    * @param value the value to set
 360    * @throws IllegalArgumentException if <code>array</code> is not a byte,
 361    *         short, int, long, float, or double array
 362    * @throws NullPointerException if <code>array</code> is null
 363    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 364    *         bounds
 365    * @see #set(Object, int, Object)
 366    */
 367   public static native void setByte(Object array, int index, byte value);
 368
 369   /**
 370    * Sets an element of a char array.
 371    *
 372    * @param array the array to set a value of
 373    * @param index the array index to set the value to
 374    * @param value the value to set
 375    * @throws IllegalArgumentException if <code>array</code> is not a char,
 376    *         int, long, float, or double array
 377    * @throws NullPointerException if <code>array</code> is null
 378    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 379    *         bounds
 380    * @see #set(Object, int, Object)
 381    */
 382   public static native void setChar(Object array, int index, char value);
 383
 384   /**
 385    * Sets an element of a short array.
 386    *
 387    * @param array the array to set a value of
 388    * @param index the array index to set the value to
 389    * @param value the value to set
 390    * @throws IllegalArgumentException if <code>array</code> is not a short,
 391    *         int, long, float, or double array
 392    * @throws NullPointerException if <code>array</code> is null
 393    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 394    *         bounds
 395    * @see #set(Object, int, Object)
 396    */
 397   public static native void setShort(Object array, int index, short value);
 398
 399   /**
 400    * Sets an element of an int array.
 401    *
 402    * @param array the array to set a value of
 403    * @param index the array index to set the value to
 404    * @param value the value to set
 405    * @throws IllegalArgumentException if <code>array</code> is not an int,
 406    *         long, float, or double array
 407    * @throws NullPointerException if <code>array</code> is null
 408    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 409    *         bounds
 410    * @see #set(Object, int, Object)
 411    */
 412   public static native void setInt(Object array, int index, int value);
 413
 414   /**
 415    * Sets an element of a long array.
 416    *
 417    * @param array the array to set a value of
 418    * @param index the array index to set the value to
 419    * @param value the value to set
 420    * @throws IllegalArgumentException if <code>array</code> is not a long,
 421    *         float, or double array
 422    * @throws NullPointerException if <code>array</code> is null
 423    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 424    *         bounds
 425    * @see #set(Object, int, Object)
 426    */
 427   public static native void setLong(Object array, int index, long value);
 428
 429   /**
 430    * Sets an element of a float array.
 431    *
 432    * @param array the array to set a value of
 433    * @param index the array index to set the value to
 434    * @param value the value to set
 435    * @throws IllegalArgumentException if <code>array</code> is not a float
 436    *         or double array
 437    * @throws NullPointerException if <code>array</code> is null
 438    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 439    *         bounds
 440    * @see #set(Object, int, Object)
 441    */
 442   public static native void setFloat(Object array, int index, float value);
 443
 444   /**
 445    * Sets an element of a double array.
 446    *
 447    * @param array the array to set a value of
 448    * @param index the array index to set the value to
 449    * @param value the value to set
 450    * @throws IllegalArgumentException if <code>array</code> is not a double
 451    *         array
 452    * @throws NullPointerException if <code>array</code> is null
 453    * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
 454    *         bounds
 455    * @see #set(Object, int, Object)
 456    */
 457   public static native void setDouble(Object array, int index, double value);
 458 }