001/* Byte.java -- object wrapper for byte
002   Copyright (C) 1998, 2001, 2002, 2004, 2005 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package 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 */
057public 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  static
092  {
093    for (int i=MIN_VALUE; i <= MAX_VALUE; i++)
094      byteCache[i - MIN_VALUE] = new Byte((byte) i);
095  }
096
097
098  /**
099   * The immutable value of this Byte.
100   *
101   * @serial the wrapped byte
102   */
103  private final byte value;
104
105  /**
106   * Create a <code>Byte</code> object representing the value of the
107   * <code>byte</code> argument.
108   *
109   * @param value the value to use
110   */
111  public Byte(byte value)
112  {
113    this.value = value;
114  }
115
116  /**
117   * Create a <code>Byte</code> object representing the value specified
118   * by the <code>String</code> argument
119   *
120   * @param s the string to convert
121   * @throws NumberFormatException if the String does not contain a byte
122   * @see #valueOf(String)
123   */
124  public Byte(String s)
125  {
126    value = parseByte(s, 10);
127  }
128
129  /**
130   * Converts the <code>byte</code> to a <code>String</code> and assumes
131   * a radix of 10.
132   *
133   * @param b the <code>byte</code> to convert to <code>String</code>
134   * @return the <code>String</code> representation of the argument
135   */
136  public static String toString(byte b)
137  {
138    return String.valueOf(b);
139  }
140
141  /**
142   * Converts the specified <code>String</code> into a <code>byte</code>.
143   * This function assumes a radix of 10.
144   *
145   * @param s the <code>String</code> to convert
146   * @return the <code>byte</code> value of <code>s</code>
147   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
148   *         <code>byte</code>
149   * @see #parseByte(String)
150   */
151  public static byte parseByte(String s)
152  {
153    return parseByte(s, 10);
154  }
155
156  /**
157   * Converts the specified <code>String</code> into an <code>int</code>
158   * using the specified radix (base). The string must not be <code>null</code>
159   * or empty. It may begin with an optional '-', which will negate the answer,
160   * provided that there are also valid digits. Each digit is parsed as if by
161   * <code>Character.digit(d, radix)</code>, and must be in the range
162   * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
163   * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
164   * Unlike Double.parseDouble, you may not have a leading '+'.
165   *
166   * @param s the <code>String</code> to convert
167   * @param radix the radix (base) to use in the conversion
168   * @return the <code>String</code> argument converted to <code>byte</code>
169   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
170   *         <code>byte</code>
171   */
172  public static byte parseByte(String s, int radix)
173  {
174    int i = Integer.parseInt(s, radix, false);
175    if ((byte) i != i)
176      throw new NumberFormatException();
177    return (byte) i;
178  }
179
180  /**
181   * Creates a new <code>Byte</code> object using the <code>String</code>
182   * and specified radix (base).
183   *
184   * @param s the <code>String</code> to convert
185   * @param radix the radix (base) to convert with
186   * @return the new <code>Byte</code>
187   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
188   *         <code>byte</code>
189   * @see #parseByte(String, int)
190   */
191  public static Byte valueOf(String s, int radix)
192  {
193    return valueOf(parseByte(s, radix));
194  }
195
196  /**
197   * Creates a new <code>Byte</code> object using the <code>String</code>,
198   * assuming a radix of 10.
199   *
200   * @param s the <code>String</code> to convert
201   * @return the new <code>Byte</code>
202   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
203   *         <code>byte</code>
204   * @see #Byte(String)
205   * @see #parseByte(String)
206   */
207  public static Byte valueOf(String s)
208  {
209    return valueOf(parseByte(s, 10));
210  }
211
212  /**
213   * Returns a <code>Byte</code> object wrapping the value.
214   * In contrast to the <code>Byte</code> constructor, this method
215   * will cache some values.  It is used by boxing conversion.
216   *
217   * @param val the value to wrap
218   * @return the <code>Byte</code>
219   */
220  public static Byte valueOf(byte val)
221  {
222    return byteCache[val - MIN_VALUE];
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 valueOf((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}