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 java.lang.annotation.Native;
29 import java.lang.invoke.MethodHandles;
30 import java.lang.constant.Constable;
31 import java.lang.constant.ConstantDesc;
32 import java.math.*;
33 import java.util.Objects;
34 import java.util.Optional;
35
36 import jdk.internal.misc.CDS;
37 import jdk.internal.util.DecimalDigits;
38 import jdk.internal.vm.annotation.AOTSafeClassInitializer;
39 import jdk.internal.vm.annotation.ForceInline;
40 import jdk.internal.vm.annotation.IntrinsicCandidate;
41 import jdk.internal.vm.annotation.Stable;
42
43 import static java.lang.Character.digit;
44 import static java.lang.String.COMPACT_STRINGS;
45
46 /**
47 * The {@code Long} class is the {@linkplain
48 * java.lang##wrapperClass wrapper class} for values of the primitive
49 * type {@code long}. An object of type {@code Long} contains a
50 * single field whose type is {@code long}.
51 *
52 * <p> In addition, this class provides several methods for converting
53 * a {@code long} to a {@code String} and a {@code String} to a {@code
54 * long}, as well as other constants and methods useful when dealing
55 * with a {@code long}.
56 *
57 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
58 * class; programmers should treat instances that are
59 * {@linkplain #equals(Object) equal} as interchangeable and should not
60 * use instances for synchronization, or unpredictable behavior may
61 * occur. For example, in a future release, synchronization may fail.
62 *
63 * <p>Implementation note: The implementations of the "bit twiddling"
64 * methods (such as {@link #highestOneBit(long) highestOneBit} and
65 * {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are
66 * based on material from Henry S. Warren, Jr.'s <cite>Hacker's
67 * Delight</cite>, (Addison Wesley, 2002) and <cite>Hacker's
68 * Delight, Second Edition</cite>, (Pearson Education, 2013).
69 *
70 * @since 1.0
71 */
72 @jdk.internal.ValueBased
73 public final class Long extends Number
74 implements Comparable<Long>, Constable, ConstantDesc {
75 /**
76 * A constant holding the minimum value a {@code long} can
77 * have, -2<sup>63</sup>.
78 */
79 @Native public static final long MIN_VALUE = 0x8000000000000000L;
80
81 /**
82 * A constant holding the maximum value a {@code long} can
83 * have, 2<sup>63</sup>-1.
84 */
85 @Native public static final long MAX_VALUE = 0x7fffffffffffffffL;
86
87 /**
88 * The {@code Class} instance representing the primitive type
89 * {@code long}.
90 *
91 * @since 1.1
92 */
93 public static final Class<Long> TYPE = Class.getPrimitiveClass("long");
909 */
910 public static Long valueOf(String s) throws NumberFormatException
911 {
912 return Long.valueOf(parseLong(s, 10));
913 }
914
915 @AOTSafeClassInitializer
916 private static final class LongCache {
917 private LongCache() {}
918
919 @Stable
920 static final Long[] cache;
921 static Long[] archivedCache;
922
923 static {
924 int size = -(-128) + 127 + 1;
925
926 // Load and use the archived cache if it exists
927 CDS.initializeFromArchive(LongCache.class);
928 if (archivedCache == null) {
929 Long[] c = new Long[size];
930 long value = -128;
931 for(int i = 0; i < size; i++) {
932 c[i] = new Long(value++);
933 }
934 archivedCache = c;
935 }
936 cache = archivedCache;
937 assert cache.length == size;
938 }
939 }
940
941 /**
942 * Returns a {@code Long} instance representing the specified
943 * {@code long} value.
944 * If a new {@code Long} instance is not required, this method
945 * should generally be used in preference to the constructor
946 * {@link #Long(long)}, as this method is likely to yield
947 * significantly better space and time performance by caching
948 * frequently requested values.
949 *
950 * This method will always cache values in the range -128 to 127,
951 * inclusive, and may cache other values outside of this range.
952 *
953 * @param l a long value.
954 * @return a {@code Long} instance representing {@code l}.
955 * @since 1.5
956 */
957 @IntrinsicCandidate
958 public static Long valueOf(long l) {
959 final int offset = 128;
960 if (l >= -128 && l <= 127) { // will cache
961 return LongCache.cache[(int)l + offset];
962 }
963 return new Long(l);
964 }
965
966 /**
967 * Decodes a {@code String} into a {@code Long}.
968 * Accepts decimal, hexadecimal, and octal numbers given by the
969 * following grammar:
970 *
971 * <blockquote>
972 * <dl>
973 * <dt><i>DecodableString:</i>
974 * <dd><i>Sign<sub>opt</sub> DecimalNumeral</i>
975 * <dd><i>Sign<sub>opt</sub></i> {@code 0x} <i>HexDigits</i>
976 * <dd><i>Sign<sub>opt</sub></i> {@code 0X} <i>HexDigits</i>
977 * <dd><i>Sign<sub>opt</sub></i> {@code #} <i>HexDigits</i>
978 * <dd><i>Sign<sub>opt</sub></i> {@code 0} <i>OctalDigits</i>
979 *
980 * <dt><i>Sign:</i>
981 * <dd>{@code -}
1056 /**
1057 * The value of the {@code Long}.
1058 *
1059 * @serial
1060 */
1061 private final long value;
1062
1063 /**
1064 * Constructs a newly allocated {@code Long} object that
1065 * represents the specified {@code long} argument.
1066 *
1067 * @param value the value to be represented by the
1068 * {@code Long} object.
1069 *
1070 * @deprecated
1071 * It is rarely appropriate to use this constructor. The static factory
1072 * {@link #valueOf(long)} is generally a better choice, as it is
1073 * likely to yield significantly better space and time performance.
1074 */
1075 @Deprecated(since="9")
1076 public Long(long value) {
1077 this.value = value;
1078 }
1079
1080 /**
1081 * Constructs a newly allocated {@code Long} object that
1082 * represents the {@code long} value indicated by the
1083 * {@code String} parameter. The string is converted to a
1084 * {@code long} value in exactly the manner used by the
1085 * {@code parseLong} method for radix 10.
1086 *
1087 * @param s the {@code String} to be converted to a
1088 * {@code Long}.
1089 * @throws NumberFormatException if the {@code String} does not
1090 * contain a parsable {@code long}.
1091 *
1092 * @deprecated
1093 * It is rarely appropriate to use this constructor.
1094 * Use {@link #parseLong(String)} to convert a string to a
1095 * {@code long} primitive, or use {@link #valueOf(String)}
|
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 java.lang.annotation.Native;
29 import java.lang.invoke.MethodHandles;
30 import java.lang.constant.Constable;
31 import java.lang.constant.ConstantDesc;
32 import java.math.*;
33 import java.util.Objects;
34 import java.util.Optional;
35
36 import jdk.internal.misc.CDS;
37 import jdk.internal.misc.PreviewFeatures;
38 import jdk.internal.value.Deserializer;
39 import jdk.internal.value.ValueClass;
40 import jdk.internal.util.DecimalDigits;
41 import jdk.internal.vm.annotation.AOTSafeClassInitializer;
42 import jdk.internal.vm.annotation.ForceInline;
43 import jdk.internal.vm.annotation.IntrinsicCandidate;
44 import jdk.internal.vm.annotation.Stable;
45
46 import static java.lang.Character.digit;
47 import static java.lang.String.COMPACT_STRINGS;
48
49 /**
50 * The {@code Long} class is the {@linkplain
51 * java.lang##wrapperClass wrapper class} for values of the primitive
52 * type {@code long}. An object of type {@code Long} contains a
53 * single field whose type is {@code long}.
54 *
55 * <p> In addition, this class provides several methods for converting
56 * a {@code long} to a {@code String} and a {@code String} to a {@code
57 * long}, as well as other constants and methods useful when dealing
58 * with a {@code long}.
59 *
60 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
61 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
62 * as interchangeable and should not use instances for synchronization or
63 * with {@linkplain java.lang.ref.Reference object references}.
64 *
65 * <div class="preview-block">
66 * <div class="preview-comment">
67 * When preview features are enabled, {@code Long} is a {@linkplain Class#isValue value class}.
68 * Use of value class instances for synchronization or with
69 * {@linkplain java.lang.ref.Reference object references} result in
70 * {@link IdentityException}.
71 * </div>
72 * </div>
73 *
74 *
75 * <p>Implementation note: The implementations of the "bit twiddling"
76 * methods (such as {@link #highestOneBit(long) highestOneBit} and
77 * {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are
78 * based on material from Henry S. Warren, Jr.'s <cite>Hacker's
79 * Delight</cite>, (Addison Wesley, 2002) and <cite>Hacker's
80 * Delight, Second Edition</cite>, (Pearson Education, 2013).
81 *
82 * @since 1.0
83 */
84 @jdk.internal.ValueBased
85 public final /*value*/ class Long extends Number
86 implements Comparable<Long>, Constable, ConstantDesc {
87 /**
88 * A constant holding the minimum value a {@code long} can
89 * have, -2<sup>63</sup>.
90 */
91 @Native public static final long MIN_VALUE = 0x8000000000000000L;
92
93 /**
94 * A constant holding the maximum value a {@code long} can
95 * have, 2<sup>63</sup>-1.
96 */
97 @Native public static final long MAX_VALUE = 0x7fffffffffffffffL;
98
99 /**
100 * The {@code Class} instance representing the primitive type
101 * {@code long}.
102 *
103 * @since 1.1
104 */
105 public static final Class<Long> TYPE = Class.getPrimitiveClass("long");
921 */
922 public static Long valueOf(String s) throws NumberFormatException
923 {
924 return Long.valueOf(parseLong(s, 10));
925 }
926
927 @AOTSafeClassInitializer
928 private static final class LongCache {
929 private LongCache() {}
930
931 @Stable
932 static final Long[] cache;
933 static Long[] archivedCache;
934
935 static {
936 int size = -(-128) + 127 + 1;
937
938 // Load and use the archived cache if it exists
939 CDS.initializeFromArchive(LongCache.class);
940 if (archivedCache == null) {
941 Long[] c = newCacheArray(size);
942 long value = -128;
943 for(int i = 0; i < size; i++) {
944 c[i] = new Long(value++);
945 }
946 archivedCache = c;
947 }
948 cache = archivedCache;
949 assert cache.length == size;
950 }
951
952 private static Long[] newCacheArray(int size) {
953 // ValueClass.newReferenceArray requires a value class component.
954 if (PreviewFeatures.isEnabled()) {
955 return (Long[]) ValueClass.newReferenceArray(Long.class, size);
956 }
957 return new Long[size];
958 }
959 }
960
961 /**
962 * Returns a {@code Long} instance representing the specified
963 * {@code long} value.
964 * <div class="preview-block">
965 * <div class="preview-comment">
966 * <p>
967 * - When preview features are NOT enabled, {@code Long} is an identity class.
968 * If a new {@code Long} instance is not required, this method
969 * should generally be used in preference to the constructor
970 * {@link #Long(long)}, as this method is likely to yield
971 * significantly better space and time performance by caching
972 * frequently requested values.
973 * This method will always cache values in the range -128 to 127,
974 * inclusive, and may cache other values outside of this range.
975 * </p>
976 * <p>
977 * - When preview features are enabled, {@code Long} is a {@linkplain Class#isValue value class}.
978 * The {@code valueOf} behavior is the same as invoking the constructor,
979 * whether cached or not.
980 * </p>
981 * </div>
982 * </div>
983 *
984 * @param l a long value.
985 * @return a {@code Long} instance representing {@code l}.
986 * @since 1.5
987 */
988 @IntrinsicCandidate
989 public static Long valueOf(long l) {
990 if (l >= -128 && l <= 127) { // will cache
991 final int offset = 128;
992 return LongCache.cache[(int) l + offset];
993 }
994 return new Long(l);
995 }
996
997 /**
998 * Decodes a {@code String} into a {@code Long}.
999 * Accepts decimal, hexadecimal, and octal numbers given by the
1000 * following grammar:
1001 *
1002 * <blockquote>
1003 * <dl>
1004 * <dt><i>DecodableString:</i>
1005 * <dd><i>Sign<sub>opt</sub> DecimalNumeral</i>
1006 * <dd><i>Sign<sub>opt</sub></i> {@code 0x} <i>HexDigits</i>
1007 * <dd><i>Sign<sub>opt</sub></i> {@code 0X} <i>HexDigits</i>
1008 * <dd><i>Sign<sub>opt</sub></i> {@code #} <i>HexDigits</i>
1009 * <dd><i>Sign<sub>opt</sub></i> {@code 0} <i>OctalDigits</i>
1010 *
1011 * <dt><i>Sign:</i>
1012 * <dd>{@code -}
1087 /**
1088 * The value of the {@code Long}.
1089 *
1090 * @serial
1091 */
1092 private final long value;
1093
1094 /**
1095 * Constructs a newly allocated {@code Long} object that
1096 * represents the specified {@code long} argument.
1097 *
1098 * @param value the value to be represented by the
1099 * {@code Long} object.
1100 *
1101 * @deprecated
1102 * It is rarely appropriate to use this constructor. The static factory
1103 * {@link #valueOf(long)} is generally a better choice, as it is
1104 * likely to yield significantly better space and time performance.
1105 */
1106 @Deprecated(since="9")
1107 @Deserializer("value")
1108 public Long(long value) {
1109 this.value = value;
1110 }
1111
1112 /**
1113 * Constructs a newly allocated {@code Long} object that
1114 * represents the {@code long} value indicated by the
1115 * {@code String} parameter. The string is converted to a
1116 * {@code long} value in exactly the manner used by the
1117 * {@code parseLong} method for radix 10.
1118 *
1119 * @param s the {@code String} to be converted to a
1120 * {@code Long}.
1121 * @throws NumberFormatException if the {@code String} does not
1122 * contain a parsable {@code long}.
1123 *
1124 * @deprecated
1125 * It is rarely appropriate to use this constructor.
1126 * Use {@link #parseLong(String)} to convert a string to a
1127 * {@code long} primitive, or use {@link #valueOf(String)}
|