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