Source for java.lang.Byte

   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: }