001 /* Byte.java -- object wrapper for byte 002 Copyright (C) 1998, 2001, 2002, 2004, 2005 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.lang; 040 041 /** 042 * Instances of class <code>Byte</code> represent primitive <code>byte</code> 043 * values. 044 * 045 * Additionally, this class provides various helper functions and variables 046 * useful to bytes. 047 * 048 * @author Paul Fisher 049 * @author John Keiser 050 * @author Per Bothner 051 * @author Eric Blake (ebb9@email.byu.edu) 052 * @author Tom Tromey (tromey@redhat.com) 053 * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 054 * @since 1.1 055 * @status updated to 1.5 056 */ 057 public final class Byte extends Number implements Comparable<Byte> 058 { 059 /** 060 * Compatible with JDK 1.1+. 061 */ 062 private static final long serialVersionUID = -7183698231559129828L; 063 064 /** 065 * The minimum value a <code>byte</code> can represent is -128 (or 066 * -2<sup>7</sup>). 067 */ 068 public static final byte MIN_VALUE = -128; 069 070 /** 071 * The maximum value a <code>byte</code> can represent is 127 (or 072 * 2<sup>7</sup> - 1). 073 */ 074 public static final byte MAX_VALUE = 127; 075 076 /** 077 * The primitive type <code>byte</code> is represented by this 078 * <code>Class</code> object. 079 */ 080 public static final Class<Byte> TYPE = (Class<Byte>) VMClassLoader.getPrimitiveClass('B'); 081 082 /** 083 * The number of bits needed to represent a <code>byte</code>. 084 * @since 1.5 085 */ 086 public static final int SIZE = 8; 087 088 // This caches Byte values, and is used by boxing conversions via 089 // valueOf(). We're required to cache all possible values here. 090 private static Byte[] byteCache = new Byte[MAX_VALUE - MIN_VALUE + 1]; 091 092 093 /** 094 * The immutable value of this Byte. 095 * 096 * @serial the wrapped byte 097 */ 098 private final byte value; 099 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 }