    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3;
    018
    019/**
    020 * <p>Operations on char primitives and Character objects.</p>
    021 *
    022 * <p>This class tries to handle {@code null} input gracefully.
    023 * An exception will not be thrown for a {@code null} input.
    024 * Each method documents its behaviour in more detail.</p>
    025 *
    026 * <p>#ThreadSafe#</p>
    027 * @since 2.1
    028 */
    029public class CharUtils {
    030
    031    private static final String[] CHAR_STRING_ARRAY = new String[128];
    032
    033    private static final char[] HEX_DIGITS = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
    034
    035    /**
    036     * {@code \u000a} linefeed LF ('\n').
    037     *
    038     * @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10.6">JLF: Escape Sequences
    039     *      for Character and String Literals</a>
    040     * @since 2.2
    041     */
    042    public static final char LF = '\n';
    043
    044    /**
    045     * {@code \u000d} carriage return CR ('\r').
    046     *
    047     * @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10.6">JLF: Escape Sequences
    048     *      for Character and String Literals</a>
    049     * @since 2.2
    050     */
    051    public static final char CR = '\r';
    052
    053    /**
    054     * {@code \u0000} null control character ('\0'), abbreviated NUL.
    055     *
    056     * @since 3.6
    057     */
    058    public static final char NUL = '\0';
    059
    060    static {
    061        for (char c = 0; c < CHAR_STRING_ARRAY.length; c++) {
    062            CHAR_STRING_ARRAY[c] = String.valueOf(c);
    063        }
    064    }
    065
    066    /**
    067     * <p>{@code CharUtils} instances should NOT be constructed in standard programming.
    068     * Instead, the class should be used as {@code CharUtils.toString('c');}.</p>
    069     *
    070     * <p>This constructor is public to permit tools that require a JavaBean instance
    071     * to operate.</p>
    072     */
    073    public CharUtils() {
    074      super();
    075    }
    076
    077    //-----------------------------------------------------------------------
    078    /**
    079     * <p>Converts the character to a Character.</p>
    080     *
    081     * <p>For ASCII 7 bit characters, this uses a cache that will return the
    082     * same Character object each time.</p>
    083     *
    084     * <pre>
    085     *   CharUtils.toCharacterObject(' ')  = ' '
    086     *   CharUtils.toCharacterObject('A')  = 'A'
    087     * </pre>
    088     *
    089     * @deprecated Java 5 introduced {@link Character#valueOf(char)} which caches chars 0 through 127.
    090     * @param ch  the character to convert
    091     * @return a Character of the specified character
    092     */
    093    @Deprecated
    094    public static Character toCharacterObject(final char ch) {
    095        return Character.valueOf(ch);
    096    }
    097
    098    /**
    099     * <p>Converts the String to a Character using the first character, returning
    100     * null for empty Strings.</p>
    101     *
    102     * <p>For ASCII 7 bit characters, this uses a cache that will return the
    103     * same Character object each time.</p>
    104     *
    105     * <pre>
    106     *   CharUtils.toCharacterObject(null) = null
    107     *   CharUtils.toCharacterObject("")   = null
    108     *   CharUtils.toCharacterObject("A")  = 'A'
    109     *   CharUtils.toCharacterObject("BA") = 'B'
    110     * </pre>
    111     *
    112     * @param str  the character to convert
    113     * @return the Character value of the first letter of the String
    114     */
    115    public static Character toCharacterObject(final String str) {
    116        if (StringUtils.isEmpty(str)) {
    117            return null;
    118        }
    119        return Character.valueOf(str.charAt(0));
    120    }
    121
    122    //-----------------------------------------------------------------------
    123    /**
    124     * <p>Converts the Character to a char throwing an exception for {@code null}.</p>
    125     *
    126     * <pre>
    127     *   CharUtils.toChar(' ')  = ' '
    128     *   CharUtils.toChar('A')  = 'A'
    129     *   CharUtils.toChar(null) throws IllegalArgumentException
    130     * </pre>
    131     *
    132     * @param ch  the character to convert
    133     * @return the char value of the Character
    134     * @throws IllegalArgumentException if the Character is null
    135     */
    136    public static char toChar(final Character ch) {
    137        Validate.isTrue(ch != null, "The Character must not be null");
    138        return ch.charValue();
    139    }
    140
    141    /**
    142     * <p>Converts the Character to a char handling {@code null}.</p>
    143     *
    144     * <pre>
    145     *   CharUtils.toChar(null, 'X') = 'X'
    146     *   CharUtils.toChar(' ', 'X')  = ' '
    147     *   CharUtils.toChar('A', 'X')  = 'A'
    148     * </pre>
    149     *
    150     * @param ch  the character to convert
    151     * @param defaultValue  the value to use if the  Character is null
    152     * @return the char value of the Character or the default if null
    153     */
    154    public static char toChar(final Character ch, final char defaultValue) {
    155        if (ch == null) {
    156            return defaultValue;
    157        }
    158        return ch.charValue();
    159    }
    160
    161    //-----------------------------------------------------------------------
    162    /**
    163     * <p>Converts the String to a char using the first character, throwing
    164     * an exception on empty Strings.</p>
    165     *
    166     * <pre>
    167     *   CharUtils.toChar("A")  = 'A'
    168     *   CharUtils.toChar("BA") = 'B'
    169     *   CharUtils.toChar(null) throws IllegalArgumentException
    170     *   CharUtils.toChar("")   throws IllegalArgumentException
    171     * </pre>
    172     *
    173     * @param str  the character to convert
    174     * @return the char value of the first letter of the String
    175     * @throws IllegalArgumentException if the String is empty
    176     */
    177    public static char toChar(final String str) {
    178        Validate.isTrue(StringUtils.isNotEmpty(str), "The String must not be empty");
    179        return str.charAt(0);
    180    }
    181
    182    /**
    183     * <p>Converts the String to a char using the first character, defaulting
    184     * the value on empty Strings.</p>
    185     *
    186     * <pre>
    187     *   CharUtils.toChar(null, 'X') = 'X'
    188     *   CharUtils.toChar("", 'X')   = 'X'
    189     *   CharUtils.toChar("A", 'X')  = 'A'
    190     *   CharUtils.toChar("BA", 'X') = 'B'
    191     * </pre>
    192     *
    193     * @param str  the character to convert
    194     * @param defaultValue  the value to use if the  Character is null
    195     * @return the char value of the first letter of the String or the default if null
    196     */
    197    public static char toChar(final String str, final char defaultValue) {
    198        if (StringUtils.isEmpty(str)) {
    199            return defaultValue;
    200        }
    201        return str.charAt(0);
    202    }
    203
    204    //-----------------------------------------------------------------------
    205    /**
    206     * <p>Converts the character to the Integer it represents, throwing an
    207     * exception if the character is not numeric.</p>
    208     *
    209     * <p>This method converts the char '1' to the int 1 and so on.</p>
    210     *
    211     * <pre>
    212     *   CharUtils.toIntValue('3')  = 3
    213     *   CharUtils.toIntValue('A')  throws IllegalArgumentException
    214     * </pre>
    215     *
    216     * @param ch  the character to convert
    217     * @return the int value of the character
    218     * @throws IllegalArgumentException if the character is not ASCII numeric
    219     */
    220    public static int toIntValue(final char ch) {
    221        if (!isAsciiNumeric(ch)) {
    222            throw new IllegalArgumentException("The character " + ch + " is not in the range '0' - '9'");
    223        }
    224        return ch - 48;
    225    }
    226
    227    /**
    228     * <p>Converts the character to the Integer it represents, throwing an
    229     * exception if the character is not numeric.</p>
    230     *
    231     * <p>This method converts the char '1' to the int 1 and so on.</p>
    232     *
    233     * <pre>
    234     *   CharUtils.toIntValue('3', -1)  = 3
    235     *   CharUtils.toIntValue('A', -1)  = -1
    236     * </pre>
    237     *
    238     * @param ch  the character to convert
    239     * @param defaultValue  the default value to use if the character is not numeric
    240     * @return the int value of the character
    241     */
    242    public static int toIntValue(final char ch, final int defaultValue) {
    243        if (!isAsciiNumeric(ch)) {
    244            return defaultValue;
    245        }
    246        return ch - 48;
    247    }
    248
    249    /**
    250     * <p>Converts the character to the Integer it represents, throwing an
    251     * exception if the character is not numeric.</p>
    252     *
    253     * <p>This method converts the char '1' to the int 1 and so on.</p>
    254     *
    255     * <pre>
    256     *   CharUtils.toIntValue('3')  = 3
    257     *   CharUtils.toIntValue(null) throws IllegalArgumentException
    258     *   CharUtils.toIntValue('A')  throws IllegalArgumentException
    259     * </pre>
    260     *
    261     * @param ch  the character to convert, not null
    262     * @return the int value of the character
    263     * @throws IllegalArgumentException if the Character is not ASCII numeric or is null
    264     */
    265    public static int toIntValue(final Character ch) {
    266        Validate.isTrue(ch != null, "The character must not be null");
    267        return toIntValue(ch.charValue());
    268    }
    269
    270    /**
    271     * <p>Converts the character to the Integer it represents, throwing an
    272     * exception if the character is not numeric.</p>
    273     *
    274     * <p>This method converts the char '1' to the int 1 and so on.</p>
    275     *
    276     * <pre>
    277     *   CharUtils.toIntValue(null, -1) = -1
    278     *   CharUtils.toIntValue('3', -1)  = 3
    279     *   CharUtils.toIntValue('A', -1)  = -1
    280     * </pre>
    281     *
    282     * @param ch  the character to convert
    283     * @param defaultValue  the default value to use if the character is not numeric
    284     * @return the int value of the character
    285     */
    286    public static int toIntValue(final Character ch, final int defaultValue) {
    287        if (ch == null) {
    288            return defaultValue;
    289        }
    290        return toIntValue(ch.charValue(), defaultValue);
    291    }
    292
    293    //-----------------------------------------------------------------------
    294    /**
    295     * <p>Converts the character to a String that contains the one character.</p>
    296     *
    297     * <p>For ASCII 7 bit characters, this uses a cache that will return the
    298     * same String object each time.</p>
    299     *
    300     * <pre>
    301     *   CharUtils.toString(' ')  = " "
    302     *   CharUtils.toString('A')  = "A"
    303     * </pre>
    304     *
    305     * @param ch  the character to convert
    306     * @return a String containing the one specified character
    307     */
    308    public static String toString(final char ch) {
    309        if (ch < 128) {
    310            return CHAR_STRING_ARRAY[ch];
    311        }
    312        return new String(new char[] {ch});
    313    }
    314
    315    /**
    316     * <p>Converts the character to a String that contains the one character.</p>
    317     *
    318     * <p>For ASCII 7 bit characters, this uses a cache that will return the
    319     * same String object each time.</p>
    320     *
    321     * <p>If {@code null} is passed in, {@code null} will be returned.</p>
    322     *
    323     * <pre>
    324     *   CharUtils.toString(null) = null
    325     *   CharUtils.toString(' ')  = " "
    326     *   CharUtils.toString('A')  = "A"
    327     * </pre>
    328     *
    329     * @param ch  the character to convert
    330     * @return a String containing the one specified character
    331     */
    332    public static String toString(final Character ch) {
    333        if (ch == null) {
    334            return null;
    335        }
    336        return toString(ch.charValue());
    337    }
    338
    339    //--------------------------------------------------------------------------
    340    /**
    341     * <p>Converts the string to the Unicode format '\u0020'.</p>
    342     *
    343     * <p>This format is the Java source code format.</p>
    344     *
    345     * <pre>
    346     *   CharUtils.unicodeEscaped(' ') = "\u0020"
    347     *   CharUtils.unicodeEscaped('A') = "\u0041"
    348     * </pre>
    349     *
    350     * @param ch  the character to convert
    351     * @return the escaped Unicode string
    352     */
    353    public static String unicodeEscaped(final char ch) {
    354        return "\\u" +
    355            HEX_DIGITS[(ch >> 12) & 15] +
    356            HEX_DIGITS[(ch >> 8) & 15] +
    357            HEX_DIGITS[(ch >> 4) & 15] +
    358            HEX_DIGITS[(ch) & 15];
    359    }
    360
    361    /**
    362     * <p>Converts the string to the Unicode format '\u0020'.</p>
    363     *
    364     * <p>This format is the Java source code format.</p>
    365     *
    366     * <p>If {@code null} is passed in, {@code null} will be returned.</p>
    367     *
    368     * <pre>
    369     *   CharUtils.unicodeEscaped(null) = null
    370     *   CharUtils.unicodeEscaped(' ')  = "\u0020"
    371     *   CharUtils.unicodeEscaped('A')  = "\u0041"
    372     * </pre>
    373     *
    374     * @param ch  the character to convert, may be null
    375     * @return the escaped Unicode string, null if null input
    376     */
    377    public static String unicodeEscaped(final Character ch) {
    378        if (ch == null) {
    379            return null;
    380        }
    381        return unicodeEscaped(ch.charValue());
    382    }
    383
    384    //--------------------------------------------------------------------------
    385    /**
    386     * <p>Checks whether the character is ASCII 7 bit.</p>
    387     *
    388     * <pre>
    389     *   CharUtils.isAscii('a')  = true
    390     *   CharUtils.isAscii('A')  = true
    391     *   CharUtils.isAscii('3')  = true
    392     *   CharUtils.isAscii('-')  = true
    393     *   CharUtils.isAscii('\n') = true
    394     *   CharUtils.isAscii('&copy;') = false
    395     * </pre>
    396     *
    397     * @param ch  the character to check
    398     * @return true if less than 128
    399     */
    400    public static boolean isAscii(final char ch) {
    401        return ch < 128;
    402    }
    403
    404    /**
    405     * <p>Checks whether the character is ASCII 7 bit printable.</p>
    406     *
    407     * <pre>
    408     *   CharUtils.isAsciiPrintable('a')  = true
    409     *   CharUtils.isAsciiPrintable('A')  = true
    410     *   CharUtils.isAsciiPrintable('3')  = true
    411     *   CharUtils.isAsciiPrintable('-')  = true
    412     *   CharUtils.isAsciiPrintable('\n') = false
    413     *   CharUtils.isAsciiPrintable('&copy;') = false
    414     * </pre>
    415     *
    416     * @param ch  the character to check
    417     * @return true if between 32 and 126 inclusive
    418     */
    419    public static boolean isAsciiPrintable(final char ch) {
    420        return ch >= 32 && ch < 127;
    421    }
    422
    423    /**
    424     * <p>Checks whether the character is ASCII 7 bit control.</p>
    425     *
    426     * <pre>
    427     *   CharUtils.isAsciiControl('a')  = false
    428     *   CharUtils.isAsciiControl('A')  = false
    429     *   CharUtils.isAsciiControl('3')  = false
    430     *   CharUtils.isAsciiControl('-')  = false
    431     *   CharUtils.isAsciiControl('\n') = true
    432     *   CharUtils.isAsciiControl('&copy;') = false
    433     * </pre>
    434     *
    435     * @param ch  the character to check
    436     * @return true if less than 32 or equals 127
    437     */
    438    public static boolean isAsciiControl(final char ch) {
    439        return ch < 32 || ch == 127;
    440    }
    441
    442    /**
    443     * <p>Checks whether the character is ASCII 7 bit alphabetic.</p>
    444     *
    445     * <pre>
    446     *   CharUtils.isAsciiAlpha('a')  = true
    447     *   CharUtils.isAsciiAlpha('A')  = true
    448     *   CharUtils.isAsciiAlpha('3')  = false
    449     *   CharUtils.isAsciiAlpha('-')  = false
    450     *   CharUtils.isAsciiAlpha('\n') = false
    451     *   CharUtils.isAsciiAlpha('&copy;') = false
    452     * </pre>
    453     *
    454     * @param ch  the character to check
    455     * @return true if between 65 and 90 or 97 and 122 inclusive
    456     */
    457    public static boolean isAsciiAlpha(final char ch) {
    458        return isAsciiAlphaUpper(ch) || isAsciiAlphaLower(ch);
    459    }
    460
    461    /**
    462     * <p>Checks whether the character is ASCII 7 bit alphabetic upper case.</p>
    463     *
    464     * <pre>
    465     *   CharUtils.isAsciiAlphaUpper('a')  = false
    466     *   CharUtils.isAsciiAlphaUpper('A')  = true
    467     *   CharUtils.isAsciiAlphaUpper('3')  = false
    468     *   CharUtils.isAsciiAlphaUpper('-')  = false
    469     *   CharUtils.isAsciiAlphaUpper('\n') = false
    470     *   CharUtils.isAsciiAlphaUpper('&copy;') = false
    471     * </pre>
    472     *
    473     * @param ch  the character to check
    474     * @return true if between 65 and 90 inclusive
    475     */
    476    public static boolean isAsciiAlphaUpper(final char ch) {
    477        return ch >= 'A' && ch <= 'Z';
    478    }
    479
    480    /**
    481     * <p>Checks whether the character is ASCII 7 bit alphabetic lower case.</p>
    482     *
    483     * <pre>
    484     *   CharUtils.isAsciiAlphaLower('a')  = true
    485     *   CharUtils.isAsciiAlphaLower('A')  = false
    486     *   CharUtils.isAsciiAlphaLower('3')  = false
    487     *   CharUtils.isAsciiAlphaLower('-')  = false
    488     *   CharUtils.isAsciiAlphaLower('\n') = false
    489     *   CharUtils.isAsciiAlphaLower('&copy;') = false
    490     * </pre>
    491     *
    492     * @param ch  the character to check
    493     * @return true if between 97 and 122 inclusive
    494     */
    495    public static boolean isAsciiAlphaLower(final char ch) {
    496        return ch >= 'a' && ch <= 'z';
    497    }
    498
    499    /**
    500     * <p>Checks whether the character is ASCII 7 bit numeric.</p>
    501     *
    502     * <pre>
    503     *   CharUtils.isAsciiNumeric('a')  = false
    504     *   CharUtils.isAsciiNumeric('A')  = false
    505     *   CharUtils.isAsciiNumeric('3')  = true
    506     *   CharUtils.isAsciiNumeric('-')  = false
    507     *   CharUtils.isAsciiNumeric('\n') = false
    508     *   CharUtils.isAsciiNumeric('&copy;') = false
    509     * </pre>
    510     *
    511     * @param ch  the character to check
    512     * @return true if between 48 and 57 inclusive
    513     */
    514    public static boolean isAsciiNumeric(final char ch) {
    515        return ch >= '0' && ch <= '9';
    516    }
    517
    518    /**
    519     * <p>Checks whether the character is ASCII 7 bit numeric.</p>
    520     *
    521     * <pre>
    522     *   CharUtils.isAsciiAlphanumeric('a')  = true
    523     *   CharUtils.isAsciiAlphanumeric('A')  = true
    524     *   CharUtils.isAsciiAlphanumeric('3')  = true
    525     *   CharUtils.isAsciiAlphanumeric('-')  = false
    526     *   CharUtils.isAsciiAlphanumeric('\n') = false
    527     *   CharUtils.isAsciiAlphanumeric('&copy;') = false
    528     * </pre>
    529     *
    530     * @param ch  the character to check
    531     * @return true if between 48 and 57 or 65 and 90 or 97 and 122 inclusive
    532     */
    533    public static boolean isAsciiAlphanumeric(final char ch) {
    534        return isAsciiAlpha(ch) || isAsciiNumeric(ch);
    535    }
    536
    537    /**
    538     * <p>Compares two {@code char} values numerically. This is the same functionality as provided in Java 7.</p>
    539     *
    540     * @param x the first {@code char} to compare
    541     * @param y the second {@code char} to compare
    542     * @return the value {@code 0} if {@code x == y};
    543     *         a value less than {@code 0} if {@code x < y}; and
    544     *         a value greater than {@code 0} if {@code x > y}
    545     * @since 3.4
    546     */
    547    public static int compare(final char x, final char y) {
    548        return x-y;
    549    }
    550}