1 /*

     2  * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.lang;

    27 

    28 import jdk.internal.HotSpotIntrinsicCandidate;

    29 

    30 /**

    31  * The {@code Short} class wraps a value of primitive type {@code

    32  * short} in an object.  An object of type {@code Short} contains a

    33  * single field whose type is {@code short}.

    34  *

    35  * <p>In addition, this class provides several methods for converting

    36  * a {@code short} to a {@code String} and a {@code String} to a

    37  * {@code short}, as well as other constants and methods useful when

    38  * dealing with a {@code short}.

    39  *

    40  * @author  Nakul Saraiya

    41  * @author  Joseph D. Darcy

    42  * @see     java.lang.Number

    43  * @since   1.1

    44  */

    45 public final class Short extends Number implements Comparable<Short> {

    46 

    47     /**

    48      * A constant holding the minimum value a {@code short} can

    49      * have, -2<sup>15</sup>.

    50      */

    51     public static final short   MIN_VALUE = -32768;

    52 

    53     /**

    54      * A constant holding the maximum value a {@code short} can

    55      * have, 2<sup>15</sup>-1.

    56      */

    57     public static final short   MAX_VALUE = 32767;

    58 

    59     /**

    60      * The {@code Class} instance representing the primitive type

    61      * {@code short}.

    62      */

    63     @SuppressWarnings("unchecked")

    64     public static final Class<Short>    TYPE = (Class<Short>) Class.getPrimitiveClass("short");

    65 

    66     /**

    67      * Returns a new {@code String} object representing the

    68      * specified {@code short}. The radix is assumed to be 10.

    69      *

    70      * @param s the {@code short} to be converted

    71      * @return the string representation of the specified {@code short}

    72      * @see java.lang.Integer#toString(int)

    73      */

    74     public static String toString(short s) {

    75         return Integer.toString((int)s, 10);

    76     }

    77 

    78     /**

    79      * Parses the string argument as a signed {@code short} in the

    80      * radix specified by the second argument. The characters in the

    81      * string must all be digits, of the specified radix (as

    82      * determined by whether {@link java.lang.Character#digit(char,

    83      * int)} returns a nonnegative value) except that the first

    84      * character may be an ASCII minus sign {@code '-'}

    85      * ({@code '\u005Cu002D'}) to indicate a negative value or an

    86      * ASCII plus sign {@code '+'} ({@code '\u005Cu002B'}) to

    87      * indicate a positive value.  The resulting {@code short} value

    88      * is returned.

    89      *

    90      * <p>An exception of type {@code NumberFormatException} is

    91      * thrown if any of the following situations occurs:

    92      * <ul>

    93      * <li> The first argument is {@code null} or is a string of

    94      * length zero.

    95      *

    96      * <li> The radix is either smaller than {@link

    97      * java.lang.Character#MIN_RADIX} or larger than {@link

    98      * java.lang.Character#MAX_RADIX}.

    99      *

   100      * <li> Any character of the string is not a digit of the

   101      * specified radix, except that the first character may be a minus

   102      * sign {@code '-'} ({@code '\u005Cu002D'}) or plus sign

   103      * {@code '+'} ({@code '\u005Cu002B'}) 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}.

   108      * </ul>

   109      *

   110      * @param s         the {@code String} containing the

   111      *                  {@code short} representation to be parsed

   112      * @param radix     the radix to be used while parsing {@code s}

   113      * @return          the {@code short} represented by the string

   114      *                  argument in the specified radix.

   115      * @throws          NumberFormatException If the {@code String}

   116      *                  does not contain a parsable {@code short}.

   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      * 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 '\u005Cu002D'}) to indicate a

   132      * negative value or an ASCII plus sign {@code '+'}

   133      * ({@code '\u005Cu002B'}) 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) throws NumberFormatException {

   146         return parseShort(s, 10);

   147     }

   148 

   149     /**

   150      * Returns a {@code Short} object holding the value

   151      * extracted from the specified {@code String} when parsed

   152      * with the radix given by the second argument. The first argument

   153      * is interpreted as representing a signed {@code short} in

   154      * the radix specified by the second argument, exactly as if the

   155      * argument were given to the {@link #parseShort(java.lang.String,

   156      * int)} method. The result is a {@code Short} object that

   157      * represents the {@code short} value specified by the string.

   158      *

   159      * <p>In other words, this method returns a {@code Short} object

   160      * equal to the value of:

   161      *

   162      * <blockquote>

   163      *  {@code new Short(Short.parseShort(s, radix))}

   164      * </blockquote>

   165      *

   166      * @param s         the string to be parsed

   167      * @param radix     the radix to be used in interpreting {@code s}

   168      * @return          a {@code Short} object holding the value

   169      *                  represented by the string argument in the

   170      *                  specified radix.

   171      * @throws          NumberFormatException If the {@code String} does

   172      *                  not contain a parsable {@code short}.

   173      */

   174     public static Short valueOf(String s, int radix)

   175         throws NumberFormatException {

   176         return valueOf(parseShort(s, radix));

   177     }

   178 

   179     /**

   180      * Returns a {@code Short} object holding the

   181      * value given by the specified {@code String}. The argument

   182      * is interpreted as representing a signed decimal

   183      * {@code short}, exactly as if the argument were given to

   184      * the {@link #parseShort(java.lang.String)} method. The result is

   185      * a {@code Short} object that represents the

   186      * {@code short} value specified by the string.

   187      *

   188      * <p>In other words, this method returns a {@code Short} object

   189      * equal to the value of:

   190      *

   191      * <blockquote>

   192      *  {@code new Short(Short.parseShort(s))}

   193      * </blockquote>

   194      *

   195      * @param s the string to be parsed

   196      * @return  a {@code Short} object holding the value

   197      *          represented by the string argument

   198      * @throws  NumberFormatException If the {@code String} does

   199      *          not contain a parsable {@code short}.

   200      */

   201     public static Short valueOf(String s) throws NumberFormatException {

   202         return valueOf(s, 10);

   203     }

   204 

   205     private static class ShortCache {

   206         private ShortCache(){}

   207 

   208         static final Short cache[] = new Short[-(-128) + 127 + 1];

   209 

   210         static {

   211             for(int i = 0; i < cache.length; i++)

   212                 cache[i] = new Short((short)(i - 128));

   213         }

   214     }

   215 

   216     /**

   217      * Returns a {@code Short} instance representing the specified

   218      * {@code short} value.

   219      * If a new {@code Short} instance is not required, this method

   220      * should generally be used in preference to the constructor

   221      * {@link #Short(short)}, as this method is likely to yield

   222      * significantly better space and time performance by caching

   223      * frequently requested values.

   224      *

   225      * This method will always cache values in the range -128 to 127,

   226      * inclusive, and may cache other values outside of this range.

   227      *

   228      * @param  s a short value.

   229      * @return a {@code Short} instance representing {@code s}.

   230      * @since  1.5

   231      */

   232     @HotSpotIntrinsicCandidate

   233     public static Short valueOf(short s) {

   234         final int offset = 128;

   235         int sAsInt = s;

   236         if (sAsInt >= -128 && sAsInt <= 127) { // must cache

   237             return ShortCache.cache[sAsInt + offset];

   238         }

   239         return new Short(s);

   240     }

   241 

   242     /**

   243      * Decodes a {@code String} into a {@code Short}.

   244      * Accepts decimal, hexadecimal, and octal numbers given by

   245      * the following grammar:

   246      *

   247      * <blockquote>

   248      * <dl>

   249      * <dt><i>DecodableString:</i>

   250      * <dd><i>Sign<sub>opt</sub> DecimalNumeral</i>

   251      * <dd><i>Sign<sub>opt</sub></i> {@code 0x} <i>HexDigits</i>

   252      * <dd><i>Sign<sub>opt</sub></i> {@code 0X} <i>HexDigits</i>

   253      * <dd><i>Sign<sub>opt</sub></i> {@code #} <i>HexDigits</i>

   254      * <dd><i>Sign<sub>opt</sub></i> {@code 0} <i>OctalDigits</i>

   255      *

   256      * <dt><i>Sign:</i>

   257      * <dd>{@code -}

   258      * <dd>{@code +}

   259      * </dl>

   260      * </blockquote>

   261      *

   262      * <i>DecimalNumeral</i>, <i>HexDigits</i>, and <i>OctalDigits</i>

   263      * are as defined in section 3.10.1 of

   264      * <cite>The Java&trade; Language Specification</cite>,

   265      * except that underscores are not accepted between digits.

   266      *

   267      * <p>The sequence of characters following an optional

   268      * sign and/or radix specifier ("{@code 0x}", "{@code 0X}",

   269      * "{@code #}", or leading zero) is parsed as by the {@code

   270      * Short.parseShort} method with the indicated radix (10, 16, or

   271      * 8).  This sequence of characters must represent a positive

   272      * value or a {@link NumberFormatException} will be thrown.  The

   273      * result is negated if first character of the specified {@code

   274      * String} is the minus sign.  No whitespace characters are

   275      * permitted in the {@code String}.

   276      *

   277      * @param     nm the {@code String} to decode.

   278      * @return    a {@code Short} object holding the {@code short}

   279      *            value represented by {@code nm}

   280      * @throws    NumberFormatException  if the {@code String} does not

   281      *            contain a parsable {@code short}.

   282      * @see java.lang.Short#parseShort(java.lang.String, int)

   283      */

   284     public static Short decode(String nm) throws NumberFormatException {

   285         int i = Integer.decode(nm);

   286         if (i < MIN_VALUE || i > MAX_VALUE)

   287             throw new NumberFormatException(

   288                     "Value " + i + " out of range from input " + nm);

   289         return valueOf((short)i);

   290     }

   291 

   292     /**

   293      * The value of the {@code Short}.

   294      *

   295      * @serial

   296      */

   297     private final short value;

   298 

   299     /**

   300      * Constructs a newly allocated {@code Short} object that

   301      * represents the specified {@code short} value.

   302      *

   303      * @param value     the value to be represented by the

   304      *                  {@code Short}.

   305      *

   306      * @deprecated

   307      * It is rarely appropriate to use this constructor. The static factory

   308      * {@link #valueOf(short)} is generally a better choice, as it is

   309      * likely to yield significantly better space and time performance.

   310      */

   311     @Deprecated(since="9")

   312     public Short(short value) {

   313         this.value = value;

   314     }

   315 

   316     /**

   317      * Constructs a newly allocated {@code Short} object that

   318      * represents the {@code short} value indicated by the

   319      * {@code String} parameter. The string is converted to a

   320      * {@code short} value in exactly the manner used by the

   321      * {@code parseShort} method for radix 10.

   322      *

   323      * @param s the {@code String} to be converted to a

   324      *          {@code Short}

   325      * @throws  NumberFormatException If the {@code String}

   326      *          does not contain a parsable {@code short}.

   327      *

   328      * @deprecated

   329      * It is rarely appropriate to use this constructor.

   330      * Use {@link #parseShort(String)} to convert a string to a

   331      * {@code short} primitive, or use {@link #valueOf(String)}

   332      * to convert a string to a {@code Short} object.

   333      */

   334     @Deprecated(since="9")

   335     public Short(String s) throws NumberFormatException {

   336         this.value = parseShort(s, 10);

   337     }

   338 

   339     /**

   340      * Returns the value of this {@code Short} as a {@code byte} after

   341      * a narrowing primitive conversion.

   342      * @jls 5.1.3 Narrowing Primitive Conversions

   343      */

   344     public byte byteValue() {

   345         return (byte)value;

   346     }

   347 

   348     /**

   349      * Returns the value of this {@code Short} as a

   350      * {@code short}.

   351      */

   352     @HotSpotIntrinsicCandidate

   353     public short shortValue() {

   354         return value;

   355     }

   356 

   357     /**

   358      * Returns the value of this {@code Short} as an {@code int} after

   359      * a widening primitive conversion.

   360      * @jls 5.1.2 Widening Primitive Conversions

   361      */

   362     public int intValue() {

   363         return (int)value;

   364     }

   365 

   366     /**

   367      * Returns the value of this {@code Short} as a {@code long} after

   368      * a widening primitive conversion.

   369      * @jls 5.1.2 Widening Primitive Conversions

   370      */

   371     public long longValue() {

   372         return (long)value;

   373     }

   374 

   375     /**

   376      * Returns the value of this {@code Short} as a {@code float}

   377      * after a widening primitive conversion.

   378      * @jls 5.1.2 Widening Primitive Conversions

   379      */

   380     public float floatValue() {

   381         return (float)value;

   382     }

   383 

   384     /**

   385      * Returns the value of this {@code Short} as a {@code double}

   386      * after a widening primitive conversion.

   387      * @jls 5.1.2 Widening Primitive Conversions

   388      */

   389     public double doubleValue() {

   390         return (double)value;

   391     }

   392 

   393     /**

   394      * Returns a {@code String} object representing this

   395      * {@code Short}'s value.  The value is converted to signed

   396      * decimal representation and returned as a string, exactly as if

   397      * the {@code short} value were given as an argument to the

   398      * {@link java.lang.Short#toString(short)} method.

   399      *

   400      * @return  a string representation of the value of this object in

   401      *          base 10.

   402      */

   403     public String toString() {

   404         return Integer.toString((int)value);

   405     }

   406 

   407     /**

   408      * Returns a hash code for this {@code Short}; equal to the result

   409      * of invoking {@code intValue()}.

   410      *

   411      * @return a hash code value for this {@code Short}

   412      */

   413     @Override

   414     public int hashCode() {

   415         return Short.hashCode(value);

   416     }

   417 

   418     /**

   419      * Returns a hash code for a {@code short} value; compatible with

   420      * {@code Short.hashCode()}.

   421      *

   422      * @param value the value to hash

   423      * @return a hash code value for a {@code short} value.

   424      * @since 1.8

   425      */

   426     public static int hashCode(short value) {

   427         return (int)value;

   428     }

   429 

   430     /**

   431      * Compares this object to the specified object.  The result is

   432      * {@code true} if and only if the argument is not

   433      * {@code null} and is a {@code Short} object that

   434      * contains the same {@code short} value as this object.

   435      *

   436      * @param obj       the object to compare with

   437      * @return          {@code true} if the objects are the same;

   438      *                  {@code false} otherwise.

   439      */

   440     public boolean equals(Object obj) {

   441         if (obj instanceof Short) {

   442             return value == ((Short)obj).shortValue();

   443         }

   444         return false;

   445     }

   446 

   447     /**

   448      * Compares two {@code Short} objects numerically.

   449      *

   450      * @param   anotherShort   the {@code Short} to be compared.

   451      * @return  the value {@code 0} if this {@code Short} is

   452      *          equal to the argument {@code Short}; a value less than

   453      *          {@code 0} if this {@code Short} is numerically less

   454      *          than the argument {@code Short}; and a value greater than

   455      *           {@code 0} if this {@code Short} is numerically

   456      *           greater than the argument {@code Short} (signed

   457      *           comparison).

   458      * @since   1.2

   459      */

   460     public int compareTo(Short anotherShort) {

   461         return compare(this.value, anotherShort.value);

   462     }

   463 

   464     /**

   465      * Compares two {@code short} values numerically.

   466      * The value returned is identical to what would be returned by:

   467      * <pre>

   468      *    Short.valueOf(x).compareTo(Short.valueOf(y))

   469      * </pre>

   470      *

   471      * @param  x the first {@code short} to compare

   472      * @param  y the second {@code short} to compare

   473      * @return the value {@code 0} if {@code x == y};

   474      *         a value less than {@code 0} if {@code x < y}; and

   475      *         a value greater than {@code 0} if {@code x > y}

   476      * @since 1.7

   477      */

   478     public static int compare(short x, short y) {

   479         return x - y;

   480     }

   481 

   482     /**

   483      * Compares two {@code short} values numerically treating the values

   484      * as unsigned.

   485      *

   486      * @param  x the first {@code short} to compare

   487      * @param  y the second {@code short} to compare

   488      * @return the value {@code 0} if {@code x == y}; a value less

   489      *         than {@code 0} if {@code x < y} as unsigned values; and

   490      *         a value greater than {@code 0} if {@code x > y} as

   491      *         unsigned values

   492      * @since 9

   493      */

   494     public static int compareUnsigned(short x, short y) {

   495         return Short.toUnsignedInt(x) - Short.toUnsignedInt(y);

   496     }

   497 

   498     /**

   499      * The number of bits used to represent a {@code short} value in two's

   500      * complement binary form.

   501      * @since 1.5

   502      */

   503     public static final int SIZE = 16;

   504 

   505     /**

   506      * The number of bytes used to represent a {@code short} value in two's

   507      * complement binary form.

   508      *

   509      * @since 1.8

   510      */

   511     public static final int BYTES = SIZE / Byte.SIZE;

   512 

   513     /**

   514      * Returns the value obtained by reversing the order of the bytes in the

   515      * two's complement representation of the specified {@code short} value.

   516      *

   517      * @param i the value whose bytes are to be reversed

   518      * @return the value obtained by reversing (or, equivalently, swapping)

   519      *     the bytes in the specified {@code short} value.

   520      * @since 1.5

   521      */

   522     @HotSpotIntrinsicCandidate

   523     public static short reverseBytes(short i) {

   524         return (short) (((i & 0xFF00) >> 8) | (i << 8));

   525     }

   526 

   527 

   528     /**

   529      * Converts the argument to an {@code int} by an unsigned

   530      * conversion.  In an unsigned conversion to an {@code int}, the

   531      * high-order 16 bits of the {@code int} are zero and the

   532      * low-order 16 bits are equal to the bits of the {@code short} argument.

   533      *

   534      * Consequently, zero and positive {@code short} values are mapped

   535      * to a numerically equal {@code int} value and negative {@code

   536      * short} values are mapped to an {@code int} value equal to the

   537      * input plus 2<sup>16</sup>.

   538      *

   539      * @param  x the value to convert to an unsigned {@code int}

   540      * @return the argument converted to {@code int} by an unsigned

   541      *         conversion

   542      * @since 1.8

   543      */

   544     public static int toUnsignedInt(short x) {

   545         return ((int) x) & 0xffff;

   546     }

   547 

   548     /**

   549      * Converts the argument to a {@code long} by an unsigned

   550      * conversion.  In an unsigned conversion to a {@code long}, the

   551      * high-order 48 bits of the {@code long} are zero and the

   552      * low-order 16 bits are equal to the bits of the {@code short} argument.

   553      *

   554      * Consequently, zero and positive {@code short} values are mapped

   555      * to a numerically equal {@code long} value and negative {@code

   556      * short} values are mapped to a {@code long} value equal to the

   557      * input plus 2<sup>16</sup>.

   558      *

   559      * @param  x the value to convert to an unsigned {@code long}

   560      * @return the argument converted to {@code long} by an unsigned

   561      *         conversion

   562      * @since 1.8

   563      */

   564     public static long toUnsignedLong(short x) {

   565         return ((long) x) & 0xffffL;

   566     }

   567 

   568     /** use serialVersionUID from JDK 1.1. for interoperability */

   569     private static final long serialVersionUID = 7515723908773894738L;

   570 }