1 /* Byte.java -- object wrapper for byte
2    Copyright (C) 1998, 2001, 2002 Free Software Foundation, Inc.
3 
4 This file is part of GNU Classpath.
5 
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10 
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15 
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING.  If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
19 02111-1307 USA.
20 
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library.  Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
25 
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module.  An independent module is a module which is not derived from
33 or based on this library.  If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so.  If you do not wish to do so, delete this
36 exception statement from your version. */
37 
38 
39 package java.lang;
40 
41 /**
42  * Instances of class <code>Byte</code> represent primitive <code>byte</code>
43  * values.
44  *
45  * Additionally, this class provides various helper functions and variables
46  * useful to bytes.
47  *
48  * @author Paul Fisher
49  * @author John Keiser
50  * @author Per Bothner
51  * @author Eric Blake <ebb9@email.byu.edu>
52  * @since 1.1
53  * @status updated to 1.4
54  */
55 public final class Byte extends Number implements Comparable
56 {
57   /**
58    * Compatible with JDK 1.1+.
59    */
60   private static final long serialVersionUID = -7183698231559129828L;
61 
62   /**
63    * The minimum value a <code>byte</code> can represent is -128 (or
64    * -2<sup>7</sup>).
65    */
66   public static final byte MIN_VALUE = -128;
67 
68   /**
69    * The maximum value a <code>byte</code> can represent is 127 (or
70    * 2<sup>7</sup> - 1).
71    */
72   public static final byte MAX_VALUE = 127;
73 
74   /**
75    * The primitive type <code>byte</code> is represented by this
76    * <code>Class</code> object.
77    */
78   public static final Class TYPE = VMClassLoader.getPrimitiveClass('B');
79 
80   /**
81    * The immutable value of this Byte.
82    *
83    * @serial the wrapped byte
84    */
85   private final byte value;
86 
87   /**
88    * Create a <code>Byte</code> object representing the value of the
89    * <code>byte</code> argument.
90    *
91    * @param value the value to use
92    */
Byte(byte value)93   public Byte(byte value)
94   {
95     this.value = value;
96   }
97 
98   /**
99    * Create a <code>Byte</code> object representing the value specified
100    * by the <code>String</code> argument
101    *
102    * @param s the string to convert
103    * @throws NumberFormatException if the String does not contain a byte
104    * @see #valueOf(String)
105    */
Byte(String s)106   public Byte(String s)
107   {
108     value = parseByte(s, 10);
109   }
110 
111   /**
112    * Converts the <code>byte</code> to a <code>String</code> and assumes
113    * a radix of 10.
114    *
115    * @param b the <code>byte</code> to convert to <code>String</code>
116    * @return the <code>String</code> representation of the argument
117    */
toString(byte b)118   public static String toString(byte b)
119   {
120     return String.valueOf(b);
121   }
122 
123   /**
124    * Converts the specified <code>String</code> into a <code>byte</code>.
125    * This function assumes a radix of 10.
126    *
127    * @param s the <code>String</code> to convert
128    * @return the <code>byte</code> value of <code>s</code>
129    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
130    *         <code>byte</code>
131    * @see #parseByte(String)
132    */
parseByte(String s)133   public static byte parseByte(String s)
134   {
135     return parseByte(s, 10);
136   }
137 
138   /**
139    * Converts the specified <code>String</code> into an <code>int</code>
140    * using the specified radix (base). The string must not be <code>null</code>
141    * or empty. It may begin with an optional '-', which will negate the answer,
142    * provided that there are also valid digits. Each digit is parsed as if by
143    * <code>Character.digit(d, radix)</code>, and must be in the range
144    * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
145    * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
146    * Unlike Double.parseDouble, you may not have a leading '+'.
147    *
148    * @param s the <code>String</code> to convert
149    * @param radix the radix (base) to use in the conversion
150    * @return the <code>String</code> argument converted to </code>byte</code>
151    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
152    *         <code>byte</code>
153    */
parseByte(String s, int radix)154   public static byte parseByte(String s, int radix)
155   {
156     int i = Integer.parseInt(s, radix, false);
157     if ((byte) i != i)
158       throw new NumberFormatException();
159     return (byte) i;
160   }
161 
162   /**
163    * Creates a new <code>Byte</code> object using the <code>String</code>
164    * and specified radix (base).
165    *
166    * @param s the <code>String</code> to convert
167    * @param radix the radix (base) to convert with
168    * @return the new <code>Byte</code>
169    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
170    *         <code>byte</code>
171    * @see #parseByte(String, int)
172    */
valueOf(String s, int radix)173   public static Byte valueOf(String s, int radix)
174   {
175     return new Byte(parseByte(s, radix));
176   }
177 
178   /**
179    * Creates a new <code>Byte</code> object using the <code>String</code>,
180    * assuming a radix of 10.
181    *
182    * @param s the <code>String</code> to convert
183    * @return the new <code>Byte</code>
184    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
185    *         <code>byte</code>
186    * @see #Byte(String)
187    * @see #parseByte(String)
188    */
valueOf(String s)189   public static Byte valueOf(String s)
190   {
191     return new Byte(parseByte(s, 10));
192   }
193 
194   /**
195    * Convert the specified <code>String</code> into a <code>Byte</code>.
196    * The <code>String</code> may represent decimal, hexadecimal, or
197    * octal numbers.
198    *
199    * <p>The extended BNF grammar is as follows:<br>
200    * <pre>
201    * <em>DecodableString</em>:
202    *      ( [ <code>-</code> ] <em>DecimalNumber</em> )
203    *    | ( [ <code>-</code> ] ( <code>0x</code> | <code>0X</code>
204    *              | <code>#</code> ) { <em>HexDigit</em> }+ )
205    *    | ( [ <code>-</code> ] <code>0</code> { <em>OctalDigit</em> } )
206    * <em>DecimalNumber</em>:
207    *        <em>DecimalDigit except '0'</em> { <em>DecimalDigit</em> }
208    * <em>DecimalDigit</em>:
209    *        <em>Character.digit(d, 10) has value 0 to 9</em>
210    * <em>OctalDigit</em>:
211    *        <em>Character.digit(d, 8) has value 0 to 7</em>
212    * <em>DecimalDigit</em>:
213    *        <em>Character.digit(d, 16) has value 0 to 15</em>
214    * </pre>
215    * Finally, the value must be in the range <code>MIN_VALUE</code> to
216    * <code>MAX_VALUE</code>, or an exception is thrown.
217    *
218    * @param s the <code>String</code> to interpret
219    * @return the value of the String as a <code>Byte</code>
220    * @throws NumberFormatException if <code>s</code> cannot be parsed as a
221    *         <code>byte</code>
222    * @throws NullPointerException if <code>s</code> is null
223    * @see Integer#decode(String)
224    */
decode(String s)225   public static Byte decode(String s)
226   {
227     int i = Integer.parseInt(s, 10, true);
228     if ((byte) i != i)
229       throw new NumberFormatException();
230     return new Byte((byte) i);
231   }
232 
233   /**
234    * Return the value of this <code>Byte</code>.
235    *
236    * @return the byte value
237    */
byteValue()238   public byte byteValue()
239   {
240     return value;
241   }
242 
243   /**
244    * Return the value of this <code>Byte</code> as a <code>short</code>.
245    *
246    * @return the short value
247    */
shortValue()248   public short shortValue()
249   {
250     return value;
251   }
252 
253   /**
254    * Return the value of this <code>Byte</code> as an <code>int</code>.
255    *
256    * @return the int value
257    */
intValue()258   public int intValue()
259   {
260     return value;
261   }
262 
263   /**
264    * Return the value of this <code>Byte</code> as a <code>long</code>.
265    *
266    * @return the long value
267    */
longValue()268   public long longValue()
269   {
270     return value;
271   }
272 
273   /**
274    * Return the value of this <code>Byte</code> as a <code>float</code>.
275    *
276    * @return the float value
277    */
floatValue()278   public float floatValue()
279   {
280     return value;
281   }
282 
283   /**
284    * Return the value of this <code>Byte</code> as a <code>double</code>.
285    *
286    * @return the double value
287    */
doubleValue()288   public double doubleValue()
289   {
290     return value;
291   }
292 
293   /**
294    * Converts the <code>Byte</code> value to a <code>String</code> and
295    * assumes a radix of 10.
296    *
297    * @return the <code>String</code> representation of this <code>Byte</code>
298    * @see Integer#toString()
299    */
toString()300   public String toString()
301   {
302     return String.valueOf(value);
303   }
304 
305   /**
306    * Return a hashcode representing this Object. <code>Byte</code>'s hash
307    * code is simply its value.
308    *
309    * @return this Object's hash code
310    */
hashCode()311   public int hashCode()
312   {
313     return value;
314   }
315 
316   /**
317    * Returns <code>true</code> if <code>obj</code> is an instance of
318    * <code>Byte</code> and represents the same byte value.
319    *
320    * @param obj the object to compare
321    * @return whether these Objects are semantically equal
322    */
equals(Object obj)323   public boolean equals(Object obj)
324   {
325     return obj instanceof Byte && value == ((Byte) obj).value;
326   }
327 
328   /**
329    * Compare two Bytes numerically by comparing their <code>byte</code> values.
330    * The result is positive if the first is greater, negative if the second
331    * is greater, and 0 if the two are equal.
332    *
333    * @param b the Byte to compare
334    * @return the comparison
335    * @since 1.2
336    */
compareTo(Byte b)337   public int compareTo(Byte b)
338   {
339     return value - b.value;
340   }
341 
342   /**
343    * Behaves like <code>compareTo(Byte)</code> unless the Object
344    * is not a <code>Byte</code>.
345    *
346    * @param o the object to compare
347    * @return the comparison
348    * @throws ClassCastException if the argument is not a <code>Byte</code>
349    * @see #compareTo(Byte)
350    * @see Comparable
351    * @since 1.2
352    */
compareTo(Object o)353   public int compareTo(Object o)
354   {
355     return compareTo((Byte) o);
356   }
357 }
358