libjava/classpath/java/lang/Short.java

   1 /* Short.java -- object wrapper for short
   2    Copyright (C) 1998, 2001, 2002, 2004, 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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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;
  40
  41 /**
  42  * Instances of class <code>Short</code> represent primitive
  43  * <code>short</code> values.
  44  *
  45  * Additionally, this class provides various helper functions and variables
  46  * related to shorts.
  47  *
  48  * @author Paul Fisher
  49  * @author John Keiser
  50  * @author Eric Blake (ebb9@email.byu.edu)
  51  * @author Tom Tromey (tromey@redhat.com)
  52  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  53  * @since 1.1
  54  * @status updated to 1.5
  55  */
  56 public final class Short extends Number implements Comparable<Short>
  57 {
  58   /**
  59    * Compatible with JDK 1.1+.
  60    */
  61   private static final long serialVersionUID = 7515723908773894738L;
  62
  63   /**
  64    * The minimum value a <code>short</code> can represent is -32768 (or
  65    * -2<sup>15</sup>).
  66    */
  67   public static final short MIN_VALUE = -32768;
  68
  69   /**
  70    * The minimum value a <code>short</code> can represent is 32767 (or
  71    * 2<sup>15</sup>).
  72    */
  73   public static final short MAX_VALUE = 32767;
  74
  75   /**
  76    * The primitive type <code>short</code> is represented by this
  77    * <code>Class</code> object.
  78    */
  79   public static final Class<Short> TYPE = (Class<Short>) VMClassLoader.getPrimitiveClass('S');
  80
  81   /**
  82    * The number of bits needed to represent a <code>short</code>.
  83    * @since 1.5
  84    */
  85   public static final int SIZE = 16;
  86
  87   // This caches some Short values, and is used by boxing conversions
  88   // via valueOf().  We must cache at least -128..127; these constants
  89   // control how much we actually cache.
  90   private static final int MIN_CACHE = -128;
  91   private static final int MAX_CACHE = 127;
  92   private static Short[] shortCache = new Short[MAX_CACHE - MIN_CACHE + 1];
  93
  94   /**
  95    * The immutable value of this Short.
  96    *
  97    * @serial the wrapped short
  98    */
  99   private final short value;
 100
 101   /**
 102    * Create a <code>Short</code> object representing the value of the
 103    * <code>short</code> argument.
 104    *
 105    * @param value the value to use
 106    */
 107   public Short(short value)
 108   {
 109     this.value = value;
 110   }
 111
 112   /**
 113    * Create a <code>Short</code> object representing the value of the
 114    * argument after conversion to a <code>short</code>.
 115    *
 116    * @param s the string to convert
 117    * @throws NumberFormatException if the String cannot be parsed
 118    */
 119   public Short(String s)
 120   {
 121     value = parseShort(s, 10);
 122   }
 123
 124   /**
 125    * Converts the <code>short</code> to a <code>String</code> and assumes
 126    * a radix of 10.
 127    *
 128    * @param s the <code>short</code> to convert to <code>String</code>
 129    * @return the <code>String</code> representation of the argument
 130    */
 131   public static String toString(short s)
 132   {
 133     return String.valueOf(s);
 134   }
 135
 136   /**
 137    * Converts the specified <code>String</code> into a <code>short</code>.
 138    * This function assumes a radix of 10.
 139    *
 140    * @param s the <code>String</code> to convert
 141    * @return the <code>short</code> value of <code>s</code>
 142    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 143    *         <code>short</code>
 144    */
 145   public static short parseShort(String s)
 146   {
 147     return parseShort(s, 10);
 148   }
 149
 150   /**
 151    * Converts the specified <code>String</code> into a <code>short</code>
 152    * using the specified radix (base). The string must not be <code>null</code>
 153    * or empty. It may begin with an optional '-', which will negate the answer,
 154    * provided that there are also valid digits. Each digit is parsed as if by
 155    * <code>Character.digit(d, radix)</code>, and must be in the range
 156    * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
 157    * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
 158    * Unlike Double.parseDouble, you may not have a leading '+'.
 159    *
 160    * @param s the <code>String</code> to convert
 161    * @param radix the radix (base) to use in the conversion
 162    * @return the <code>String</code> argument converted to <code>short</code>
 163    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 164    *         <code>short</code>
 165    */
 166   public static short parseShort(String s, int radix)
 167   {
 168     int i = Integer.parseInt(s, radix, false);
 169     if ((short) i != i)
 170       throw new NumberFormatException();
 171     return (short) i;
 172   }
 173
 174   /**
 175    * Creates a new <code>Short</code> object using the <code>String</code>
 176    * and specified radix (base).
 177    *
 178    * @param s the <code>String</code> to convert
 179    * @param radix the radix (base) to convert with
 180    * @return the new <code>Short</code>
 181    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 182    *         <code>short</code>
 183    * @see #parseShort(String, int)
 184    */
 185   public static Short valueOf(String s, int radix)
 186   {
 187     return new Short(parseShort(s, radix));
 188   }
 189
 190   /**
 191    * Creates a new <code>Short</code> object using the <code>String</code>,
 192    * assuming a radix of 10.
 193    *
 194    * @param s the <code>String</code> to convert
 195    * @return the new <code>Short</code>
 196    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 197    *         <code>short</code>
 198    * @see #Short(String)
 199    * @see #parseShort(String)
 200    */
 201   public static Short valueOf(String s)
 202   {
 203     return new Short(parseShort(s, 10));
 204   }
 205
 206   /**
 207    * Returns a <code>Short</code> object wrapping the value.
 208    * In contrast to the <code>Short</code> constructor, this method
 209    * will cache some values.  It is used by boxing conversion.
 210    *
 211    * @param val the value to wrap
 212    * @return the <code>Short</code>
 213    * @since 1.5
 214    */
 215   public static Short valueOf(short val)
 216   {
 217     if (val < MIN_CACHE || val > MAX_CACHE)
 218       return new Short(val);
 219     synchronized (shortCache)
 220       {
 221         if (shortCache[val - MIN_CACHE] == null)
 222           shortCache[val - MIN_CACHE] = new Short(val);
 223         return shortCache[val - MIN_CACHE];
 224       }
 225   }
 226
 227   /**
 228    * Convert the specified <code>String</code> into a <code>Short</code>.
 229    * The <code>String</code> may represent decimal, hexadecimal, or
 230    * octal numbers.
 231    *
 232    * <p>The extended BNF grammar is as follows:<br>
 233    * <pre>
 234    * <em>DecodableString</em>:
 235    *      ( [ <code>-</code> ] <em>DecimalNumber</em> )
 236    *    | ( [ <code>-</code> ] ( <code>0x</code> | <code>0X</code>
 237    *              | <code>#</code> ) <em>HexDigit</em> { <em>HexDigit</em> } )
 238    *    | ( [ <code>-</code> ] <code>0</code> { <em>OctalDigit</em> } )
 239    * <em>DecimalNumber</em>:
 240    *        <em>DecimalDigit except '0'</em> { <em>DecimalDigit</em> }
 241    * <em>DecimalDigit</em>:
 242    *        <em>Character.digit(d, 10) has value 0 to 9</em>
 243    * <em>OctalDigit</em>:
 244    *        <em>Character.digit(d, 8) has value 0 to 7</em>
 245    * <em>DecimalDigit</em>:
 246    *        <em>Character.digit(d, 16) has value 0 to 15</em>
 247    * </pre>
 248    * Finally, the value must be in the range <code>MIN_VALUE</code> to
 249    * <code>MAX_VALUE</code>, or an exception is thrown.
 250    *
 251    * @param s the <code>String</code> to interpret
 252    * @return the value of the String as a <code>Short</code>
 253    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 254    *         <code>short</code>
 255    * @throws NullPointerException if <code>s</code> is null
 256    * @see Integer#decode(String)
 257    */
 258   public static Short decode(String s)
 259   {
 260     int i = Integer.parseInt(s, 10, true);
 261     if ((short) i != i)
 262       throw new NumberFormatException();
 263     return new Short((short) i);
 264   }
 265
 266   /**
 267    * Return the value of this <code>Short</code> as a <code>byte</code>.
 268    *
 269    * @return the byte value
 270    */
 271   public byte byteValue()
 272   {
 273     return (byte) value;
 274   }
 275
 276   /**
 277    * Return the value of this <code>Short</code>.
 278    *
 279    * @return the short value
 280    */
 281   public short shortValue()
 282   {
 283     return value;
 284   }
 285
 286   /**
 287    * Return the value of this <code>Short</code> as an <code>int</code>.
 288    *
 289    * @return the int value
 290    */
 291   public int intValue()
 292   {
 293     return value;
 294   }
 295
 296   /**
 297    * Return the value of this <code>Short</code> as a <code>long</code>.
 298    *
 299    * @return the long value
 300    */
 301   public long longValue()
 302   {
 303     return value;
 304   }
 305
 306   /**
 307    * Return the value of this <code>Short</code> as a <code>float</code>.
 308    *
 309    * @return the float value
 310    */
 311   public float floatValue()
 312   {
 313     return value;
 314   }
 315
 316   /**
 317    * Return the value of this <code>Short</code> as a <code>double</code>.
 318    *
 319    * @return the double value
 320    */
 321   public double doubleValue()
 322   {
 323     return value;
 324   }
 325
 326   /**
 327    * Converts the <code>Short</code> value to a <code>String</code> and
 328    * assumes a radix of 10.
 329    *
 330    * @return the <code>String</code> representation of this <code>Short</code>
 331    */
 332   public String toString()
 333   {
 334     return String.valueOf(value);
 335   }
 336
 337   /**
 338    * Return a hashcode representing this Object. <code>Short</code>'s hash
 339    * code is simply its value.
 340    *
 341    * @return this Object's hash code
 342    */
 343   public int hashCode()
 344   {
 345     return value;
 346   }
 347
 348   /**
 349    * Returns <code>true</code> if <code>obj</code> is an instance of
 350    * <code>Short</code> and represents the same short value.
 351    *
 352    * @param obj the object to compare
 353    * @return whether these Objects are semantically equal
 354    */
 355   public boolean equals(Object obj)
 356   {
 357     return obj instanceof Short && value == ((Short) obj).value;
 358   }
 359
 360   /**
 361    * Compare two Shorts numerically by comparing their <code>short</code>
 362    * values. The result is positive if the first is greater, negative if the
 363    * second is greater, and 0 if the two are equal.
 364    *
 365    * @param s the Short to compare
 366    * @return the comparison
 367    * @since 1.2
 368    */
 369   public int compareTo(Short s)
 370   {
 371     return value - s.value;
 372   }
 373
 374   /**
 375    * Reverse the bytes in val.
 376    * @since 1.5
 377    */
 378   public static short reverseBytes(short val)
 379   {
 380     return (short) (((val >> 8) & 0xff) | ((val << 8) & 0xff00));
 381   }
 382 }