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