1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.lang; 19 20 /** 21 * The wrapper for the primitive type {@code byte}. 22 * 23 * @since 1.1 24 */ 25 @FindBugsSuppressWarnings("DM_NUMBER_CTOR") 26 public final class Byte extends Number implements Comparable<Byte> { 27 28 private static final long serialVersionUID = -7183698231559129828L; 29 30 /** 31 * The value which the receiver represents. 32 */ 33 private final byte value; 34 35 /** 36 * The maximum {@code Byte} value, 2<sup>7</sup>-1. 37 */ 38 public static final byte MAX_VALUE = (byte) 0x7F; 39 40 /** 41 * The minimum {@code Byte} value, -2<sup>7</sup>. 42 */ 43 public static final byte MIN_VALUE = (byte) 0x80; 44 45 /** 46 * The number of bits needed to represent a {@code Byte} value in two's 47 * complement form. 48 * 49 * @since 1.5 50 */ 51 public static final int SIZE = 8; 52 53 /** 54 * The {@link Class} object that represents the primitive type {@code byte}. 55 */ 56 @SuppressWarnings("unchecked") 57 public static final Class<Byte> TYPE 58 = (Class<Byte>) byte[].class.getComponentType(); 59 // Note: Byte.TYPE can't be set to "byte.class", since *that* is 60 // defined to be "java.lang.Byte.TYPE"; 61 62 /** 63 * Constructs a new {@code Byte} with the specified primitive byte value. 64 * 65 * @param value 66 * the primitive byte value to store in the new instance. 67 */ Byte(byte value)68 public Byte(byte value) { 69 this.value = value; 70 } 71 72 /** 73 * Constructs a new {@code Byte} from the specified string. 74 * 75 * @param string 76 * the string representation of a single byte value. 77 * @throws NumberFormatException 78 * if {@code string} cannot be parsed as a byte value. 79 * @see #parseByte(String) 80 */ Byte(String string)81 public Byte(String string) throws NumberFormatException { 82 this(parseByte(string)); 83 } 84 85 /** 86 * Gets the primitive value of this byte. 87 * 88 * @return this object's primitive value. 89 */ 90 @Override byteValue()91 public byte byteValue() { 92 return value; 93 } 94 95 /** 96 * Compares this object to the specified byte object to determine their 97 * relative order. 98 * 99 * @param object 100 * the byte object to compare this object to. 101 * @return a negative value if the value of this byte is less than the value 102 * of {@code object}; 0 if the value of this byte and the value of 103 * {@code object} are equal; a positive value if the value of this 104 * byte is greater than the value of {@code object}. 105 * @see java.lang.Comparable 106 * @since 1.2 107 */ compareTo(Byte object)108 public int compareTo(Byte object) { 109 return compare(value, object.value); 110 } 111 112 /** 113 * Compares two {@code byte} values. 114 * @return 0 if lhs = rhs, less than 0 if lhs < rhs, and greater than 0 if lhs > rhs. 115 * @since 1.7 116 * @hide 1.7 117 */ compare(byte lhs, byte rhs)118 public static int compare(byte lhs, byte rhs) { 119 return lhs > rhs ? 1 : (lhs < rhs ? -1 : 0); 120 } 121 122 /** 123 * Parses the specified string and returns a {@code Byte} instance if the 124 * string can be decoded into a single byte value. The string may be an 125 * optional minus sign "-" followed by a hexadecimal ("0x..." or "#..."), 126 * octal ("0..."), or decimal ("...") representation of a byte. 127 * 128 * @param string 129 * a string representation of a single byte value. 130 * @return a {@code Byte} containing the value represented by {@code string}. 131 * @throws NumberFormatException 132 * if {@code string} cannot be parsed as a byte value. 133 */ decode(String string)134 public static Byte decode(String string) throws NumberFormatException { 135 int intValue = Integer.decode(string); 136 byte result = (byte) intValue; 137 if (result == intValue) { 138 return valueOf(result); 139 } 140 throw new NumberFormatException("Value out of range for byte: \"" + string + "\""); 141 } 142 143 @Override doubleValue()144 public double doubleValue() { 145 return value; 146 } 147 148 /** 149 * Compares this object with the specified object and indicates if they are 150 * equal. In order to be equal, {@code object} must be an instance of 151 * {@code Byte} and have the same byte value as this object. 152 * 153 * @param object 154 * the object to compare this byte with. 155 * @return {@code true} if the specified object is equal to this 156 * {@code Byte}; {@code false} otherwise. 157 */ 158 @Override 159 @FindBugsSuppressWarnings("RC_REF_COMPARISON") equals(Object object)160 public boolean equals(Object object) { 161 return (object == this) || ((object instanceof Byte) && (((Byte) object).value == value)); 162 } 163 164 @Override floatValue()165 public float floatValue() { 166 return value; 167 } 168 169 @Override hashCode()170 public int hashCode() { 171 return value; 172 } 173 174 @Override intValue()175 public int intValue() { 176 return value; 177 } 178 179 @Override longValue()180 public long longValue() { 181 return value; 182 } 183 184 /** 185 * Parses the specified string as a signed decimal byte value. The ASCII 186 * character \u002d ('-') is recognized as the minus sign. 187 * 188 * @param string 189 * the string representation of a single byte value. 190 * @return the primitive byte value represented by {@code string}. 191 * @throws NumberFormatException 192 * if {@code string} can not be parsed as a byte value. 193 */ parseByte(String string)194 public static byte parseByte(String string) throws NumberFormatException { 195 return parseByte(string, 10); 196 } 197 198 /** 199 * Parses the specified string as a signed byte value using the specified 200 * radix. The ASCII character \u002d ('-') is recognized as the minus sign. 201 * 202 * @param string 203 * the string representation of a single byte value. 204 * @param radix 205 * the radix to use when parsing. 206 * @return the primitive byte value represented by {@code string} using 207 * {@code radix}. 208 * @throws NumberFormatException 209 * if {@code string} can not be parsed as a byte value, or 210 * {@code radix < Character.MIN_RADIX || 211 * radix > Character.MAX_RADIX}. 212 */ parseByte(String string, int radix)213 public static byte parseByte(String string, int radix) throws NumberFormatException { 214 int intValue = Integer.parseInt(string, radix); 215 byte result = (byte) intValue; 216 if (result == intValue) { 217 return result; 218 } 219 throw new NumberFormatException("Value out of range for byte: \"" + string + "\""); 220 } 221 222 @Override shortValue()223 public short shortValue() { 224 return value; 225 } 226 227 @Override toString()228 public String toString() { 229 return Integer.toString(value); 230 } 231 232 /** 233 * Returns a two-digit hex string. That is, -1 becomes "ff" or "FF" and 2 becomes "02". 234 * @hide internal use only 235 */ toHexString(byte b, boolean upperCase)236 public static String toHexString(byte b, boolean upperCase) { 237 return IntegralToString.byteToHexString(b, upperCase); 238 } 239 240 /** 241 * Returns a string containing a concise, human-readable description of the 242 * specified byte value. 243 * 244 * @param value 245 * the byte to convert to a string. 246 * @return a printable representation of {@code value}. 247 */ toString(byte value)248 public static String toString(byte value) { 249 return Integer.toString(value); 250 } 251 252 /** 253 * Parses the specified string as a signed decimal byte value. 254 * 255 * @param string 256 * the string representation of a single byte value. 257 * @return a {@code Byte} instance containing the byte value represented by 258 * {@code string}. 259 * @throws NumberFormatException 260 * if {@code string} can not be parsed as a byte value. 261 * @see #parseByte(String) 262 */ valueOf(String string)263 public static Byte valueOf(String string) throws NumberFormatException { 264 return valueOf(parseByte(string)); 265 } 266 267 /** 268 * Parses the specified string as a signed byte value using the specified 269 * radix. 270 * 271 * @param string 272 * the string representation of a single byte value. 273 * @param radix 274 * the radix to use when parsing. 275 * @return a {@code Byte} instance containing the byte value represented by 276 * {@code string} using {@code radix}. 277 * @throws NumberFormatException 278 * if {@code string} can not be parsed as a byte value, or 279 * {@code radix < Character.MIN_RADIX || 280 * radix > Character.MAX_RADIX}. 281 * @see #parseByte(String, int) 282 */ valueOf(String string, int radix)283 public static Byte valueOf(String string, int radix) throws NumberFormatException { 284 return valueOf(parseByte(string, radix)); 285 } 286 287 /** 288 * Returns a {@code Byte} instance for the specified byte value. 289 * <p> 290 * If it is not necessary to get a new {@code Byte} instance, it is 291 * recommended to use this method instead of the constructor, since it 292 * maintains a cache of instances which may result in better performance. 293 * 294 * @param b 295 * the byte value to store in the instance. 296 * @return a {@code Byte} instance containing {@code b}. 297 * @since 1.5 298 */ valueOf(byte b)299 public static Byte valueOf(byte b) { 300 return VALUES[b + 128]; 301 } 302 303 /** 304 * A cache of instances used by {@link Byte#valueOf(byte)} and auto-boxing 305 */ 306 private static final Byte[] VALUES = new Byte[256]; 307 308 static { 309 for (int i = -128; i < 128; i++) { 310 VALUES[i + 128] = new Byte((byte) i); 311 } 312 } 313 } 314