libcore/luni/src/main/java/java/lang/Byte.java

   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 public final class Byte extends Number implements Comparable<Byte> {
  26
  27     private static final long serialVersionUID = -7183698231559129828L;
  28
  29     /**
  30      * The value which the receiver represents.
  31      */
  32     private final byte value;
  33
  34     /**
  35      * The maximum {@code Byte} value, 2<sup>7</sup>-1.
  36      */
  37     public static final byte MAX_VALUE = (byte) 0x7F;
  38
  39     /**
  40      * The minimum {@code Byte} value, -2<sup>7</sup>.
  41      */
  42     public static final byte MIN_VALUE = (byte) 0x80;
  43
  44     /**
  45      * The number of bits needed to represent a {@code Byte} value in two's
  46      * complement form.
  47      *
  48      * @since 1.5
  49      */
  50     public static final int SIZE = 8;
  51
  52     /**
  53      * The {@link Class} object that represents the primitive type {@code byte}.
  54      */
  55     @SuppressWarnings("unchecked")
  56     public static final Class<Byte> TYPE
  57             = (Class<Byte>) byte[].class.getComponentType();
  58     // Note: This can't be set to "byte.class", since *that* is
  59     // defined to be "java.lang.Byte.TYPE";
  60
  61     /**
  62      * Constructs a new {@code Byte} with the specified primitive byte value.
  63      *
  64      * @param value
  65      *            the primitive byte value to store in the new instance.
  66      */
  67     public Byte(byte value) {
  68         this.value = value;
  69     }
  70
  71     /**
  72      * Constructs a new {@code Byte} from the specified string.
  73      *
  74      * @param string
  75      *            the string representation of a single byte value.
  76      * @throws NumberFormatException
  77      *             if {@code string} can not be decoded into a byte value.
  78      * @see #parseByte(String)
  79      */
  80     public Byte(String string) throws NumberFormatException {
  81         this(parseByte(string));
  82     }
  83
  84     /**
  85      * Gets the primitive value of this byte.
  86      *
  87      * @return this object's primitive value.
  88      */
  89     @Override
  90     public byte byteValue() {
  91         return value;
  92     }
  93
  94     /**
  95      * Compares this object to the specified byte object to determine their
  96      * relative order.
  97      *
  98      * @param object
  99      *            the byte object to compare this object to.
 100      * @return a negative value if the value of this byte is less than the value
 101      *         of {@code object}; 0 if the value of this byte and the value of
 102      *         {@code object} are equal; a positive value if the value of this
 103      *         byte is greater than the value of {@code object}.
 104      * @see java.lang.Comparable
 105      * @since 1.2
 106      */
 107     public int compareTo(Byte object) {
 108         return value > object.value ? 1 : (value < object.value ? -1 : 0);
 109     }
 110
 111     /**
 112      * Parses the specified string and returns a {@code Byte} instance if the
 113      * string can be decoded into a single byte value. The string may be an
 114      * optional minus sign "-" followed by a hexadecimal ("0x..." or "#..."),
 115      * octal ("0..."), or decimal ("...") representation of a byte.
 116      *
 117      * @param string
 118      *            a string representation of a single byte value.
 119      * @return a {@code Byte} containing the value represented by {@code string}.
 120      * @throws NumberFormatException
 121      *             if {@code string} can not be parsed as a byte value.
 122      */
 123     public static Byte decode(String string) throws NumberFormatException {
 124         int intValue = Integer.decode(string).intValue();
 125         byte result = (byte) intValue;
 126         if (result == intValue) {
 127             return valueOf(result);
 128         }
 129         throw new NumberFormatException();
 130     }
 131
 132     @Override
 133     public double doubleValue() {
 134         return value;
 135     }
 136
 137     /**
 138      * Compares this object with the specified object and indicates if they are
 139      * equal. In order to be equal, {@code object} must be an instance of
 140      * {@code Byte} and have the same byte value as this object.
 141      *
 142      * @param object
 143      *            the object to compare this byte with.
 144      * @return {@code true} if the specified object is equal to this
 145      *         {@code Byte}; {@code false} otherwise.
 146      */
 147     @Override
 148     public boolean equals(Object object) {
 149         return (object == this) || (object instanceof Byte)
 150                 && (value == ((Byte) object).value);
 151     }
 152
 153     @Override
 154     public float floatValue() {
 155         return value;
 156     }
 157
 158     @Override
 159     public int hashCode() {
 160         return value;
 161     }
 162
 163     @Override
 164     public int intValue() {
 165         return value;
 166     }
 167
 168     @Override
 169     public long longValue() {
 170         return value;
 171     }
 172
 173     /**
 174      * Parses the specified string as a signed decimal byte value. The ASCII
 175      * character \u002d ('-') is recognized as the minus sign.
 176      *
 177      * @param string
 178      *            the string representation of a single byte value.
 179      * @return the primitive byte value represented by {@code string}.
 180      * @throws NumberFormatException
 181      *             if {@code string} is {@code null}, has a length of zero or
 182      *             can not be parsed as a byte value.
 183      */
 184     public static byte parseByte(String string) throws NumberFormatException {
 185         int intValue = Integer.parseInt(string);
 186         byte result = (byte) intValue;
 187         if (result == intValue) {
 188             return result;
 189         }
 190         throw new NumberFormatException();
 191     }
 192
 193     /**
 194      * Parses the specified string as a signed byte value using the specified
 195      * radix. The ASCII character \u002d ('-') is recognized as the minus sign.
 196      *
 197      * @param string
 198      *            the string representation of a single byte value.
 199      * @param radix
 200      *            the radix to use when parsing.
 201      * @return the primitive byte value represented by {@code string} using
 202      *         {@code radix}.
 203      * @throws NumberFormatException
 204      *             if {@code string} is {@code null} or has a length of zero,
 205      *             {@code radix < Character.MIN_RADIX},
 206      *             {@code radix > Character.MAX_RADIX}, or if {@code string}
 207      *             can not be parsed as a byte value.
 208      */
 209     public static byte parseByte(String string, int radix)
 210             throws NumberFormatException {
 211         int intValue = Integer.parseInt(string, radix);
 212         byte result = (byte) intValue;
 213         if (result == intValue) {
 214             return result;
 215         }
 216         throw new NumberFormatException();
 217     }
 218
 219     @Override
 220     public short shortValue() {
 221         return value;
 222     }
 223
 224     @Override
 225     public String toString() {
 226         return Integer.toString(value);
 227     }
 228
 229     /**
 230      * Returns a string containing a concise, human-readable description of the
 231      * specified byte value.
 232      *
 233      * @param value
 234      *            the byte to convert to a string.
 235      * @return a printable representation of {@code value}.
 236      */
 237     public static String toString(byte value) {
 238         return Integer.toString(value);
 239     }
 240
 241     /**
 242      * Parses the specified string as a signed decimal byte value.
 243      *
 244      * @param string
 245      *            the string representation of a single byte value.
 246      * @return a {@code Byte} instance containing the byte value represented by
 247      *         {@code string}.
 248      * @throws NumberFormatException
 249      *             if {@code string} is {@code null}, has a length of zero or
 250      *             can not be parsed as a byte value.
 251      * @see #parseByte(String)
 252      */
 253     public static Byte valueOf(String string) throws NumberFormatException {
 254         return valueOf(parseByte(string));
 255     }
 256
 257     /**
 258      * Parses the specified string as a signed byte value using the specified
 259      * radix.
 260      *
 261      * @param string
 262      *            the string representation of a single byte value.
 263      * @param radix
 264      *            the radix to use when parsing.
 265      * @return a {@code Byte} instance containing the byte value represented by
 266      *         {@code string} using {@code radix}.
 267      * @throws NumberFormatException
 268      *             if {@code string} is {@code null} or has a length of zero,
 269      *             {@code radix < Character.MIN_RADIX},
 270      *             {@code radix > Character.MAX_RADIX}, or if {@code string}
 271      *             can not be parsed as a byte value.
 272      * @see #parseByte(String, int)
 273      */
 274     public static Byte valueOf(String string, int radix)
 275             throws NumberFormatException {
 276         return valueOf(parseByte(string, radix));
 277     }
 278
 279     /**
 280      * Returns a {@code Byte} instance for the specified byte value.
 281      * <p>
 282      * If it is not necessary to get a new {@code Byte} instance, it is
 283      * recommended to use this method instead of the constructor, since it
 284      * maintains a cache of instances which may result in better performance.
 285      *
 286      * @param b
 287      *            the byte value to store in the instance.
 288      * @return a {@code Byte} instance containing {@code b}.
 289      * @since 1.5
 290      */
 291     public static Byte valueOf(byte b) {
 292         return VALUES[b + 128];
 293     }
 294
 295     /**
 296      * A cache of instances used by {@link Byte#valueOf(byte)} and auto-boxing
 297      */
 298     private static final Byte[] VALUES = new Byte[256];
 299
 300     static {
 301         for (int i = -128; i < 128; i++) {
 302             VALUES[i + 128] = new Byte((byte) i);
 303         }
 304     }
 305 }