001    /* Short.java -- object wrapper for short
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>Short</code> represent primitive
043     * <code>short</code> values.
044     *
045     * Additionally, this class provides various helper functions and variables
046     * related to shorts.
047     *
048     * @author Paul Fisher
049     * @author John Keiser
050     * @author Eric Blake (ebb9@email.byu.edu)
051     * @author Tom Tromey (tromey@redhat.com)
052     * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
053     * @since 1.1
054     * @status updated to 1.5
055     */
056    public final class Short extends Number implements Comparable<Short>
057    {
058      /**
059       * Compatible with JDK 1.1+.
060       */
061      private static final long serialVersionUID = 7515723908773894738L;
062    
063      /**
064       * The minimum value a <code>short</code> can represent is -32768 (or
065       * -2<sup>15</sup>).
066       */
067      public static final short MIN_VALUE = -32768;
068    
069      /**
070       * The minimum value a <code>short</code> can represent is 32767 (or
071       * 2<sup>15</sup>).
072       */
073      public static final short MAX_VALUE = 32767;
074    
075      /**
076       * The primitive type <code>short</code> is represented by this
077       * <code>Class</code> object.
078       */
079      public static final Class<Short> TYPE = (Class<Short>) VMClassLoader.getPrimitiveClass('S');
080    
081      /**
082       * The number of bits needed to represent a <code>short</code>.
083       * @since 1.5
084       */
085      public static final int SIZE = 16;
086    
087      // This caches some Short values, and is used by boxing conversions
088      // via valueOf().  We must cache at least -128..127; these constants
089      // control how much we actually cache.
090      private static final int MIN_CACHE = -128;
091      private static final int MAX_CACHE = 127;
092      private static Short[] shortCache = new Short[MAX_CACHE - MIN_CACHE + 1];
093    
094      /**
095       * The immutable value of this Short.
096       *
097       * @serial the wrapped short
098       */
099      private final short value;
100    
101      /**
102       * Create a <code>Short</code> object representing the value of the
103       * <code>short</code> argument.
104       *
105       * @param value the value to use
106       */
107      public Short(short value)
108      {
109        this.value = value;
110      }
111    
112      /**
113       * Create a <code>Short</code> object representing the value of the
114       * argument after conversion to a <code>short</code>.
115       *
116       * @param s the string to convert
117       * @throws NumberFormatException if the String cannot be parsed
118       */
119      public Short(String s)
120      {
121        value = parseShort(s, 10);
122      }
123    
124      /**
125       * Converts the <code>short</code> to a <code>String</code> and assumes
126       * a radix of 10.
127       *
128       * @param s the <code>short</code> to convert to <code>String</code>
129       * @return the <code>String</code> representation of the argument
130       */
131      public static String toString(short s)
132      {
133        return String.valueOf(s);
134      }
135    
136      /**
137       * Converts the specified <code>String</code> into a <code>short</code>.
138       * This function assumes a radix of 10.
139       *
140       * @param s the <code>String</code> to convert
141       * @return the <code>short</code> value of <code>s</code>
142       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
143       *         <code>short</code>
144       */
145      public static short parseShort(String s)
146      {
147        return parseShort(s, 10);
148      }
149    
150      /**
151       * Converts the specified <code>String</code> into a <code>short</code>
152       * using the specified radix (base). The string must not be <code>null</code>
153       * or empty. It may begin with an optional '-', which will negate the answer,
154       * provided that there are also valid digits. Each digit is parsed as if by
155       * <code>Character.digit(d, radix)</code>, and must be in the range
156       * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
157       * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
158       * Unlike Double.parseDouble, you may not have a leading '+'.
159       *
160       * @param s the <code>String</code> to convert
161       * @param radix the radix (base) to use in the conversion
162       * @return the <code>String</code> argument converted to <code>short</code>
163       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
164       *         <code>short</code>
165       */
166      public static short parseShort(String s, int radix)
167      {
168        int i = Integer.parseInt(s, radix, false);
169        if ((short) i != i)
170          throw new NumberFormatException();
171        return (short) i;
172      }
173    
174      /**
175       * Creates a new <code>Short</code> object using the <code>String</code>
176       * and specified radix (base).
177       *
178       * @param s the <code>String</code> to convert
179       * @param radix the radix (base) to convert with
180       * @return the new <code>Short</code>
181       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
182       *         <code>short</code>
183       * @see #parseShort(String, int)
184       */
185      public static Short valueOf(String s, int radix)
186      {
187        return new Short(parseShort(s, radix));
188      }
189    
190      /**
191       * Creates a new <code>Short</code> object using the <code>String</code>,
192       * assuming a radix of 10.
193       *
194       * @param s the <code>String</code> to convert
195       * @return the new <code>Short</code>
196       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
197       *         <code>short</code>
198       * @see #Short(String)
199       * @see #parseShort(String)
200       */
201      public static Short valueOf(String s)
202      {
203        return new Short(parseShort(s, 10));
204      }
205    
206      /**
207       * Returns a <code>Short</code> object wrapping the value.
208       * In contrast to the <code>Short</code> constructor, this method
209       * will cache some values.  It is used by boxing conversion.
210       *
211       * @param val the value to wrap
212       * @return the <code>Short</code>
213       * @since 1.5
214       */
215      public static Short valueOf(short val)
216      {
217        if (val < MIN_CACHE || val > MAX_CACHE)
218          return new Short(val);
219        synchronized (shortCache)
220          {
221            if (shortCache[val - MIN_CACHE] == null)
222              shortCache[val - MIN_CACHE] = new Short(val);
223            return shortCache[val - MIN_CACHE];
224          }
225      }
226    
227      /**
228       * Convert the specified <code>String</code> into a <code>Short</code>.
229       * The <code>String</code> may represent decimal, hexadecimal, or
230       * octal numbers.
231       *
232       * <p>The extended BNF grammar is as follows:<br>
233       * <pre>
234       * <em>DecodableString</em>:
235       *      ( [ <code>-</code> ] <em>DecimalNumber</em> )
236       *    | ( [ <code>-</code> ] ( <code>0x</code> | <code>0X</code>
237       *              | <code>#</code> ) <em>HexDigit</em> { <em>HexDigit</em> } )
238       *    | ( [ <code>-</code> ] <code>0</code> { <em>OctalDigit</em> } )
239       * <em>DecimalNumber</em>:
240       *        <em>DecimalDigit except '0'</em> { <em>DecimalDigit</em> }
241       * <em>DecimalDigit</em>:
242       *        <em>Character.digit(d, 10) has value 0 to 9</em>
243       * <em>OctalDigit</em>:
244       *        <em>Character.digit(d, 8) has value 0 to 7</em>
245       * <em>DecimalDigit</em>:
246       *        <em>Character.digit(d, 16) has value 0 to 15</em>
247       * </pre>
248       * Finally, the value must be in the range <code>MIN_VALUE</code> to
249       * <code>MAX_VALUE</code>, or an exception is thrown.
250       *
251       * @param s the <code>String</code> to interpret
252       * @return the value of the String as a <code>Short</code>
253       * @throws NumberFormatException if <code>s</code> cannot be parsed as a
254       *         <code>short</code>
255       * @throws NullPointerException if <code>s</code> is null
256       * @see Integer#decode(String)
257       */
258      public static Short decode(String s)
259      {
260        int i = Integer.parseInt(s, 10, true);
261        if ((short) i != i)
262          throw new NumberFormatException();
263        return new Short((short) i);
264      }
265    
266      /**
267       * Return the value of this <code>Short</code> as a <code>byte</code>.
268       *
269       * @return the byte value
270       */
271      public byte byteValue()
272      {
273        return (byte) value;
274      }
275    
276      /**
277       * Return the value of this <code>Short</code>.
278       *
279       * @return the short value
280       */
281      public short shortValue()
282      {
283        return value;
284      }
285    
286      /**
287       * Return the value of this <code>Short</code> as an <code>int</code>.
288       *
289       * @return the int value
290       */
291      public int intValue()
292      {
293        return value;
294      }
295    
296      /**
297       * Return the value of this <code>Short</code> as a <code>long</code>.
298       *
299       * @return the long value
300       */
301      public long longValue()
302      {
303        return value;
304      }
305    
306      /**
307       * Return the value of this <code>Short</code> as a <code>float</code>.
308       *
309       * @return the float value
310       */
311      public float floatValue()
312      {
313        return value;
314      }
315    
316      /**
317       * Return the value of this <code>Short</code> as a <code>double</code>.
318       *
319       * @return the double value
320       */
321      public double doubleValue()
322      {
323        return value;
324      }
325    
326      /**
327       * Converts the <code>Short</code> value to a <code>String</code> and
328       * assumes a radix of 10.
329       *
330       * @return the <code>String</code> representation of this <code>Short</code>
331       */
332      public String toString()
333      {
334        return String.valueOf(value);
335      }
336    
337      /**
338       * Return a hashcode representing this Object. <code>Short</code>'s hash
339       * code is simply its value.
340       *
341       * @return this Object's hash code
342       */
343      public int hashCode()
344      {
345        return value;
346      }
347    
348      /**
349       * Returns <code>true</code> if <code>obj</code> is an instance of
350       * <code>Short</code> and represents the same short value.
351       *
352       * @param obj the object to compare
353       * @return whether these Objects are semantically equal
354       */
355      public boolean equals(Object obj)
356      {
357        return obj instanceof Short && value == ((Short) obj).value;
358      }
359    
360      /**
361       * Compare two Shorts numerically by comparing their <code>short</code>
362       * values. The result is positive if the first is greater, negative if the
363       * second is greater, and 0 if the two are equal.
364       *
365       * @param s the Short to compare
366       * @return the comparison
367       * @since 1.2
368       */
369      public int compareTo(Short s)
370      {
371        return value - s.value;
372      }
373    
374      /**
375       * Reverse the bytes in val.
376       * @since 1.5
377       */
378      public static short reverseBytes(short val)
379      {
380        return (short) (((val >> 8) & 0xff) | ((val << 8) & 0xff00));
381      }
382    }