libjava/java/lang/Byte.java

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