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   static
  92   {
  93     for (int i=MIN_VALUE; i <= MAX_VALUE; i++)
  94       byteCache[i - MIN_VALUE] = new Byte((byte) i);
  95   }
  96
  97
  98   /**
  99    * The immutable value of this Byte.
 100    *
 101    * @serial the wrapped byte
 102    */
 103   private final byte value;
 104
 105   /**
 106    * Create a <code>Byte</code> object representing the value of the
 107    * <code>byte</code> argument.
 108    *
 109    * @param value the value to use
 110    */
 111   public Byte(byte value)
 112   {
 113     this.value = value;
 114   }
 115
 116   /**
 117    * Create a <code>Byte</code> object representing the value specified
 118    * by the <code>String</code> argument
 119    *
 120    * @param s the string to convert
 121    * @throws NumberFormatException if the String does not contain a byte
 122    * @see #valueOf(String)
 123    */
 124   public Byte(String s)
 125   {
 126     value = parseByte(s, 10);
 127   }
 128
 129   /**
 130    * Converts the <code>byte</code> to a <code>String</code> and assumes
 131    * a radix of 10.
 132    *
 133    * @param b the <code>byte</code> to convert to <code>String</code>
 134    * @return the <code>String</code> representation of the argument
 135    */
 136   public static String toString(byte b)
 137   {
 138     return String.valueOf(b);
 139   }
 140
 141   /**
 142    * Converts the specified <code>String</code> into a <code>byte</code>.
 143    * This function assumes a radix of 10.
 144    *
 145    * @param s the <code>String</code> to convert
 146    * @return the <code>byte</code> value of <code>s</code>
 147    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 148    *         <code>byte</code>
 149    * @see #parseByte(String)
 150    */
 151   public static byte parseByte(String s)
 152   {
 153     return parseByte(s, 10);
 154   }
 155
 156   /**
 157    * Converts the specified <code>String</code> into an <code>int</code>
 158    * using the specified radix (base). The string must not be <code>null</code>
 159    * or empty. It may begin with an optional '-', which will negate the answer,
 160    * provided that there are also valid digits. Each digit is parsed as if by
 161    * <code>Character.digit(d, radix)</code>, and must be in the range
 162    * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
 163    * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
 164    * Unlike Double.parseDouble, you may not have a leading '+'.
 165    *
 166    * @param s the <code>String</code> to convert
 167    * @param radix the radix (base) to use in the conversion
 168    * @return the <code>String</code> argument converted to <code>byte</code>
 169    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 170    *         <code>byte</code>
 171    */
 172   public static byte parseByte(String s, int radix)
 173   {
 174     int i = Integer.parseInt(s, radix, false);
 175     if ((byte) i != i)
 176       throw new NumberFormatException();
 177     return (byte) i;
 178   }
 179
 180   /**
 181    * Creates a new <code>Byte</code> object using the <code>String</code>
 182    * and specified radix (base).
 183    *
 184    * @param s the <code>String</code> to convert
 185    * @param radix the radix (base) to convert with
 186    * @return the new <code>Byte</code>
 187    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 188    *         <code>byte</code>
 189    * @see #parseByte(String, int)
 190    */
 191   public static Byte valueOf(String s, int radix)
 192   {
 193     return valueOf(parseByte(s, radix));
 194   }
 195
 196   /**
 197    * Creates a new <code>Byte</code> object using the <code>String</code>,
 198    * assuming a radix of 10.
 199    *
 200    * @param s the <code>String</code> to convert
 201    * @return the new <code>Byte</code>
 202    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
 203    *         <code>byte</code>
 204    * @see #Byte(String)
 205    * @see #parseByte(String)
 206    */
 207   public static Byte valueOf(String s)
 208   {
 209     return valueOf(parseByte(s, 10));
 210   }
 211
 212   /**
 213    * Returns a <code>Byte</code> object wrapping the value.
 214    * In contrast to the <code>Byte</code> constructor, this method
 215    * will cache some values.  It is used by boxing conversion.
 216    *
 217    * @param val the value to wrap
 218    * @return the <code>Byte</code>
 219    */
 220   public static Byte valueOf(byte val)
 221   {
 222     return byteCache[val - MIN_VALUE];
 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 valueOf((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   /**
 374    * Compares two unboxed byte values.
 375    * The result is positive if the first is greater, negative if the second
 376    * is greater, and 0 if the two are equal.
 377    *
 378    * @param x First value to compare.
 379    * @param y Second value to compare.
 380    *
 381    * @return positive int if the first value is greater, negative if the second
 382    * is greater, and 0 if the two are equal.
 383    * @since 1.7
 384    */
 385   public static int compare(byte x, byte y)
 386   {
 387     return Byte.valueOf(x).compareTo(Byte.valueOf(y));
 388   }
 389
 390 }