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 */ 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 */ 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 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 */ 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 */ 117 public static int compare(byte lhs, byte rhs) { 118 return lhs > rhs ? 1 : (lhs < rhs ? -1 : 0); 119 } 120 121 /** 122 * Parses the specified string and returns a {@code Byte} instance if the 123 * string can be decoded into a single byte value. The string may be an 124 * optional minus sign "-" followed by a hexadecimal ("0x..." or "#..."), 125 * octal ("0..."), or decimal ("...") representation of a byte. 126 * 127 * @param string 128 * a string representation of a single byte value. 129 * @return a {@code Byte} containing the value represented by {@code string}. 130 * @throws NumberFormatException 131 * if {@code string} cannot be parsed as a byte value. 132 */ 133 public static Byte decode(String string) throws NumberFormatException { 134 int intValue = Integer.decode(string); 135 byte result = (byte) intValue; 136 if (result == intValue) { 137 return valueOf(result); 138 } 139 throw new NumberFormatException("Value out of range for byte: \"" + string + "\""); 140 } 141 142 @Override 143 public double doubleValue() { 144 return value; 145 } 146 147 /** 148 * Compares this object with the specified object and indicates if they are 149 * equal. In order to be equal, {@code object} must be an instance of 150 * {@code Byte} and have the same byte value as this object. 151 * 152 * @param object 153 * the object to compare this byte with. 154 * @return {@code true} if the specified object is equal to this 155 * {@code Byte}; {@code false} otherwise. 156 */ 157 @Override 158 @FindBugsSuppressWarnings("RC_REF_COMPARISON") 159 public boolean equals(Object object) { 160 return (object == this) || ((object instanceof Byte) && (((Byte) object).value == value)); 161 } 162 163 @Override 164 public float floatValue() { 165 return value; 166 } 167 168 @Override 169 public int hashCode() { 170 return value; 171 } 172 173 @Override 174 public int intValue() { 175 return value; 176 } 177 178 @Override 179 public long longValue() { 180 return value; 181 } 182 183 /** 184 * Parses the specified string as a signed decimal byte value. The ASCII 185 * character \u002d ('-') is recognized as the minus sign. 186 * 187 * @param string 188 * the string representation of a single byte value. 189 * @return the primitive byte value represented by {@code string}. 190 * @throws NumberFormatException 191 * if {@code string} can not be parsed as a byte value. 192 */ 193 public static byte parseByte(String string) throws NumberFormatException { 194 return parseByte(string, 10); 195 } 196 197 /** 198 * Parses the specified string as a signed byte value using the specified 199 * radix. The ASCII character \u002d ('-') is recognized as the minus sign. 200 * 201 * @param string 202 * the string representation of a single byte value. 203 * @param radix 204 * the radix to use when parsing. 205 * @return the primitive byte value represented by {@code string} using 206 * {@code radix}. 207 * @throws NumberFormatException 208 * if {@code string} can not be parsed as a byte value, or 209 * {@code radix < Character.MIN_RADIX || 210 * radix > Character.MAX_RADIX}. 211 */ 212 public static byte parseByte(String string, int radix) throws NumberFormatException { 213 int intValue = Integer.parseInt(string, radix); 214 byte result = (byte) intValue; 215 if (result == intValue) { 216 return result; 217 } 218 throw new NumberFormatException("Value out of range for byte: \"" + string + "\""); 219 } 220 221 @Override 222 public short shortValue() { 223 return value; 224 } 225 226 @Override 227 public String toString() { 228 return Integer.toString(value); 229 } 230 231 /** 232 * Returns a two-digit hex string. That is, -1 becomes "ff" or "FF" and 2 becomes "02". 233 * @hide internal use only 234 */ 235 public static String toHexString(byte b, boolean upperCase) { 236 return IntegralToString.byteToHexString(b, upperCase); 237 } 238 239 /** 240 * Returns a string containing a concise, human-readable description of the 241 * specified byte value. 242 * 243 * @param value 244 * the byte to convert to a string. 245 * @return a printable representation of {@code value}. 246 */ 247 public static String toString(byte value) { 248 return Integer.toString(value); 249 } 250 251 /** 252 * Parses the specified string as a signed decimal byte value. 253 * 254 * @param string 255 * the string representation of a single byte value. 256 * @return a {@code Byte} instance containing the byte value represented by 257 * {@code string}. 258 * @throws NumberFormatException 259 * if {@code string} can not be parsed as a byte value. 260 * @see #parseByte(String) 261 */ 262 public static Byte valueOf(String string) throws NumberFormatException { 263 return valueOf(parseByte(string)); 264 } 265 266 /** 267 * Parses the specified string as a signed byte value using the specified 268 * radix. 269 * 270 * @param string 271 * the string representation of a single byte value. 272 * @param radix 273 * the radix to use when parsing. 274 * @return a {@code Byte} instance containing the byte value represented by 275 * {@code string} using {@code radix}. 276 * @throws NumberFormatException 277 * if {@code string} can not be parsed as a byte value, or 278 * {@code radix < Character.MIN_RADIX || 279 * radix > Character.MAX_RADIX}. 280 * @see #parseByte(String, int) 281 */ 282 public static Byte valueOf(String string, int radix) throws NumberFormatException { 283 return valueOf(parseByte(string, radix)); 284 } 285 286 /** 287 * Returns a {@code Byte} instance for the specified byte value. 288 * <p> 289 * If it is not necessary to get a new {@code Byte} instance, it is 290 * recommended to use this method instead of the constructor, since it 291 * maintains a cache of instances which may result in better performance. 292 * 293 * @param b 294 * the byte value to store in the instance. 295 * @return a {@code Byte} instance containing {@code b}. 296 * @since 1.5 297 */ 298 public static Byte valueOf(byte b) { 299 return VALUES[b + 128]; 300 } 301 302 /** 303 * A cache of instances used by {@link Byte#valueOf(byte)} and auto-boxing 304 */ 305 private static final Byte[] VALUES = new Byte[256]; 306 307 static { 308 for (int i = -128; i < 128; i++) { 309 VALUES[i + 128] = new Byte((byte) i); 310 } 311 } 312 } 313
