libjava/classpath/java/lang/Byte.java

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