/*

 * Copyright (c) 2002, 2009, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.lang;

import java.util.Arrays;

import java.util.Map;

import java.util.HashMap;

import java.util.Locale;

/**

 * The <code>Character</code> class wraps a value of the primitive

 * type <code>char</code> in an object. An object of type

 * <code>Character</code> contains a single field whose type is

 * <code>char</code>.

 * <p>

 * In addition, this class provides several methods for determining

 * a character's category (lowercase letter, digit, etc.) and for converting

 * characters from uppercase to lowercase and vice versa.

 * <p>

 * Character information is based on the Unicode Standard, version 5.1.0.

 * <p>

 * The methods and data of class <code>Character</code> are defined by

 * the information in the <i>UnicodeData</i> file that is part of the

 * Unicode Character Database maintained by the Unicode

 * Consortium. This file specifies various properties including name

 * and general category for every defined Unicode code point or

 * character range.

 * <p>

 * The file and its description are available from the Unicode Consortium at:

 * <ul>

 * <li><a href="http://www.unicode.org">http://www.unicode.org</a>

 * </ul>

 *

 * <h4><a name="unicode">Unicode Character Representations</a></h4>

 *

 * <p>The <code>char</code> data type (and therefore the value that a

 * <code>Character</code> object encapsulates) are based on the

 * original Unicode specification, which defined characters as

 * fixed-width 16-bit entities. The Unicode standard has since been

 * changed to allow for characters whose representation requires more

 * than 16 bits.  The range of legal <em>code point</em>s is now

 * U+0000 to U+10FFFF, known as <em>Unicode scalar value</em>.

 * (Refer to the <a

 * href="http://www.unicode.org/reports/tr27/#notation"><i>

 * definition</i></a> of the U+<i>n</i> notation in the Unicode

 * standard.)

 *

 * <p><a name="BMP">The set of characters from U+0000 to U+FFFF is

 * sometimes referred to as the <em>Basic Multilingual Plane (BMP)</em>.

 * <a name="supplementary">Characters</a> whose code points are greater

 * than U+FFFF are called <em>supplementary character</em>s.  The Java

 * platform uses the UTF-16 representation in <code>char</code> arrays and

 * in the <code>String</code> and <code>StringBuffer</code> classes. In

 * this representation, supplementary characters are represented as a pair

 * of <code>char</code> values, the first from the <em>high-surrogates</em>

 * range, (\uD800-\uDBFF), the second from the

 * <em>low-surrogates</em> range (&#92;uDC00-&#92;uDFFF).

 *

 * <p>A <code>char</code> value, therefore, represents Basic

 * Multilingual Plane (BMP) code points, including the surrogate

 * code points, or code units of the UTF-16 encoding. An

 * <code>int</code> value represents all Unicode code points,

 * including supplementary code points. The lower (least significant)

 * 21 bits of <code>int</code> are used to represent Unicode code

 * points and the upper (most significant) 11 bits must be zero.

 * Unless otherwise specified, the behavior with respect to

 * supplementary characters and surrogate <code>char</code> values is

 * as follows:

 *

 * <ul>

 * <li>The methods that only accept a <code>char</code> value cannot support

 * supplementary characters. They treat <code>char</code> values from the

 * surrogate ranges as undefined characters. For example,

 * <code>Character.isLetter('&#92;uD840')</code> returns <code>false</code>, even though

 * this specific value if followed by any low-surrogate value in a string

 * would represent a letter.

 *

 * <li>The methods that accept an <code>int</code> value support all

 * Unicode characters, including supplementary characters. For

 * example, <code>Character.isLetter(0x2F81A)</code> returns

 * <code>true</code> because the code point value represents a letter

 * (a CJK ideograph).

 * </ul>

 *

 * <p>In the Java SE API documentation, <em>Unicode code point</em> is

 * used for character values in the range between U+0000 and U+10FFFF,

 * and <em>Unicode code unit</em> is used for 16-bit

 * <code>char</code> values that are code units of the <em>UTF-16</em>

 * encoding. For more information on Unicode terminology, refer to the

 * <a href="http://www.unicode.org/glossary/">Unicode Glossary</a>.

 *

 * @author  Lee Boynton

 * @author  Guy Steele

 * @author  Akira Tanaka

 * @author  Martin Buchholz

 * @author  Ulf Zibis

 * @since   1.0

 */

public final

class Character implements java.io.Serializable, Comparable<Character> {

    /**

     * The minimum radix available for conversion to and from strings.

     * The constant value of this field is the smallest value permitted

     * for the radix argument in radix-conversion methods such as the

     * <code>digit</code> method, the <code>forDigit</code>

     * method, and the <code>toString</code> method of class

     * <code>Integer</code>.

     *

     * @see     Character#digit(char, int)

     * @see     Character#forDigit(int, int)

     * @see     Integer#toString(int, int)

     * @see     Integer#valueOf(String)

     */

    public static final int MIN_RADIX = 2;

    /**

     * The maximum radix available for conversion to and from strings.

     * The constant value of this field is the largest value permitted

     * for the radix argument in radix-conversion methods such as the

     * <code>digit</code> method, the <code>forDigit</code>

     * method, and the <code>toString</code> method of class

     * <code>Integer</code>.

     *

     * @see     Character#digit(char, int)

     * @see     Character#forDigit(int, int)

     * @see     Integer#toString(int, int)

     * @see     Integer#valueOf(String)

     */

    public static final int MAX_RADIX = 36;

    /**

     * The constant value of this field is the smallest value of type

     * <code>char</code>, <code>'&#92;u0000'</code>.

     *

     * @since   1.0.2

     */

    public static final char MIN_VALUE = '\u0000';

    /**

     * The constant value of this field is the largest value of type

     * <code>char</code>, <code>'&#92;uFFFF'</code>.

     *

     * @since   1.0.2

     */

    public static final char MAX_VALUE = '\uFFFF';

    /**

     * The <code>Class</code> instance representing the primitive type

     * <code>char</code>.

     *

     * @since   1.1

     */

    @SuppressWarnings("unchecked")

    public static final Class<Character> TYPE = Class.getPrimitiveClass("char");

    /*

     * Normative general types

     */

    /*

     * General character types

     */

    /**

     * General category "Cn" in the Unicode specification.

     * @since   1.1

     */

    public static final byte UNASSIGNED = 0;

    /**

     * General category "Lu" in the Unicode specification.

     * @since   1.1

     */

    public static final byte UPPERCASE_LETTER = 1;

    /**

     * General category "Ll" in the Unicode specification.

     * @since   1.1

     */

    public static final byte LOWERCASE_LETTER = 2;

    /**

     * General category "Lt" in the Unicode specification.

     * @since   1.1

     */

    public static final byte TITLECASE_LETTER = 3;

    /**

     * General category "Lm" in the Unicode specification.

     * @since   1.1

     */

    public static final byte MODIFIER_LETTER = 4;

    /**

     * General category "Lo" in the Unicode specification.

     * @since   1.1

     */

    public static final byte OTHER_LETTER = 5;

    /**

     * General category "Mn" in the Unicode specification.

     * @since   1.1

     */

    public static final byte NON_SPACING_MARK = 6;

    /**

     * General category "Me" in the Unicode specification.

     * @since   1.1

     */

    public static final byte ENCLOSING_MARK = 7;

    /**

     * General category "Mc" in the Unicode specification.

     * @since   1.1

     */

    public static final byte COMBINING_SPACING_MARK = 8;

    /**

     * General category "Nd" in the Unicode specification.

     * @since   1.1

     */

    public static final byte DECIMAL_DIGIT_NUMBER        = 9;

    /**

     * General category "Nl" in the Unicode specification.

     * @since   1.1

     */

    public static final byte LETTER_NUMBER = 10;

    /**

     * General category "No" in the Unicode specification.

     * @since   1.1

     */

    public static final byte OTHER_NUMBER = 11;

    /**

     * General category "Zs" in the Unicode specification.

     * @since   1.1

     */

    public static final byte SPACE_SEPARATOR = 12;

    /**

     * General category "Zl" in the Unicode specification.

     * @since   1.1

     */

    public static final byte LINE_SEPARATOR = 13;

    /**

     * General category "Zp" in the Unicode specification.

     * @since   1.1

     */

    public static final byte PARAGRAPH_SEPARATOR = 14;

    /**

     * General category "Cc" in the Unicode specification.

     * @since   1.1

     */

    public static final byte CONTROL = 15;

    /**

     * General category "Cf" in the Unicode specification.

     * @since   1.1

     */

    public static final byte FORMAT = 16;

    /**

     * General category "Co" in the Unicode specification.

     * @since   1.1

     */

    public static final byte PRIVATE_USE = 18;

    /**

     * General category "Cs" in the Unicode specification.

     * @since   1.1

     */

    public static final byte SURROGATE = 19;

    /**

     * General category "Pd" in the Unicode specification.

     * @since   1.1

     */

    public static final byte DASH_PUNCTUATION = 20;

    /**

     * General category "Ps" in the Unicode specification.

     * @since   1.1

     */

    public static final byte START_PUNCTUATION = 21;

    /**

     * General category "Pe" in the Unicode specification.

     * @since   1.1

     */

    public static final byte END_PUNCTUATION = 22;

    /**

     * General category "Pc" in the Unicode specification.

     * @since   1.1

     */

    public static final byte CONNECTOR_PUNCTUATION = 23;

    /**

     * General category "Po" in the Unicode specification.

     * @since   1.1

     */

    public static final byte OTHER_PUNCTUATION = 24;

    /**

     * General category "Sm" in the Unicode specification.

     * @since   1.1

     */

    public static final byte MATH_SYMBOL = 25;

    /**

     * General category "Sc" in the Unicode specification.

     * @since   1.1

     */

    public static final byte CURRENCY_SYMBOL = 26;

    /**

     * General category "Sk" in the Unicode specification.

     * @since   1.1

     */

    public static final byte MODIFIER_SYMBOL = 27;

    /**

     * General category "So" in the Unicode specification.

     * @since   1.1

     */

    public static final byte OTHER_SYMBOL = 28;

    /**

     * General category "Pi" in the Unicode specification.

     * @since   1.4

     */

    public static final byte INITIAL_QUOTE_PUNCTUATION = 29;

    /**

     * General category "Pf" in the Unicode specification.

     * @since   1.4

     */

    public static final byte FINAL_QUOTE_PUNCTUATION = 30;

    /**

     * Error flag. Use int (code point) to avoid confusion with U+FFFF.

     */

    static final int ERROR = 0xFFFFFFFF;

    /**

     * Undefined bidirectional character type. Undefined <code>char</code>

     * values have undefined directionality in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_UNDEFINED = -1;

    /**

     * Strong bidirectional character type "L" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_LEFT_TO_RIGHT = 0;

    /**

     * Strong bidirectional character type "R" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_RIGHT_TO_LEFT = 1;

    /**

    * Strong bidirectional character type "AL" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_RIGHT_TO_LEFT_ARABIC = 2;

    /**

     * Weak bidirectional character type "EN" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_EUROPEAN_NUMBER = 3;

    /**

     * Weak bidirectional character type "ES" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_EUROPEAN_NUMBER_SEPARATOR = 4;

    /**

     * Weak bidirectional character type "ET" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_EUROPEAN_NUMBER_TERMINATOR = 5;

    /**

     * Weak bidirectional character type "AN" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_ARABIC_NUMBER = 6;

    /**

     * Weak bidirectional character type "CS" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_COMMON_NUMBER_SEPARATOR = 7;

    /**

     * Weak bidirectional character type "NSM" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_NONSPACING_MARK = 8;

    /**

     * Weak bidirectional character type "BN" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_BOUNDARY_NEUTRAL = 9;

    /**

     * Neutral bidirectional character type "B" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_PARAGRAPH_SEPARATOR = 10;

    /**

     * Neutral bidirectional character type "S" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_SEGMENT_SEPARATOR = 11;

    /**

     * Neutral bidirectional character type "WS" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_WHITESPACE = 12;

    /**

     * Neutral bidirectional character type "ON" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_OTHER_NEUTRALS = 13;

    /**

     * Strong bidirectional character type "LRE" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_LEFT_TO_RIGHT_EMBEDDING = 14;

    /**

     * Strong bidirectional character type "LRO" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_LEFT_TO_RIGHT_OVERRIDE = 15;

    /**

     * Strong bidirectional character type "RLE" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_RIGHT_TO_LEFT_EMBEDDING = 16;

    /**

     * Strong bidirectional character type "RLO" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_RIGHT_TO_LEFT_OVERRIDE = 17;

    /**

     * Weak bidirectional character type "PDF" in the Unicode specification.

     * @since 1.4

     */

    public static final byte DIRECTIONALITY_POP_DIRECTIONAL_FORMAT = 18;

    /**

     * The minimum value of a

     * <a href="http://www.unicode.org/glossary/#high_surrogate_code_unit">

     * Unicode high-surrogate code unit</a>

     * in the UTF-16 encoding, constant <code>'&#92;uD800'</code>.

     * A high-surrogate is also known as a <i>leading-surrogate</i>.

     *

     * @since 1.5

     */

    public static final char MIN_HIGH_SURROGATE = '\uD800';

    /**

     * The maximum value of a

     * <a href="http://www.unicode.org/glossary/#high_surrogate_code_unit">

     * Unicode high-surrogate code unit</a>

     * in the UTF-16 encoding, constant <code>'&#92;uDBFF'</code>.

     * A high-surrogate is also known as a <i>leading-surrogate</i>.