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
152 * surrogate ranges as undefined characters. For example,
153 * {@code Character.isLetter('\u005CuD840')} returns {@code false}, even though
154 * this specific value if followed by any low-surrogate value in a string
155 * would represent a letter.
156 *
157 * <li>The methods that accept an {@code int} value support all
158 * Unicode characters, including supplementary characters. For
159 * example, {@code Character.isLetter(0x2F81A)} returns
160 * {@code true} because the code point value represents a letter
161 * (a CJK ideograph).
162 * </ul>
163 *
164 * <p>In the Java SE API documentation, <em>Unicode code point</em> is
165 * used for character values in the range between U+0000 and U+10FFFF,
166 * and <em>Unicode code unit</em> is used for 16-bit
167 * {@code char} values that are code units of the <em>UTF-16</em>
168 * encoding. For more information on Unicode terminology, refer to the
169 * <a href="http://www.unicode.org/glossary/">Unicode Glossary</a>.
170 *
171 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
172 * class; programmers should treat instances that are
173 * {@linkplain #equals(Object) equal} as interchangeable and should not
174 * use instances for synchronization, or unpredictable behavior may
175 * occur. For example, in a future release, synchronization may fail.
176 *
177 * @spec https://www.unicode.org/reports/tr44 Unicode Character Database
178 * @author Lee Boynton
179 * @author Guy Steele
180 * @author Akira Tanaka
181 * @author Martin Buchholz
182 * @author Ulf Zibis
183 * @since 1.0
184 */
185 @jdk.internal.ValueBased
186 public final
187 class Character implements java.io.Serializable, Comparable<Character>, Constable {
188 /**
189 * The minimum radix available for conversion to and from strings.
190 * The constant value of this field is the smallest value permitted
191 * for the radix argument in radix-conversion methods such as the
192 * {@code digit} method, the {@code forDigit} method, and the
193 * {@code toString} method of class {@code Integer}.
194 *
195 * @see Character#digit(char, int)
196 * @see Character#forDigit(int, int)
197 * @see Integer#toString(int, int)
198 * @see Integer#valueOf(String)
199 */
200 public static final int MIN_RADIX = 2;
201
202 /**
203 * The maximum radix available for conversion to and from strings.
204 * The constant value of this field is the largest value permitted
205 * for the radix argument in radix-conversion methods such as the
206 * {@code digit} method, the {@code forDigit} method, and the
207 * {@code toString} method of class {@code Integer}.
9391 static {
9392 int size = 127 + 1;
9393
9394 // Load and use the archived cache if it exists
9395 CDS.initializeFromArchive(CharacterCache.class);
9396 if (archivedCache == null) {
9397 Character[] c = new Character[size];
9398 for (int i = 0; i < size; i++) {
9399 c[i] = new Character((char) i);
9400 }
9401 archivedCache = c;
9402 }
9403 cache = archivedCache;
9404 assert cache.length == size;
9405 }
9406 }
9407
9408 /**
9409 * Returns a {@code Character} instance representing the specified
9410 * {@code char} value.
9411 * If a new {@code Character} instance is not required, this method
9412 * should generally be used in preference to the constructor
9413 * {@link #Character(char)}, as this method is likely to yield
9414 * significantly better space and time performance by caching
9415 * frequently requested values.
9416 *
9417 * This method will always cache values in the range {@code
9418 * '\u005Cu0000'} to {@code '\u005Cu007F'}, inclusive, and may
9419 * cache other values outside of this range.
9420 *
9421 * @param c a char value.
9422 * @return a {@code Character} instance representing {@code c}.
9423 * @since 1.5
9424 */
9425 @IntrinsicCandidate
9426 public static Character valueOf(char c) {
9427 if (c <= 127) { // must cache
9428 return CharacterCache.cache[(int)c];
9429 }
9430 return new Character(c);
9431 }
9432
9433 /**
9434 * Returns the value of this {@code Character} object.
9435 * @return the primitive {@code char} value represented by
9436 * this object.
9437 */
9438 @IntrinsicCandidate
9439 public char charValue() {
9440 return value;
9441 }
9442
9443 /**
9444 * Returns a hash code for this {@code Character}; equal to the result
9445 * of invoking {@code charValue()}.
|
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
154 * surrogate ranges as undefined characters. For example,
155 * {@code Character.isLetter('\u005CuD840')} returns {@code false}, even though
156 * this specific value if followed by any low-surrogate value in a string
157 * would represent a letter.
158 *
159 * <li>The methods that accept an {@code int} value support all
160 * Unicode characters, including supplementary characters. For
161 * example, {@code Character.isLetter(0x2F81A)} returns
162 * {@code true} because the code point value represents a letter
163 * (a CJK ideograph).
164 * </ul>
165 *
166 * <p>In the Java SE API documentation, <em>Unicode code point</em> is
167 * used for character values in the range between U+0000 and U+10FFFF,
168 * and <em>Unicode code unit</em> is used for 16-bit
169 * {@code char} values that are code units of the <em>UTF-16</em>
170 * encoding. For more information on Unicode terminology, refer to the
171 * <a href="http://www.unicode.org/glossary/">Unicode Glossary</a>.
172 *
173 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
174 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
175 * as interchangeable and should not use instances for synchronization, mutexes, or
176 * with {@linkplain java.lang.ref.Reference object references}.
177 *
178 * <div class="preview-block">
179 * <div class="preview-comment">
180 * When preview features are enabled, {@code Character} is a {@linkplain Class#isValue value class}.
181 * Use of value class instances for synchronization, mutexes, or with
182 * {@linkplain java.lang.ref.Reference object references} result in
183 * {@link IdentityException}.
184 * </div>
185 * </div>
186 *
187 * @spec https://www.unicode.org/reports/tr44 Unicode Character Database
188 * @author Lee Boynton
189 * @author Guy Steele
190 * @author Akira Tanaka
191 * @author Martin Buchholz
192 * @author Ulf Zibis
193 * @since 1.0
194 */
195 @jdk.internal.MigratedValueClass
196 @jdk.internal.ValueBased
197 public final class Character implements java.io.Serializable, Comparable<Character>, Constable {
198 /**
199 * The minimum radix available for conversion to and from strings.
200 * The constant value of this field is the smallest value permitted
201 * for the radix argument in radix-conversion methods such as the
202 * {@code digit} method, the {@code forDigit} method, and the
203 * {@code toString} method of class {@code Integer}.
204 *
205 * @see Character#digit(char, int)
206 * @see Character#forDigit(int, int)
207 * @see Integer#toString(int, int)
208 * @see Integer#valueOf(String)
209 */
210 public static final int MIN_RADIX = 2;
211
212 /**
213 * The maximum radix available for conversion to and from strings.
214 * The constant value of this field is the largest value permitted
215 * for the radix argument in radix-conversion methods such as the
216 * {@code digit} method, the {@code forDigit} method, and the
217 * {@code toString} method of class {@code Integer}.
9401 static {
9402 int size = 127 + 1;
9403
9404 // Load and use the archived cache if it exists
9405 CDS.initializeFromArchive(CharacterCache.class);
9406 if (archivedCache == null) {
9407 Character[] c = new Character[size];
9408 for (int i = 0; i < size; i++) {
9409 c[i] = new Character((char) i);
9410 }
9411 archivedCache = c;
9412 }
9413 cache = archivedCache;
9414 assert cache.length == size;
9415 }
9416 }
9417
9418 /**
9419 * Returns a {@code Character} instance representing the specified
9420 * {@code char} value.
9421 * <div class="preview-block">
9422 * <div class="preview-comment">
9423 * <p>
9424 * - When preview features are NOT enabled, {@code Character} is an identity class.
9425 * If a new {@code Character} instance is not required, this method
9426 * should generally be used in preference to the constructor
9427 * {@link #Character(char)}, as this method is likely to yield
9428 * significantly better space and time performance by caching
9429 * frequently requested values.
9430 * This method will always cache values in the range {@code
9431 * '\u005Cu0000'} to {@code '\u005Cu007F'}, inclusive, and may
9432 * cache other values outside of this range.
9433 * </p>
9434 * <p>
9435 * - When preview features are enabled, {@code Character} is a {@linkplain Class#isValue value class}.
9436 * The {@code valueOf} behavior is the same as invoking the constructor,
9437 * whether cached or not.
9438 * </p>
9439 * </div>
9440 * </div>
9441 *
9442 * @param c a char value.
9443 * @return a {@code Character} instance representing {@code c}.
9444 * @since 1.5
9445 */
9446 @IntrinsicCandidate
9447 @DeserializeConstructor
9448 public static Character valueOf(char c) {
9449 if (c <= 127) { // must cache
9450 return CharacterCache.cache[(int)c];
9451 }
9452 return new Character(c);
9453 }
9454
9455 /**
9456 * Returns the value of this {@code Character} object.
9457 * @return the primitive {@code char} value represented by
9458 * this object.
9459 */
9460 @IntrinsicCandidate
9461 public char charValue() {
9462 return value;
9463 }
9464
9465 /**
9466 * Returns a hash code for this {@code Character}; equal to the result
9467 * of invoking {@code charValue()}.
|