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