/*

 * Copyright (c) 2002, 2010, 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;

/**

 * The {@code Character} class wraps a value of the primitive

 * type {@code char} in an object. An object of type

 * {@code Character} contains a single field whose type is

 * {@code char}.

 * <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 6.0.0.

 * <p>

 * The methods and data of class {@code Character} 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} data type (and therefore the value that a

 * {@code Character} 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} arrays and

 * in the {@code String} and {@code StringBuffer} classes. In

 * this representation, supplementary characters are represented as a pair

 * of {@code char} 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} 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} value represents all Unicode code points,

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

 * 21 bits of {@code int} 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} values is

 * as follows:

 *

 * <ul>

 * <li>The methods that only accept a {@code char} value cannot support

 * supplementary characters. They treat {@code char} values from the

 * surrogate ranges as undefined characters. For example,

 * {@code Character.isLetter('\u005CuD840')} returns {@code false}, 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} value support all

 * Unicode characters, including supplementary characters. For

 * example, {@code Character.isLetter(0x2F81A)} returns

 * {@code true} 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} 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} method, the {@code forDigit} method, and the

     * {@code toString} method of class {@code Integer}.

     *

     * @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} method, the {@code forDigit} method, and the

     * {@code toString} method of class {@code Integer}.

     *

     * @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 '\u005Cu0000'}.

     *

     * @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 '\u005CuFFFF'}.

     *

     * @since   1.0.2

     */

    public static final char MAX_VALUE = '\uFFFF';

    /**

     * The {@code Class} instance representing the primitive type

     * {@code char}.

     *

     * @since   1.1

     */

    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}

     * 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 '\u005CuD800'}.

     * 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 '\u005CuDBFF'}.

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

     *

     * @since 1.5

     */

    public static final char MAX_HIGH_SURROGATE = '\uDBFF';

    /**

     * The minimum value of a

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

     * Unicode low-surrogate code unit</a>

     * in the UTF-16 encoding, constant {@code '\u005CuDC00'}.

     * A low-surrogate is also known as a <i>trailing-surrogate</i>.

     *

     * @since 1.5

     */

    public static final char MIN_LOW_SURROGATE  = '\uDC00';

    /**

     * The maximum value of a

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

     * Unicode low-surrogate code unit</a>

     * in the UTF-16 encoding, constant {@code '\u005CuDFFF'}.

     * A low-surrogate is also known as a <i>trailing-surrogate</i>.

     *

     * @since 1.5

     */

    public static final char MAX_LOW_SURROGATE  = '\uDFFF';

    /**

     * The minimum value of a Unicode surrogate code unit in the

     * UTF-16 encoding, constant {@code '\u005CuD800'}.

     *

     * @since 1.5

     */

    public static final char MIN_SURROGATE = MIN_HIGH_SURROGATE;

    /**

     * The maximum value of a Unicode surrogate code unit in the

     * UTF-16 encoding, constant {@code '\u005CuDFFF'}.

     *

     * @since 1.5

     */

    public static final char MAX_SURROGATE = MAX_LOW_SURROGATE;

    /**

     * The minimum value of a

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

     * Unicode supplementary code point</a>, constant {@code U+10000}.

     *

     * @since 1.5

     */

    public static final int MIN_SUPPLEMENTARY_CODE_POINT = 0x010000;

    /**

     * The minimum value of a

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

     * Unicode code point</a>, constant {@code U+0000}.

     *

     * @since 1.5

     */

    public static final int MIN_CODE_POINT = 0x000000;

    /**

     * The maximum value of a

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

     * Unicode code point</a>, constant {@code U+10FFFF}.

     *

     * @since 1.5

     */

    public static final int MAX_CODE_POINT = 0X10FFFF;

    /**

     * Instances of this class represent particular subsets of the Unicode

     * character set.  The only family of subsets defined in the

     * {@code Character} class is {@link Character.UnicodeBlock}.

     * Other portions of the Java API may define other subsets for their

     * own purposes.

     *

     * @since 1.2

     */

    public static class Subset  {

        private String name;

        /**

         * Constructs a new {@code Subset} instance.

         *

         * @param  name  The name of this subset

         * @exception NullPointerException if name is {@code null}

         */

        protected Subset(String name) {

            if (name == null) {

                throw new NullPointerException("name");

            }

            this.name = name;

        }

        /**

         * Compares two {@code Subset} objects for equality.

         * This method returns {@code true} if and only if

         * {@code this} and the argument refer to the same

         * object; since this method is {@code final}, this

         * guarantee holds for all subclasses.

         */

        public final boolean equals(Object obj) {

            return (this == obj);

        }

        /**

         * Returns the standard hash code as defined by the

         * {@link Object#hashCode} method.  This method

         * is {@code final} in order to ensure that the

         * {@code equals} and {@code hashCode} methods will

         * be consistent in all subclasses.

         */

        public final int hashCode() {

            return super.hashCode();

        }

        /**

         * Returns the name of this subset.

         */

        public final String toString() {

            return name;

        }

    }

    // See http://www.unicode.org/Public/UNIDATA/Blocks.txt

    // for the latest specification of Unicode Blocks.

    /**

     * The value of the {@code Character}.

     *

     * @serial

     */

    private final char value;

    /** use serialVersionUID from JDK 1.0.2 for interoperability */

    private static final long serialVersionUID = 3786198910865385080L;

    /**

     * Constructs a newly allocated {@code Character} object that

     * represents the specified {@code char} value.

     *

     * @param  value   the value to be represented by the

     *                  {@code Character} object.

     */

    public Character(char value) {

        this.value = value;

    }

    private static class CharacterCache {

        private CharacterCache(){}

        static final Character cache[] = new Character[127 + 1];

        static {

            for (int i = 0; i < cache.length; i++)

                cache[i] = new Character((char)i);

        }

    }

    /**

     * Returns a <tt>Character</tt> instance representing the specified

     * <tt>char</tt> value.

     * If a new <tt>Character</tt> instance is not required, this method

     * should generally be used in preference to the constructor

     * {@link #Character(char)}, as this method is likely to yield

     * significantly better space and time performance by caching

     * frequently requested values.

     *

     * This method will always cache values in the range {@code

     * '\u005Cu0000'} to {@code '\u005Cu007F'}, inclusive, and may

     * cache other values outside of this range.

     *

     * @param  c a char value.

     * @return a <tt>Character</tt> instance representing <tt>c</tt>.

     * @since  1.5

     */

    public static Character valueOf(char c) {

        if (c <= 127) { // must cache

            return CharacterCache.cache[(int)c];

        }

        return new Character(c);

    }

    /**

     * Returns the value of this {@code Character} object.

     * @return  the primitive {@code char} value represented by

     *          this object.

     */

    public char charValue() {

        return value;

    }

    /**

     * Returns a hash code for this {@code Character}; equal to the result

     * of invoking {@code charValue()}.

     *

     * @return a hash code value for this {@code Character}

     */

    public int hashCode() {

        return (int)value;

    }

    /**

     * Compares this object against the specified object.

     * The result is {@code true} if and only if the argument is not

     * {@code null} and is a {@code Character} object that

     * represents the same {@code char} value as this object.

     *

     * @param   obj   the object to compare with.

     * @return  {@code true} if the objects are the same;

     *          {@code false} otherwise.

     */

    public boolean equals(Object obj) {

        if (obj instanceof Character) {

            return value == ((Character)obj).charValue();

        }

        return false;

    }

    /**

     * Returns a {@code String} object representing this

     * {@code Character}'s value.  The result is a string of

     * length 1 whose sole component is the primitive

     * {@code char} value represented by this

     * {@code Character} object.

     *

     * @return  a string representation of this object.

     */

    public String toString() {

        char buf[] = {value};

        return String.valueOf(buf);

    }

    /**

     * Returns a {@code String} object representing the

     * specified {@code char}.  The result is a string of length

     * 1 consisting solely of the specified {@code char}.

     *

     * @param c the {@code char} to be converted

     * @return the string representation of the specified {@code char}

     * @since 1.4

     */

    public static String toString(char c) {

        return String.valueOf(c);

    }

    /**

     * Determines whether the specified code point is a valid

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

     * Unicode code point value</a>.

     *

     * @param  codePoint the Unicode code point to be tested

     * @return {@code true} if the specified code point value is between

     *         {@link #MIN_CODE_POINT} and

     *         {@link #MAX_CODE_POINT} inclusive;

     *         {@code false} otherwise.

     * @since  1.5

     */

    public static boolean isValidCodePoint(int codePoint) {

        // Optimized form of:

        //     codePoint >= MIN_CODE_POINT && codePoint <= MAX_CODE_POINT

        int plane = codePoint >>> 16;

        return plane < ((MAX_CODE_POINT + 1) >>> 16);

    }

    /**

     * Determines whether the specified character (Unicode code point)

     * is in the <a href="#BMP">Basic Multilingual Plane (BMP)</a>.

     * Such code points can be represented using a single {@code char}.

     *

     * @param  codePoint the character (Unicode code point) to be tested

     * @return {@code true} if the specified code point is between

     *         {@link #MIN_VALUE} and {@link #MAX_VALUE} inclusive;

     *         {@code false} otherwise.

     * @since  1.7

     */

    public static boolean isBmpCodePoint(int codePoint) {

        return codePoint >>> 16 == 0;

        // Optimized form of:

        //     codePoint >= MIN_VALUE && codePoint <= MAX_VALUE

        // We consistently use logical shift (>>>) to facilitate

        // additional runtime optimizations.

    }

    /**

     * Determines whether the specified character (Unicode code point)

     * is in the <a href="#supplementary">supplementary character</a> range.

     *

     * @param  codePoint the character (Unicode code point) to be tested

     * @return {@code true} if the specified code point is between

     *         {@link #MIN_SUPPLEMENTARY_CODE_POINT} and

     *         {@link #MAX_CODE_POINT} inclusive;

     *         {@code false} otherwise.

     * @since  1.5

     */

    public static boolean isSupplementaryCodePoint(int codePoint) {

        return codePoint >= MIN_SUPPLEMENTARY_CODE_POINT

            && codePoint <  MAX_CODE_POINT + 1;

    }

    /**

     * Determines if the given {@code char} value is a

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

     * Unicode high-surrogate code unit</a>

     * (also known as <i>leading-surrogate code unit</i>).

     *

     * <p>Such values do not represent characters by themselves,

     * but are used in the representation of

     * <a href="#supplementary">supplementary characters</a>

     * in the UTF-16 encoding.

     *

     * @param  ch the {@code char} value to be tested.

     * @return {@code true} if the {@code char} value is between

     *         {@link #MIN_HIGH_SURROGATE} and

     *         {@link #MAX_HIGH_SURROGATE} inclusive;

     *         {@code false} otherwise.

     * @see    Character#isLowSurrogate(char)

     * @see    Character.UnicodeBlock#of(int)

     * @since  1.5

     */

    public static boolean isHighSurrogate(char ch) {

        // Help VM constant-fold; MAX_HIGH_SURROGATE + 1 == MIN_LOW_SURROGATE

        return ch >= MIN_HIGH_SURROGATE && ch < (MAX_HIGH_SURROGATE + 1);

    }

    /**

     * Determines if the given {@code char} value is a

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

     * Unicode low-surrogate code unit</a>

     * (also known as <i>trailing-surrogate code unit</i>).

     *

     * <p>Such values do not represent characters by themselves,

     * but are used in the representation of

     * <a href="#supplementary">supplementary characters</a>

     * in the UTF-16 encoding.

     *

     * @param  ch the {@code char} value to be tested.

     * @return {@code true} if the {@code char} value is between

     *         {@link #MIN_LOW_SURROGATE} and

     *         {@link #MAX_LOW_SURROGATE} inclusive;

     *         {@code false} otherwise.

     * @see    Character#isHighSurrogate(char)

     * @since  1.5

     */

    public static boolean isLowSurrogate(char ch) {

        return ch >= MIN_LOW_SURROGATE && ch < (MAX_LOW_SURROGATE + 1);

    }

    /**

     * Determines if the given {@code char} value is a Unicode

     * <i>surrogate code unit</i>.

     *

     * <p>Such values do not represent characters by themselves,

     * but are used in the representation of

     * <a href="#supplementary">supplementary characters</a>

     * in the UTF-16 encoding.

     *

     * <p>A char value is a surrogate code unit if and only if it is either

     * a {@linkplain #isLowSurrogate(char) low-surrogate code unit} or

     * a {@linkplain #isHighSurrogate(char) high-surrogate code unit}.

     *

     * @param  ch the {@code char} value to be tested.

     * @return {@code true} if the {@code char} value is between

     *         {@link #MIN_SURROGATE} and

     *         {@link #MAX_SURROGATE} inclusive;

     *         {@code false} otherwise.

     * @since  1.7

     */

    public static boolean isSurrogate(char ch) {

        return ch >= MIN_SURROGATE && ch < (MAX_SURROGATE + 1);

    }

    /**

     * Determines whether the specified pair of {@code char}

     * values is a valid

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

     * Unicode surrogate pair</a>.

     * <p>This method is equivalent to the expression:

     * <blockquote><pre>

     * isHighSurrogate(high) && isLowSurrogate(low)

     * </pre></blockquote>

     *

     * @param  high the high-surrogate code value to be tested

     * @param  low the low-surrogate code value to be tested

     * @return {@code true} if the specified high and

     * low-surrogate code values represent a valid surrogate pair;

     * {@code false} otherwise.

     * @since  1.5

     */

    public static boolean isSurrogatePair(char high, char low) {

        return isHighSurrogate(high) && isLowSurrogate(low);

    }

    /**

     * Determines the number of {@code char} values needed to

     * represent the specified character (Unicode code point). If the

     * specified character is equal to or greater than 0x10000, then

     * the method returns 2. Otherwise, the method returns 1.

     *

     * <p>This method doesn't validate the specified character to be a

     * valid Unicode code point. The caller must validate the

     * character value using {@link #isValidCodePoint(int) isValidCodePoint}

     * if necessary.

     *

     * @param   codePoint the character (Unicode code point) to be tested.

     * @return  2 if the character is a valid supplementary character; 1 otherwise.

     * @see     Character#isSupplementaryCodePoint(int)

     * @since   1.5

     */

    public static int charCount(int codePoint) {

        return codePoint >= MIN_SUPPLEMENTARY_CODE_POINT ? 2 : 1;

    }

    /**

     * Converts the specified surrogate pair to its supplementary code

     * point value. This method does not validate the specified

     * surrogate pair. The caller must validate it using {@link

     * #isSurrogatePair(char, char) isSurrogatePair} if necessary.

     *

     * @param  high the high-surrogate code unit

     * @param  low the low-surrogate code unit

     * @return the supplementary code point composed from the

     *         specified surrogate pair.

     * @since  1.5

     */

    public static int toCodePoint(char high, char low) {

        // Optimized form of:

        // return ((high - MIN_HIGH_SURROGATE) << 10)

        //         + (low - MIN_LOW_SURROGATE)

        //         + MIN_SUPPLEMENTARY_CODE_POINT;

        return ((high << 10) + low) + (MIN_SUPPLEMENTARY_CODE_POINT

                                       - (MIN_HIGH_SURROGATE << 10)

                                       - MIN_LOW_SURROGATE);

    }

    /**

     * Returns the code point at the given index of the

     * {@code CharSequence}. If the {@code char} value at

     * the given index in the {@code CharSequence} is in the

     * high-surrogate range, the following index is less than the

     * length of the {@code CharSequence}, and the

     * {@code char} value at the following index is in the

     * low-surrogate range, then the supplementary code point

     * corresponding to this surrogate pair is returned. Otherwise,

     * the {@code char} value at the given index is returned.

     *

     * @param seq a sequence of {@code char} values (Unicode code

     * units)

     * @param index the index to the {@code char} values (Unicode

     * code units) in {@code seq} to be converted

     * @return the Unicode code point at the given index

     * @exception NullPointerException if {@code seq} is null.

     * @exception IndexOutOfBoundsException if the value

     * {@code index} is negative or not less than

     * {@link CharSequence#length() seq.length()}.

     * @since  1.5

     */

    public static int codePointAt(CharSequence seq, int index) {

        char c1 = seq.charAt(index++);

        if (isHighSurrogate(c1)) {

            if (index < seq.length()) {

                char c2 = seq.charAt(index);

                if (isLowSurrogate(c2)) {

                    return toCodePoint(c1, c2);

                }

            }

        }

        return c1;

    }

    /**

     * Returns the code point at the given index of the

     * {@code char} array. If the {@code char} value at

     * the given index in the {@code char} array is in the

     * high-surrogate range, the following index is less than the

     * length of the {@code char} array, and the

     * {@code char} value at the following index is in the

     * low-surrogate range, then the supplementary code point

     * corresponding to this surrogate pair is returned. Otherwise,

     * the {@code char} value at the given index is returned.

     *

     * @param a the {@code char} array

     * @param index the index to the {@code char} values (Unicode

     * code units) in the {@code char} array to be converted

     * @return the Unicode code point at the given index

     * @exception NullPointerException if {@code a} is null.