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    
092    
093      /**
094       * The immutable value of this Byte.
095       *
096       * @serial the wrapped byte
097       */
098      private final byte value;
099    
100      /**
101       * Create a <code>Byte</code> object representing the value of the
102       * <code>byte</code> argument.
103       *
104       * @param value the value to use
105       */
106      public Byte(byte value)
107      {
108        this.value = value;
109      }
110    
111      /**
112       * Create a <code>Byte</code> object representing the value specified
113       * by the <code>String</code> argument
114       *
115       * @param s the string to convert
116       * @throws NumberFormatException if the String does not contain a byte
117       * @see #valueOf(String)
118       */
119      public Byte(String s)
120      {
121        value = parseByte(s, 10);
122      }
123    
124      /**
125       * Converts the <code>byte</code> to a <code>String</code> and assumes
126       * a radix of 10.
127       *
128       * @param b the <code>byte</code> to convert to <code>String</code>
129       * @return the <code>String</code> representation of the argument
130       */
131      public static String toString(byte b)
132      {
133        return String.valueOf(b);
134      }
135    
136      /**
137       * Converts the specified <code>String</code> into a <code>byte</code>.
138       * This function assumes a radix of 10.
139       *
140       * @param s the <code>String</code> to convert
141       * @return the <code>byte</code> value of <code>s</code>
142       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
143       *         <code>byte</code>
144       * @see #parseByte(String)
145       */
146      public static byte parseByte(String s)
147      {
148        return parseByte(s, 10);
149      }
150    
151      /**
152       * Converts the specified <code>String</code> into an <code>int</code>
153       * using the specified radix (base). The string must not be <code>null</code>
154       * or empty. It may begin with an optional '-', which will negate the answer,
155       * provided that there are also valid digits. Each digit is parsed as if by
156       * <code>Character.digit(d, radix)</code>, and must be in the range
157       * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
158       * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
159       * Unlike Double.parseDouble, you may not have a leading '+'.
160       *
161       * @param s the <code>String</code> to convert
162       * @param radix the radix (base) to use in the conversion
163       * @return the <code>String</code> argument converted to <code>byte</code>
164       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
165       *         <code>byte</code>
166       */
167      public static byte parseByte(String s, int radix)
168      {
169        int i = Integer.parseInt(s, radix, false);
170        if ((byte) i != i)
171          throw new NumberFormatException();
172        return (byte) i;
173      }
174    
175      /**
176       * Creates a new <code>Byte</code> object using the <code>String</code>
177       * and specified radix (base).
178       *
179       * @param s the <code>String</code> to convert
180       * @param radix the radix (base) to convert with
181       * @return the new <code>Byte</code>
182       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
183       *         <code>byte</code>
184       * @see #parseByte(String, int)
185       */
186      public static Byte valueOf(String s, int radix)
187      {
188        return new Byte(parseByte(s, radix));
189      }
190    
191      /**
192       * Creates a new <code>Byte</code> object using the <code>String</code>,
193       * assuming a radix of 10.
194       *
195       * @param s the <code>String</code> to convert
196       * @return the new <code>Byte</code>
197       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
198       *         <code>byte</code>
199       * @see #Byte(String)
200       * @see #parseByte(String)
201       */
202      public static Byte valueOf(String s)
203      {
204        return new Byte(parseByte(s, 10));
205      }
206    
207      /**
208       * Returns a <code>Byte</code> object wrapping the value.
209       * In contrast to the <code>Byte</code> constructor, this method
210       * will cache some values.  It is used by boxing conversion.
211       *
212       * @param val the value to wrap
213       * @return the <code>Byte</code>
214       */
215      public static Byte valueOf(byte val)
216      {
217        synchronized (byteCache)
218          {
219            if (byteCache[val - MIN_VALUE] == null)
220              byteCache[val - MIN_VALUE] = new Byte(val);
221            return byteCache[val - MIN_VALUE];
222          }
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 new Byte((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    }