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.misc.CDS;
29 import jdk.internal.vm.annotation.AOTSafeClassInitializer;
30 import jdk.internal.vm.annotation.IntrinsicCandidate;
31 import jdk.internal.vm.annotation.Stable;
32
33 import java.lang.constant.Constable;
34 import java.lang.constant.DynamicConstantDesc;
35 import java.util.Arrays;
36 import java.util.HashMap;
37 import java.util.Locale;
38 import java.util.Map;
39 import java.util.Objects;
40 import java.util.Optional;
41
42 import static java.lang.constant.ConstantDescs.BSM_EXPLICIT_CAST;
43 import static java.lang.constant.ConstantDescs.CD_char;
44 import static java.lang.constant.ConstantDescs.DEFAULT_NAME;
45
46 /**
47 * The {@code Character} class is the {@linkplain
48 * java.lang##wrapperClass wrapper class} for values of the primitive
188 * surrogate ranges as undefined characters. For example,
189 * {@code Character.isLetter('\u005CuD840')} returns {@code false}, even though
190 * this specific value if followed by any low-surrogate value in a string
191 * would represent a letter.
192 *
193 * <li>The methods that accept an {@code int} value support all
194 * Unicode characters, including supplementary characters. For
195 * example, {@code Character.isLetter(0x2F81A)} returns
196 * {@code true} because the code point value represents a letter
197 * (a CJK ideograph).
198 * </ul>
199 *
200 * <p>In the Java SE API documentation, <em>Unicode code point</em> is
201 * used for character values in the range between U+0000 and U+10FFFF,
202 * and <em>Unicode code unit</em> is used for 16-bit
203 * {@code char} values that are code units of the <em>UTF-16</em>
204 * encoding. For more information on Unicode terminology, refer to the
205 * <a href="http://www.unicode.org/glossary/">Unicode Glossary</a>.
206 *
207 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
208 * class; programmers should treat instances that are
209 * {@linkplain #equals(Object) equal} as interchangeable and should not
210 * use instances for synchronization, or unpredictable behavior may
211 * occur. For example, in a future release, synchronization may fail.
212 *
213 * @spec https://www.unicode.org/reports/tr44 Unicode Character Database
214 * @author Lee Boynton
215 * @author Guy Steele
216 * @author Akira Tanaka
217 * @author Martin Buchholz
218 * @author Ulf Zibis
219 * @since 1.0
220 */
221 @jdk.internal.ValueBased
222 public final
223 class Character implements java.io.Serializable, Comparable<Character>, Constable {
224 /**
225 * The minimum radix available for conversion to and from strings.
226 * The constant value of this field is the smallest value permitted
227 * for the radix argument in radix-conversion methods such as the
228 * {@code digit} method, the {@code forDigit} method, and the
229 * {@code toString} method of class {@code Integer}.
230 *
231 * @see Character#digit(char, int)
232 * @see Character#forDigit(int, int)
233 * @see Integer#toString(int, int)
234 * @see Integer#valueOf(String)
235 */
236 public static final int MIN_RADIX = 2;
237
238 /**
239 * The maximum radix available for conversion to and from strings.
240 * The constant value of this field is the largest value permitted
241 * for the radix argument in radix-conversion methods such as the
242 * {@code digit} method, the {@code forDigit} method, and the
243 * {@code toString} method of class {@code Integer}.
9395 */
9396 private final char value;
9397
9398 /** use serialVersionUID from JDK 1.0.2 for interoperability */
9399 @java.io.Serial
9400 private static final long serialVersionUID = 3786198910865385080L;
9401
9402 /**
9403 * Constructs a newly allocated {@code Character} object that
9404 * represents the specified {@code char} value.
9405 *
9406 * @param value the value to be represented by the
9407 * {@code Character} object.
9408 *
9409 * @deprecated
9410 * It is rarely appropriate to use this constructor. The static factory
9411 * {@link #valueOf(char)} is generally a better choice, as it is
9412 * likely to yield significantly better space and time performance.
9413 */
9414 @Deprecated(since="9")
9415 public Character(char value) {
9416 this.value = value;
9417 }
9418
9419 @AOTSafeClassInitializer
9420 private static final class CharacterCache {
9421 private CharacterCache(){}
9422
9423 @Stable
9424 static final Character[] cache;
9425 static Character[] archivedCache;
9426
9427 static {
9428 int size = 127 + 1;
9429
9430 // Load and use the archived cache if it exists
9431 CDS.initializeFromArchive(CharacterCache.class);
9432 if (archivedCache == null) {
9433 Character[] c = new Character[size];
9434 for (int i = 0; i < size; i++) {
9435 c[i] = new Character((char) i);
9436 }
9437 archivedCache = c;
9438 }
9439 cache = archivedCache;
9440 assert cache.length == size;
9441 }
9442 }
9443
9444 /**
9445 * Returns a {@code Character} instance representing the specified
9446 * {@code char} value.
9447 * If a new {@code Character} instance is not required, this method
9448 * should generally be used in preference to the constructor
9449 * {@link #Character(char)}, as this method is likely to yield
9450 * significantly better space and time performance by caching
9451 * frequently requested values.
9452 *
9453 * This method will always cache values in the range {@code
9454 * '\u005Cu0000'} to {@code '\u005Cu007F'}, inclusive, and may
9455 * cache other values outside of this range.
9456 *
9457 * @param c a char value.
9458 * @return a {@code Character} instance representing {@code c}.
9459 * @since 1.5
9460 */
9461 @IntrinsicCandidate
9462 public static Character valueOf(char c) {
9463 if (c <= 127) { // must cache
9464 return CharacterCache.cache[(int)c];
9465 }
9466 return new Character(c);
9467 }
9468
9469 /**
9470 * Returns the value of this {@code Character} object.
9471 * @return the primitive {@code char} value represented by
9472 * this object.
9473 */
9474 @IntrinsicCandidate
9475 public char charValue() {
9476 return value;
9477 }
9478
9479 /**
9480 * Returns a hash code for this {@code Character}; equal to the result
9481 * of invoking {@code charValue()}.
9482 *
9483 * @return a hash code value for this {@code Character}
9484 */
|
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.misc.CDS;
29 import jdk.internal.misc.PreviewFeatures;
30 import jdk.internal.value.DeserializeConstructor;
31 import jdk.internal.value.ValueClass;
32 import jdk.internal.vm.annotation.AOTSafeClassInitializer;
33 import jdk.internal.vm.annotation.IntrinsicCandidate;
34 import jdk.internal.vm.annotation.Stable;
35
36 import java.lang.constant.Constable;
37 import java.lang.constant.DynamicConstantDesc;
38 import java.util.Arrays;
39 import java.util.HashMap;
40 import java.util.Locale;
41 import java.util.Map;
42 import java.util.Objects;
43 import java.util.Optional;
44
45 import static java.lang.constant.ConstantDescs.BSM_EXPLICIT_CAST;
46 import static java.lang.constant.ConstantDescs.CD_char;
47 import static java.lang.constant.ConstantDescs.DEFAULT_NAME;
48
49 /**
50 * The {@code Character} class is the {@linkplain
51 * java.lang##wrapperClass wrapper class} for values of the primitive
191 * surrogate ranges as undefined characters. For example,
192 * {@code Character.isLetter('\u005CuD840')} returns {@code false}, even though
193 * this specific value if followed by any low-surrogate value in a string
194 * would represent a letter.
195 *
196 * <li>The methods that accept an {@code int} value support all
197 * Unicode characters, including supplementary characters. For
198 * example, {@code Character.isLetter(0x2F81A)} returns
199 * {@code true} because the code point value represents a letter
200 * (a CJK ideograph).
201 * </ul>
202 *
203 * <p>In the Java SE API documentation, <em>Unicode code point</em> is
204 * used for character values in the range between U+0000 and U+10FFFF,
205 * and <em>Unicode code unit</em> is used for 16-bit
206 * {@code char} values that are code units of the <em>UTF-16</em>
207 * encoding. For more information on Unicode terminology, refer to the
208 * <a href="http://www.unicode.org/glossary/">Unicode Glossary</a>.
209 *
210 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
211 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
212 * as interchangeable and should not use instances for synchronization, mutexes, or
213 * with {@linkplain java.lang.ref.Reference object references}.
214 *
215 * <div class="preview-block">
216 * <div class="preview-comment">
217 * When preview features are enabled, {@code Character} is a {@linkplain Class#isValue value class}.
218 * Use of value class instances for synchronization, mutexes, or with
219 * {@linkplain java.lang.ref.Reference object references} result in
220 * {@link IdentityException}.
221 * </div>
222 * </div>
223 *
224 * @spec https://www.unicode.org/reports/tr44 Unicode Character Database
225 * @author Lee Boynton
226 * @author Guy Steele
227 * @author Akira Tanaka
228 * @author Martin Buchholz
229 * @author Ulf Zibis
230 * @since 1.0
231 */
232 @jdk.internal.MigratedValueClass
233 @jdk.internal.ValueBased
234 public final class Character implements java.io.Serializable, Comparable<Character>, Constable {
235 /**
236 * The minimum radix available for conversion to and from strings.
237 * The constant value of this field is the smallest value permitted
238 * for the radix argument in radix-conversion methods such as the
239 * {@code digit} method, the {@code forDigit} method, and the
240 * {@code toString} method of class {@code Integer}.
241 *
242 * @see Character#digit(char, int)
243 * @see Character#forDigit(int, int)
244 * @see Integer#toString(int, int)
245 * @see Integer#valueOf(String)
246 */
247 public static final int MIN_RADIX = 2;
248
249 /**
250 * The maximum radix available for conversion to and from strings.
251 * The constant value of this field is the largest value permitted
252 * for the radix argument in radix-conversion methods such as the
253 * {@code digit} method, the {@code forDigit} method, and the
254 * {@code toString} method of class {@code Integer}.
9406 */
9407 private final char value;
9408
9409 /** use serialVersionUID from JDK 1.0.2 for interoperability */
9410 @java.io.Serial
9411 private static final long serialVersionUID = 3786198910865385080L;
9412
9413 /**
9414 * Constructs a newly allocated {@code Character} object that
9415 * represents the specified {@code char} value.
9416 *
9417 * @param value the value to be represented by the
9418 * {@code Character} object.
9419 *
9420 * @deprecated
9421 * It is rarely appropriate to use this constructor. The static factory
9422 * {@link #valueOf(char)} is generally a better choice, as it is
9423 * likely to yield significantly better space and time performance.
9424 */
9425 @Deprecated(since="9")
9426 @DeserializeConstructor
9427 public Character(char value) {
9428 this.value = value;
9429 }
9430
9431 @AOTSafeClassInitializer
9432 private static final class CharacterCache {
9433 private CharacterCache(){}
9434
9435 @Stable
9436 static final Character[] cache;
9437 static Character[] archivedCache;
9438
9439 static {
9440 int size = 127 + 1;
9441
9442 // Load and use the archived cache if it exists
9443 CDS.initializeFromArchive(CharacterCache.class);
9444 if (archivedCache == null) {
9445 Character[] c = newCacheArray(size);
9446 for (int i = 0; i < size; i++) {
9447 c[i] = new Character((char) i);
9448 }
9449 archivedCache = c;
9450 }
9451 cache = archivedCache;
9452 assert cache.length == size;
9453 }
9454
9455 private static Character[] newCacheArray(int size) {
9456 // ValueClass.newReferenceArray requires a value class component.
9457 if (PreviewFeatures.isEnabled()) {
9458 return (Character[]) ValueClass.newReferenceArray(Character.class, size);
9459 }
9460 return new Character[size];
9461 }
9462 }
9463
9464 /**
9465 * Returns a {@code Character} instance representing the specified
9466 * {@code char} value.
9467 * <div class="preview-block">
9468 * <div class="preview-comment">
9469 * <p>
9470 * - When preview features are NOT enabled, {@code Character} is an identity class.
9471 * If a new {@code Character} instance is not required, this method
9472 * should generally be used in preference to the constructor
9473 * {@link #Character(char)}, as this method is likely to yield
9474 * significantly better space and time performance by caching
9475 * frequently requested values.
9476 * This method will always cache values in the range {@code
9477 * '\u005Cu0000'} to {@code '\u005Cu007F'}, inclusive, and may
9478 * cache other values outside of this range.
9479 * </p>
9480 * <p>
9481 * - When preview features are enabled, {@code Character} is a {@linkplain Class#isValue value class}.
9482 * The {@code valueOf} behavior is the same as invoking the constructor,
9483 * whether cached or not.
9484 * </p>
9485 * </div>
9486 * </div>
9487 *
9488 * @param c a char value.
9489 * @return a {@code Character} instance representing {@code c}.
9490 * @since 1.5
9491 */
9492 @IntrinsicCandidate
9493 public static Character valueOf(char c) {
9494 if (c <= 127) { // must cache
9495 return CharacterCache.cache[(int) c];
9496 }
9497 return new Character(c);
9498 }
9499
9500 /**
9501 * Returns the value of this {@code Character} object.
9502 * @return the primitive {@code char} value represented by
9503 * this object.
9504 */
9505 @IntrinsicCandidate
9506 public char charValue() {
9507 return value;
9508 }
9509
9510 /**
9511 * Returns a hash code for this {@code Character}; equal to the result
9512 * of invoking {@code charValue()}.
9513 *
9514 * @return a hash code value for this {@code Character}
9515 */
|