Short


1   /*
2    * @(#)Short.java   1.43 04/05/11
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.lang;
9   
10  /**
11   * The <code>Short</code> class wraps a value of primitive type
12   * <code>short</code> in an object.  An object of type
13   * <code>Short</code> contains a single field whose type is
14   * <code>short</code>.
15   *
16   * <p>
17   *
18   * In addition, this class provides several methods for converting a
19   * <code>short</code> to a <code>String</code> and a
20   * <code>String</code> to a <code>short</code>, as well as other
21   * constants and methods useful when dealing with a <code>short</code>.
22   *
23   * @author  Nakul Saraiya
24   * @version 1.43, 05/11/04
25   * @see     java.lang.Number
26   * @since   JDK1.1
27   */
28  public final class Short extends Number   implements Comparable  <Short  > {
29  
30      /**
31       * A constant holding the minimum value a <code>short</code> can
32       * have, -2<sup>15</sup>.
33       */
34      public static final short   MIN_VALUE = -32768;
35  
36      /**
37       * A constant holding the maximum value a <code>short</code> can
38       * have, 2<sup>15</sup>-1.
39       */
40      public static final short   MAX_VALUE = 32767;
41  
42      /**
43       * The <code>Class</code> instance representing the primitive type
44       * <code>short</code>.
45       */
46      public static final Class  <Short  >    TYPE = (Class  <Short  >) Class.getPrimitiveClass("short");
47  
48      /**
49       * Returns a new <code>String</code> object representing the
50       * specified <code>short</code>. The radix is assumed to be 10.
51       *
52       * @param s the <code>short</code> to be converted
53       * @return the string representation of the specified <code>short</code>
54       * @see java.lang.Integer#toString(int)
55       */
56      public static String   toString(short s) {
57      return Integer.toString((int)s, 10);
58      }
59  
60      /**
61       * Parses the string argument as a signed decimal
62       * <code>short</code>. The characters in the string must all be
63       * decimal digits, except that the first character may be an ASCII
64       * minus sign <code>'-'</code> (<code>'&#92;u002D'</code>) to
65       * indicate a negative value. The resulting <code>short</code> value is
66       * returned, exactly as if the argument and the radix 10 were
67       * given as arguments to the {@link #parseShort(java.lang.String,
68       * int)} method.
69       *
70       * @param s     a <code>String</code> containing the <code>short</code>
71       *                  representation to be parsed
72       * @return          the <code>short</code> value represented by the 
73       *                  argument in decimal.
74       * @exception   NumberFormatException If the string does not
75       *          contain a parsable <code>short</code>.
76       */
77      public static short parseShort(String   s) throws NumberFormatException   {
78      return parseShort(s, 10);
79      }
80  
81      /**
82       * Parses the string argument as a signed <code>short</code> in
83       * the radix specified by the second argument. The characters in
84       * the string must all be digits, of the specified radix (as
85       * determined by whether {@link java.lang.Character#digit(char,
86       * int)} returns a nonnegative value) except that the first
87       * character may be an ASCII minus sign <code>'-'</code>
88       * (<code>'&#92;u002D'</code>) to indicate a negative value.  The
89       * resulting <code>byte</code> value is returned.
90       * <p>
91       * An exception of type <code>NumberFormatException</code> is
92       * thrown if any of the following situations occurs:
93       * <ul>
94       * <li> The first argument is <code>null</code> or is a string of
95       * length zero.
96       *
97       * <li> The radix is either smaller than {@link
98       * java.lang.Character#MIN_RADIX} or larger than {@link
99       * java.lang.Character#MAX_RADIX}.
100      *
101      * <li> Any character of the string is not a digit of the specified
102      * radix, except that the first character may be a minus sign
103      * <code>'-'</code> (<code>'&#92;u002D'</code>) provided that the
104      * string is longer than length 1.
105      *
106      * <li> The value represented by the string is not a value of type
107      * <code>short</code>.
108      * </ul>
109      *
110      * @param s     the <code>String</code> containing the 
111      *          <code>short</code> representation to be parsed
112      * @param radix the radix to be used while parsing <code>s</code>
113      * @return      the <code>short</code> represented by the string 
114      *              argument in the specified radix.
115      * @exception   NumberFormatException If the <code>String</code> 
116      *          does not contain a parsable <code>short</code>.
117      */
118     public static short parseShort(String   s, int radix)
119     throws NumberFormatException   {
120     int i = Integer.parseInt(s, radix);
121     if (i < MIN_VALUE || i > MAX_VALUE)
122         throw new NumberFormatException  (
123                 "Value out of range. Value:\"" + s + "\" Radix:" + radix);
124     return (short)i;
125     }
126 
127     /**
128      * Returns a <code>Short</code> object holding the value
129      * extracted from the specified <code>String</code> when parsed
130      * with the radix given by the second argument. The first argument
131      * is interpreted as representing a signed <code>short</code> in
132      * the radix specified by the second argument, exactly as if the
133      * argument were given to the {@link #parseShort(java.lang.String,
134      * int)} method. The result is a <code>Short</code> object that
135      * represents the <code>short</code> value specified by the string.
136      * <p> In other words, this method returns a <code>Short</code> object
137      * equal to the value of:
138      *
139      * <blockquote><code>
140      * new Short(Short.parseShort(s, radix))
141      * </code></blockquote>
142      *
143      * @param s     the string to be parsed
144      * @param radix     the radix to be used in interpreting <code>s</code>
145      * @return          a <code>Short</code> object holding the value 
146      *          represented by the string argument in the 
147      *          specified radix.
148      * @exception   NumberFormatException If the <code>String</code> does
149      *          not contain a parsable <code>short</code>.
150      */
151     public static Short   valueOf(String   s, int radix)
152     throws NumberFormatException   {
153     return new Short  (parseShort(s, radix));
154     }
155 
156     /**
157      * Returns a <code>Short</code> object holding the
158      * value given by the specified <code>String</code>. The argument
159      * is interpreted as representing a signed decimal
160      * <code>short</code>, exactly as if the argument were given to
161      * the {@link #parseShort(java.lang.String)} method. The result is
162      * a <code>Short</code> object that represents the
163      * <code>short</code> value specified by the string.  <p> In other
164      * words, this method returns a <code>Byte</code> object equal to
165      * the value of:
166      *
167      * <blockquote><code>
168      * new Short(Short.parseShort(s))
169      * </code></blockquote>
170      *
171      * @param s     the string to be parsed
172      * @return          a <code>Short</code> object holding the value
173      *          represented by the string argument
174      * @exception   NumberFormatException If the <code>String</code> does
175      *          not contain a parsable <code>short</code>.
176      */
177     public static Short   valueOf(String   s) throws NumberFormatException   {
178     return valueOf(s, 10);
179     }
180 
181     private static class ShortCache {
182     private ShortCache(){}
183 
184     static final Short   cache[] = new Short  [-(-128) + 127 + 1];
185 
186     static {
187         for(int i = 0; i < cache.length; i++)
188         cache[i] = new Short  ((short)(i - 128));
189     }
190     }
191 
192     /**
193      * Returns a <tt>Short</tt> instance representing the specified
194      * <tt>short</tt> value.
195      * If a new <tt>Short</tt> instance is not required, this method
196      * should generally be used in preference to the constructor
197      * {@link #Short(short)}, as this method is likely to yield
198      * significantly better space and time performance by caching
199      * frequently requested values.
200      *
201      * @param  s a short value.
202      * @return a <tt>Short</tt> instance representing <tt>s</tt>.
203      * @since  1.5
204      */
205     public static Short   valueOf(short s) {
206     final int offset = 128;
207     int sAsInt = s;
208     if (sAsInt >= -128 && sAsInt <= 127) { // must cache 
209         return ShortCache.cache[sAsInt + offset];
210     }
211         return new Short  (s);
212     }
213 
214     /**
215      * Decodes a <code>String</code> into a <code>Short</code>.
216      * Accepts decimal, hexadecimal, and octal numbers given by
217      * the following grammar:
218      *
219      * <blockquote>
220      * <dl>
221      * <dt><i>DecodableString:</i>
222      * <dd><i>Sign<sub>opt</sub> DecimalNumeral</i>
223      * <dd><i>Sign<sub>opt</sub></i> <code>0x</code> <i>HexDigits</i>
224      * <dd><i>Sign<sub>opt</sub></i> <code>0X</code> <i>HexDigits</i>
225      * <dd><i>Sign<sub>opt</sub></i> <code>#</code> <i>HexDigits</i>
226      * <dd><i>Sign<sub>opt</sub></i> <code>0</code> <i>OctalDigits</i>
227      * <p>
228      * <dt><i>Sign:</i>
229      * <dd><code>-</code>
230      * </dl>
231      * </blockquote>
232      *
233      * <i>DecimalNumeral</i>, <i>HexDigits</i>, and <i>OctalDigits</i>
234      * are defined in <a HREF="http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#48282">&sect;3.10.1</a> 
235      * of the <a HREF="http://java.sun.com/docs/books/jls/html/">Java 
236      * Language Specification</a>.
237      * <p>
238      * The sequence of characters following an (optional) negative
239      * sign and/or radix specifier (&quot;<code>0x</code>&quot;,
240      * &quot;<code>0X</code>&quot;, &quot;<code>#</code>&quot;, or
241      * leading zero) is parsed as by the <code>Short.parseShort</code>
242      * method with the indicated radix (10, 16, or 8).  This sequence
243      * of characters must represent a positive value or a {@link
244      * NumberFormatException} will be thrown.  The result is negated
245      * if first character of the specified <code>String</code> is the
246      * minus sign.  No whitespace characters are permitted in the
247      * <code>String</code>.
248      *
249      * @param     nm the <code>String</code> to decode.
250      * @return    a <code>Short</code> object holding the <code>short</code>
251      *        value represented by <code>nm</code>
252      * @exception NumberFormatException  if the <code>String</code> does not
253      *            contain a parsable <code>short</code>.
254      * @see java.lang.Short#parseShort(java.lang.String, int)
255      */
256     public static Short   decode(String   nm) throws NumberFormatException   {
257         int radix = 10;
258         int index = 0;
259         boolean negative = false;
260         Short   result;
261 
262         // Handle minus sign, if present
263         if (nm.startsWith("-")) {
264             negative = true;
265             index++;
266         }
267 
268         // Handle radix specifier, if present
269     if (nm.startsWith("0x", index) || nm.startsWith("0X", index)) {
270         index += 2;
271             radix = 16;
272     }
273     else if (nm.startsWith("#", index)) {
274         index ++;
275             radix = 16;
276     }
277     else if (nm.startsWith("0", index) && nm.length() > 1 + index) {
278         index ++;
279             radix = 8;
280     }
281 
282         if (nm.startsWith("-", index))
283             throw new NumberFormatException  ("Negative sign in wrong position");
284 
285         try {
286             result = Short.valueOf(nm.substring(index), radix);
287             result = negative ? new Short  ((short)-result.shortValue()) :result;
288         } catch (NumberFormatException   e) {
289             // If number is Short.MIN_VALUE, we'll end up here. The next line
290             // handles this case, and causes any genuine format error to be
291             // rethrown.
292             String   constant = negative ? new String  ("-" + nm.substring(index))
293                                        : nm.substring(index);
294             result = Short.valueOf(constant, radix);
295         }
296         return result;
297     }
298 
299     /**
300      * The value of the <code>Short</code>.
301      *
302      * @serial
303      */
304     private final short value;
305 
306     /**
307      * Constructs a newly allocated <code>Short</code> object that
308      * represents the specified <code>short</code> value.
309      *
310      * @param value the value to be represented by the 
311      *          <code>Short</code>.
312      */
313     public Short(short value) {
314     this.value = value;
315     }
316 
317     /**
318      * Constructs a newly allocated <code>Short</code> object that
319      * represents the <code>short</code> value indicated by the
320      * <code>String</code> parameter. The string is converted to a
321      * <code>short</code> value in exactly the manner used by the
322      * <code>parseShort</code> method for radix 10.
323      *
324      * @param s     the <code>String</code> to be converted to a 
325      *          <code>Short</code>
326      * @exception   NumberFormatException If the <code>String</code> 
327      *          does not contain a parsable <code>short</code>.
328      * @see        java.lang.Short#parseShort(java.lang.String, int)
329      */
330     public Short(String   s) throws NumberFormatException   {
331     this.value = parseShort(s, 10);
332     }
333 
334     /**
335      * Returns the value of this <code>Short</code> as a
336      * <code>byte</code>.
337      */
338     public byte byteValue() {
339     return (byte)value;
340     }
341 
342     /**
343      * Returns the value of this <code>Short</code> as a
344      * <code>short</code>.
345      */
346     public short shortValue() {
347     return value;
348     }
349 
350     /**
351      * Returns the value of this <code>Short</code> as an
352      * <code>int</code>.
353      */
354     public int intValue() {
355     return (int)value;
356     }
357 
358     /**
359      * Returns the value of this <code>Short</code> as a
360      * <code>long</code>.
361      */
362     public long longValue() {
363     return (long)value;
364     }
365 
366     /**
367      * Returns the value of this <code>Short</code> as a
368      * <code>float</code>.
369      */
370     public float floatValue() {
371     return (float)value;
372     }
373 
374     /**
375      * Returns the value of this <code>Short</code> as a
376      * <code>double</code>.
377      */
378     public double doubleValue() {
379     return (double)value;
380     }
381 
382     /**
383      * Returns a <code>String</code> object representing this
384      * <code>Short</code>'s value.  The value is converted to signed
385      * decimal representation and returned as a string, exactly as if
386      * the <code>short</code> value were given as an argument to the
387      * {@link java.lang.Short#toString(short)} method.
388      *
389      * @return  a string representation of the value of this object in
390      *          base&nbsp;10.
391      */
392     public String   toString() {
393     return String.valueOf((int)value);
394     }
395 
396     /**
397      * Returns a hash code for this <code>Short</code>.
398      */
399     public int hashCode() {
400     return (int)value;
401     }
402 
403     /**
404      * Compares this object to the specified object.  The result is
405      * <code>true</code> if and only if the argument is not
406      * <code>null</code> and is a <code>Short</code> object that
407      * contains the same <code>short</code> value as this object.
408      *
409      * @param obj   the object to compare with
410      * @return      <code>true</code> if the objects are the same;
411      *          <code>false</code> otherwise.
412      */
413     public boolean equals(Object   obj) {
414     if (obj instanceof Short  ) {
415         return value == ((Short  )obj).shortValue();
416     }
417     return false;
418     }
419 
420     /**
421      * Compares two <code>Short</code> objects numerically.
422      *
423      * @param   anotherShort   the <code>Short</code> to be compared.
424      * @return  the value <code>0</code> if this <code>Short</code> is
425      *      equal to the argument <code>Short</code>; a value less than
426      *      <code>0</code> if this <code>Short</code> is numerically less
427      *      than the argument <code>Short</code>; and a value greater than
428      *       <code>0</code> if this <code>Short</code> is numerically
429      *       greater than the argument <code>Short</code> (signed
430      *       comparison).
431      * @since   1.2
432      */
433     public int compareTo(Short   anotherShort) {
434     return this.value - anotherShort.value;
435     }
436 
437     /**
438      * The number of bits used to represent a <tt>short</tt> value in two's
439      * complement binary form.
440      */
441     public static final int SIZE = 16;
442  
443     /**
444      * Returns the value obtained by reversing the order of the bytes in the
445      * two's complement representation of the specified <tt>short</tt> value.
446      *
447      * @return the value obtained by reversing (or, equivalently, swapping)
448      *     the bytes in the specified <tt>short</tt> value.
449      * @since 1.5
450      */
451     public static short reverseBytes(short i) {
452         return (short) (((i & 0xFF00) >> 8) | (i << 8));
453     }
454 
455     /** use serialVersionUID from JDK 1.1. for interoperability */
456     private static final long serialVersionUID = 7515723908773894738L;
457 }
458
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags