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      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    }