Source for java.lang.Byte

   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., 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:  * @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: }