001 /*
002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang;
027
028 /**
029 * The {@code Short} class wraps a value of primitive type {@code
030 * short} in an object. An object of type {@code Short} contains a
031 * single field whose type is {@code short}.
032 *
033 * <p>In addition, this class provides several methods for converting
034 * a {@code short} to a {@code String} and a {@code String} to a
035 * {@code short}, as well as other constants and methods useful when
036 * dealing with a {@code short}.
037 *
038 * @author Nakul Saraiya
039 * @author Joseph D. Darcy
040 * @version 1.53, 05/05/07
041 * @see java.lang.Number
042 * @since JDK1.1
043 */
044 public final class Short extends Number implements Comparable<Short> {
045
046 /**
047 * A constant holding the minimum value a {@code short} can
048 * have, -2<sup>15</sup>.
049 */
050 public static final short MIN_VALUE = -32768;
051
052 /**
053 * A constant holding the maximum value a {@code short} can
054 * have, 2<sup>15</sup>-1.
055 */
056 public static final short MAX_VALUE = 32767;
057
058 /**
059 * The {@code Class} instance representing the primitive type
060 * {@code short}.
061 */
062 public static final Class<Short> TYPE = (Class<Short>) Class
063 .getPrimitiveClass("short");
064
065 /**
066 * Returns a new {@code String} object representing the
067 * specified {@code short}. The radix is assumed to be 10.
068 *
069 * @param s the {@code short} to be converted
070 * @return the string representation of the specified {@code short}
071 * @see java.lang.Integer#toString(int)
072 */
073 public static String toString(short s) {
074 return Integer.toString((int) s, 10);
075 }
076
077 /**
078 * Parses the string argument as a signed {@code short} in the
079 * radix specified by the second argument. The characters in the
080 * string must all be digits, of the specified radix (as
081 * determined by whether {@link java.lang.Character#digit(char,
082 * int)} returns a nonnegative value) except that the first
083 * character may be an ASCII minus sign {@code '-'}
084 * (<code>'\u002D'</code>) to indicate a negative value or an
085 * ASCII plus sign {@code '+'} (<code>'\u002B'</code>) to
086 * indicate a positive value. The resulting {@code short} value
087 * is returned.
088 *
089 * <p>An exception of type {@code NumberFormatException} is
090 * thrown if any of the following situations occurs:
091 * <ul>
092 * <li> The first argument is {@code null} or is a string of
093 * length zero.
094 *
095 * <li> The radix is either smaller than {@link
096 * java.lang.Character#MIN_RADIX} or larger than {@link
097 * java.lang.Character#MAX_RADIX}.
098 *
099 * <li> Any character of the string is not a digit of the
100 * specified radix, except that the first character may be a minus
101 * sign {@code '-'} (<code>'\u002D'</code>) or plus sign
102 * {@code '+'} (<code>'\u002B'</code>) provided that the
103 * string is longer than length 1.
104 *
105 * <li> The value represented by the string is not a value of type
106 * {@code short}.
107 * </ul>
108 *
109 * @param s the {@code String} containing the
110 * {@code short} representation to be parsed
111 * @param radix the radix to be used while parsing {@code s}
112 * @return the {@code short} represented by the string
113 * argument in the specified radix.
114 * @throws NumberFormatException If the {@code String}
115 * does not contain a parsable {@code short}.
116 */
117 public static short parseShort(String s, int radix)
118 throws NumberFormatException {
119 int i = Integer.parseInt(s, radix);
120 if (i < MIN_VALUE || i > MAX_VALUE)
121 throw new NumberFormatException(
122 "Value out of range. Value:\"" + s + "\" Radix:"
123 + radix);
124 return (short) i;
125 }
126
127 /**
128 * Parses the string argument as a signed decimal {@code
129 * short}. The characters in the string must all be decimal
130 * digits, except that the first character may be an ASCII minus
131 * sign {@code '-'} (<code>'\u002D'</code>) to indicate a
132 * negative value or an ASCII plus sign {@code '+'}
133 * (<code>'\u002B'</code>) to indicate a positive value. The
134 * resulting {@code short} value is returned, exactly as if the
135 * argument and the radix 10 were given as arguments to the {@link
136 * #parseShort(java.lang.String, int)} method.
137 *
138 * @param s a {@code String} containing the {@code short}
139 * representation to be parsed
140 * @return the {@code short} value represented by the
141 * argument in decimal.
142 * @throws NumberFormatException If the string does not
143 * contain a parsable {@code short}.
144 */
145 public static short parseShort(String s)
146 throws NumberFormatException {
147 return parseShort(s, 10);
148 }
149
150 /**
151 * Returns a {@code Short} object holding the value
152 * extracted from the specified {@code String} when parsed
153 * with the radix given by the second argument. The first argument
154 * is interpreted as representing a signed {@code short} in
155 * the radix specified by the second argument, exactly as if the
156 * argument were given to the {@link #parseShort(java.lang.String,
157 * int)} method. The result is a {@code Short} object that
158 * represents the {@code short} value specified by the string.
159 *
160 * <p>In other words, this method returns a {@code Short} object
161 * equal to the value of:
162 *
163 * <blockquote>
164 * {@code new Short(Short.parseShort(s, radix))}
165 * </blockquote>
166 *
167 * @param s the string to be parsed
168 * @param radix the radix to be used in interpreting {@code s}
169 * @return a {@code Short} object holding the value
170 * represented by the string argument in the
171 * specified radix.
172 * @throws NumberFormatException If the {@code String} does
173 * not contain a parsable {@code short}.
174 */
175 public static Short valueOf(String s, int radix)
176 throws NumberFormatException {
177 return new Short(parseShort(s, radix));
178 }
179
180 /**
181 * Returns a {@code Short} object holding the
182 * value given by the specified {@code String}. The argument
183 * is interpreted as representing a signed decimal
184 * {@code short}, exactly as if the argument were given to
185 * the {@link #parseShort(java.lang.String)} method. The result is
186 * a {@code Short} object that represents the
187 * {@code short} value specified by the string.
188 *
189 * <p>In other words, this method returns a {@code Short} object
190 * equal to the value of:
191 *
192 * <blockquote>
193 * {@code new Short(Short.parseShort(s))}
194 * </blockquote>
195 *
196 * @param s the string to be parsed
197 * @return a {@code Short} object holding the value
198 * represented by the string argument
199 * @throws NumberFormatException If the {@code String} does
200 * not contain a parsable {@code short}.
201 */
202 public static Short valueOf(String s) throws NumberFormatException {
203 return valueOf(s, 10);
204 }
205
206 private static class ShortCache {
207 private ShortCache() {
208 }
209
210 static final Short cache[] = new Short[-(-128) + 127 + 1];
211
212 static {
213 for (int i = 0; i < cache.length; i++)
214 cache[i] = new Short((short) (i - 128));
215 }
216 }
217
218 /**
219 * Returns a {@code Short} instance representing the specified
220 * {@code short} value.
221 * If a new {@code Short} instance is not required, this method
222 * should generally be used in preference to the constructor
223 * {@link #Short(short)}, as this method is likely to yield
224 * significantly better space and time performance by caching
225 * frequently requested values.
226 *
227 * @param s a short value.
228 * @return a {@code Short} instance representing {@code s}.
229 * @since 1.5
230 */
231 public static Short valueOf(short s) {
232 final int offset = 128;
233 int sAsInt = s;
234 if (sAsInt >= -128 && sAsInt <= 127) { // must cache
235 return ShortCache.cache[sAsInt + offset];
236 }
237 return new Short(s);
238 }
239
240 /**
241 * Decodes a {@code String} into a {@code Short}.
242 * Accepts decimal, hexadecimal, and octal numbers given by
243 * the following grammar:
244 *
245 * <blockquote>
246 * <dl>
247 * <dt><i>DecodableString:</i>
248 * <dd><i>Sign<sub>opt</sub> DecimalNumeral</i>
249 * <dd><i>Sign<sub>opt</sub></i> {@code 0x} <i>HexDigits</i>
250 * <dd><i>Sign<sub>opt</sub></i> {@code 0X} <i>HexDigits</i>
251 * <dd><i>Sign<sub>opt</sub></i> {@code #} <i>HexDigits</i>
252 * <dd><i>Sign<sub>opt</sub></i> {@code 0} <i>OctalDigits</i>
253 * <p>
254 * <dt><i>Sign:</i>
255 * <dd>{@code -}
256 * <dd>{@code +}
257 * </dl>
258 * </blockquote>
259 *
260 * <i>DecimalNumeral</i>, <i>HexDigits</i>, and <i>OctalDigits</i>
261 * are defined in <a href="http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#48282">§3.10.1</a>
262 * of the <a href="http://java.sun.com/docs/books/jls/html/">Java
263 * Language Specification</a>.
264 *
265 * <p>The sequence of characters following an optional
266 * sign and/or radix specifier ("{@code 0x}", "{@code 0X}",
267 * "{@code #}", or leading zero) is parsed as by the {@code
268 * Short.parseShort} method with the indicated radix (10, 16, or
269 * 8). This sequence of characters must represent a positive
270 * value or a {@link NumberFormatException} will be thrown. The
271 * result is negated if first character of the specified {@code
272 * String} is the minus sign. No whitespace characters are
273 * permitted in the {@code String}.
274 *
275 * @param nm the {@code String} to decode.
276 * @return a {@code Short} object holding the {@code short}
277 * value represented by {@code nm}
278 * @throws NumberFormatException if the {@code String} does not
279 * contain a parsable {@code short}.
280 * @see java.lang.Short#parseShort(java.lang.String, int)
281 */
282 public static Short decode(String nm) throws NumberFormatException {
283 int i = Integer.decode(nm);
284 if (i < MIN_VALUE || i > MAX_VALUE)
285 throw new NumberFormatException("Value " + i
286 + " out of range from input " + nm);
287 return (short) i;
288 }
289
290 /**
291 * The value of the {@code Short}.
292 *
293 * @serial
294 */
295 private final short value;
296
297 /**
298 * Constructs a newly allocated {@code Short} object that
299 * represents the specified {@code short} value.
300 *
301 * @param value the value to be represented by the
302 * {@code Short}.
303 */
304 public Short(short value) {
305 this .value = value;
306 }
307
308 /**
309 * Constructs a newly allocated {@code Short} object that
310 * represents the {@code short} value indicated by the
311 * {@code String} parameter. The string is converted to a
312 * {@code short} value in exactly the manner used by the
313 * {@code parseShort} method for radix 10.
314 *
315 * @param s the {@code String} to be converted to a
316 * {@code Short}
317 * @throws NumberFormatException If the {@code String}
318 * does not contain a parsable {@code short}.
319 * @see java.lang.Short#parseShort(java.lang.String, int)
320 */
321 public Short(String s) throws NumberFormatException {
322 this .value = parseShort(s, 10);
323 }
324
325 /**
326 * Returns the value of this {@code Short} as a
327 * {@code byte}.
328 */
329 public byte byteValue() {
330 return (byte) value;
331 }
332
333 /**
334 * Returns the value of this {@code Short} as a
335 * {@code short}.
336 */
337 public short shortValue() {
338 return value;
339 }
340
341 /**
342 * Returns the value of this {@code Short} as an
343 * {@code int}.
344 */
345 public int intValue() {
346 return (int) value;
347 }
348
349 /**
350 * Returns the value of this {@code Short} as a
351 * {@code long}.
352 */
353 public long longValue() {
354 return (long) value;
355 }
356
357 /**
358 * Returns the value of this {@code Short} as a
359 * {@code float}.
360 */
361 public float floatValue() {
362 return (float) value;
363 }
364
365 /**
366 * Returns the value of this {@code Short} as a
367 * {@code double}.
368 */
369 public double doubleValue() {
370 return (double) value;
371 }
372
373 /**
374 * Returns a {@code String} object representing this
375 * {@code Short}'s value. The value is converted to signed
376 * decimal representation and returned as a string, exactly as if
377 * the {@code short} value were given as an argument to the
378 * {@link java.lang.Short#toString(short)} method.
379 *
380 * @return a string representation of the value of this object in
381 * base 10.
382 */
383 public String toString() {
384 return String.valueOf((int) value);
385 }
386
387 /**
388 * Returns a hash code for this {@code Short}.
389 */
390 public int hashCode() {
391 return (int) value;
392 }
393
394 /**
395 * Compares this object to the specified object. The result is
396 * {@code true} if and only if the argument is not
397 * {@code null} and is a {@code Short} object that
398 * contains the same {@code short} value as this object.
399 *
400 * @param obj the object to compare with
401 * @return {@code true} if the objects are the same;
402 * {@code false} otherwise.
403 */
404 public boolean equals(Object obj) {
405 if (obj instanceof Short) {
406 return value == ((Short) obj).shortValue();
407 }
408 return false;
409 }
410
411 /**
412 * Compares two {@code Short} objects numerically.
413 *
414 * @param anotherShort the {@code Short} to be compared.
415 * @return the value {@code 0} if this {@code Short} is
416 * equal to the argument {@code Short}; a value less than
417 * {@code 0} if this {@code Short} is numerically less
418 * than the argument {@code Short}; and a value greater than
419 * {@code 0} if this {@code Short} is numerically
420 * greater than the argument {@code Short} (signed
421 * comparison).
422 * @since 1.2
423 */
424 public int compareTo(Short anotherShort) {
425 return this .value - anotherShort.value;
426 }
427
428 /**
429 * The number of bits used to represent a {@code short} value in two's
430 * complement binary form.
431 * @since 1.5
432 */
433 public static final int SIZE = 16;
434
435 /**
436 * Returns the value obtained by reversing the order of the bytes in the
437 * two's complement representation of the specified {@code short} value.
438 *
439 * @return the value obtained by reversing (or, equivalently, swapping)
440 * the bytes in the specified {@code short} value.
441 * @since 1.5
442 */
443 public static short reverseBytes(short i) {
444 return (short) (((i & 0xFF00) >> 8) | (i << 8));
445 }
446
447 /** use serialVersionUID from JDK 1.1. for interoperability */
448 private static final long serialVersionUID = 7515723908773894738L;
449 }
|