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