Package org.apache.commons.lang

## Class CharUtils

- java.lang.Object
- - org.apache.commons.lang.CharUtils

-     public class CharUtils
      extends Object

  Operations on char primitives and Character objects.

  This class tries to handle `null` input gracefully. An exception will not be thrown for a `null` input. Each method documents its behaviour in more detail.

  #ThreadSafe#

  Since:
    2.1
  Version:
    $Id: CharUtils.java 1056988 2011-01-09 17:58:53Z niallp $

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static char` | `CR` | `` carriage return CR ('\r').
    `static char` | `LF` | `` linefeed LF ('\n').

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CharUtils()` | `CharUtils` instances should NOT be constructed in standard programming.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static boolean` | `isAscii​(char ch)` | Checks whether the character is ASCII 7 bit.
    `static boolean` | `isAsciiAlpha​(char ch)` | Checks whether the character is ASCII 7 bit alphabetic.
    `static boolean` | `isAsciiAlphaLower​(char ch)` | Checks whether the character is ASCII 7 bit alphabetic lower case.
    `static boolean` | `isAsciiAlphanumeric​(char ch)` | Checks whether the character is ASCII 7 bit numeric.
    `static boolean` | `isAsciiAlphaUpper​(char ch)` | Checks whether the character is ASCII 7 bit alphabetic upper case.
    `static boolean` | `isAsciiControl​(char ch)` | Checks whether the character is ASCII 7 bit control.
    `static boolean` | `isAsciiNumeric​(char ch)` | Checks whether the character is ASCII 7 bit numeric.
    `static boolean` | `isAsciiPrintable​(char ch)` | Checks whether the character is ASCII 7 bit printable.
    `static char` | `toChar​(Character ch)` | Converts the Character to a char throwing an exception for `null`.
    `static char` | `toChar​(Character ch, char defaultValue)` | Converts the Character to a char handling `null`.
    `static char` | `toChar​(String str)` | Converts the String to a char using the first character, throwing an exception on empty Strings.
    `static char` | `toChar​(String str, char defaultValue)` | Converts the String to a char using the first character, defaulting the value on empty Strings.
    `static Character` | `toCharacterObject​(char ch)` | Converts the character to a Character.
    `static Character` | `toCharacterObject​(String str)` | Converts the String to a Character using the first character, returning null for empty Strings.
    `static int` | `toIntValue​(char ch)` | Converts the character to the Integer it represents, throwing an exception if the character is not numeric.
    `static int` | `toIntValue​(char ch, int defaultValue)` | Converts the character to the Integer it represents, throwing an exception if the character is not numeric.
    `static int` | `toIntValue​(Character ch)` | Converts the character to the Integer it represents, throwing an exception if the character is not numeric.
    `static int` | `toIntValue​(Character ch, int defaultValue)` | Converts the character to the Integer it represents, throwing an exception if the character is not numeric.
    `static String` | `toString​(char ch)` | Converts the character to a String that contains the one character.
    `static String` | `toString​(Character ch)` | Converts the character to a String that contains the one character.
    `static String` | `unicodeEscaped​(char ch)` | Converts the string to the unicode format ' '.
    `static String` | `unicodeEscaped​(Character ch)` | Converts the string to the unicode format ' '.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### LF

          public static final char LF

      `` linefeed LF ('\n').
      Since:
        2.2
      See Also:
        JLF: Escape Sequences for Character and String Literals, Constant Field Values

    - #### CR

          public static final char CR

      `` carriage return CR ('\r').
      Since:
        2.2
      See Also:
        JLF: Escape Sequences for Character and String Literals, Constant Field Values

  - ### Constructor Detail

    - #### CharUtils

          public CharUtils()

      `CharUtils` instances should NOT be constructed in standard programming. Instead, the class should be used as `CharUtils.toString('c');`.

      This constructor is public to permit tools that require a JavaBean instance to operate.

  - ### Method Detail

    - #### toCharacterObject

          public static Character toCharacterObject​(char ch)

      Converts the character to a Character.

      For ASCII 7 bit characters, this uses a cache that will return the same Character object each time.

             CharUtils.toCharacterObject(' ')  = ' '
             CharUtils.toCharacterObject('A')  = 'A'

      Parameters:
        `ch` - the character to convert
      Returns:
        a Character of the specified character

    - #### toCharacterObject

          public static Character toCharacterObject​(String str)

      Converts the String to a Character using the first character, returning null for empty Strings.

      For ASCII 7 bit characters, this uses a cache that will return the same Character object each time.

             CharUtils.toCharacterObject(null) = null
             CharUtils.toCharacterObject("")   = null
             CharUtils.toCharacterObject("A")  = 'A'
             CharUtils.toCharacterObject("BA") = 'B'

      Parameters:
        `str` - the character to convert
      Returns:
        the Character value of the first letter of the String

    - #### toChar

          public static char toChar​(Character ch)

      Converts the Character to a char throwing an exception for `null`.

             CharUtils.toChar(null) = IllegalArgumentException
             CharUtils.toChar(' ')  = ' '
             CharUtils.toChar('A')  = 'A'

      Parameters:
        `ch` - the character to convert
      Returns:
        the char value of the Character
      Throws:
        `IllegalArgumentException` - if the Character is null

    - #### toChar

          public static char toChar​(Character ch,
                                    char defaultValue)

      Converts the Character to a char handling `null`.

             CharUtils.toChar(null, 'X') = 'X'
             CharUtils.toChar(' ', 'X')  = ' '
             CharUtils.toChar('A', 'X')  = 'A'

      Parameters:
        `ch` - the character to convert
        `defaultValue` - the value to use if the Character is null
      Returns:
        the char value of the Character or the default if null

    - #### toChar

          public static char toChar​(String str)

      Converts the String to a char using the first character, throwing an exception on empty Strings.

             CharUtils.toChar(null) = IllegalArgumentException
             CharUtils.toChar("")   = IllegalArgumentException
             CharUtils.toChar("A")  = 'A'
             CharUtils.toChar("BA") = 'B'

      Parameters:
        `str` - the character to convert
      Returns:
        the char value of the first letter of the String
      Throws:
        `IllegalArgumentException` - if the String is empty

    - #### toChar

          public static char toChar​(String str,
                                    char defaultValue)

      Converts the String to a char using the first character, defaulting the value on empty Strings.

             CharUtils.toChar(null, 'X') = 'X'
             CharUtils.toChar("", 'X')   = 'X'
             CharUtils.toChar("A", 'X')  = 'A'
             CharUtils.toChar("BA", 'X') = 'B'

      Parameters:
        `str` - the character to convert
        `defaultValue` - the value to use if the Character is null
      Returns:
        the char value of the first letter of the String or the default if null

    - #### toIntValue

          public static int toIntValue​(char ch)

      Converts the character to the Integer it represents, throwing an exception if the character is not numeric.

      This method coverts the char '1' to the int 1 and so on.

             CharUtils.toIntValue('3')  = 3
             CharUtils.toIntValue('A')  = IllegalArgumentException

      Parameters:
        `ch` - the character to convert
      Returns:
        the int value of the character
      Throws:
        `IllegalArgumentException` - if the character is not ASCII numeric

    - #### toIntValue

          public static int toIntValue​(char ch,
                                       int defaultValue)

      Converts the character to the Integer it represents, throwing an exception if the character is not numeric.

      This method coverts the char '1' to the int 1 and so on.

             CharUtils.toIntValue('3', -1)  = 3
             CharUtils.toIntValue('A', -1)  = -1

      Parameters:
        `ch` - the character to convert
        `defaultValue` - the default value to use if the character is not numeric
      Returns:
        the int value of the character

    - #### toIntValue

          public static int toIntValue​(Character ch)

      Converts the character to the Integer it represents, throwing an exception if the character is not numeric.

      This method coverts the char '1' to the int 1 and so on.

             CharUtils.toIntValue(null) = IllegalArgumentException
             CharUtils.toIntValue('3')  = 3
             CharUtils.toIntValue('A')  = IllegalArgumentException

      Parameters:
        `ch` - the character to convert, not null
      Returns:
        the int value of the character
      Throws:
        `IllegalArgumentException` - if the Character is not ASCII numeric or is null

    - #### toIntValue

          public static int toIntValue​(Character ch,
                                       int defaultValue)

      Converts the character to the Integer it represents, throwing an exception if the character is not numeric.

      This method coverts the char '1' to the int 1 and so on.

             CharUtils.toIntValue(null, -1) = -1
             CharUtils.toIntValue('3', -1)  = 3
             CharUtils.toIntValue('A', -1)  = -1

      Parameters:
        `ch` - the character to convert
        `defaultValue` - the default value to use if the character is not numeric
      Returns:
        the int value of the character

    - #### toString

          public static String toString​(char ch)

      Converts the character to a String that contains the one character.

      For ASCII 7 bit characters, this uses a cache that will return the same String object each time.

             CharUtils.toString(' ')  = " "
             CharUtils.toString('A')  = "A"

      Parameters:
        `ch` - the character to convert
      Returns:
        a String containing the one specified character

    - #### toString

          public static String toString​(Character ch)

      Converts the character to a String that contains the one character.

      For ASCII 7 bit characters, this uses a cache that will return the same String object each time.

      If `null` is passed in, `null` will be returned.

             CharUtils.toString(null) = null
             CharUtils.toString(' ')  = " "
             CharUtils.toString('A')  = "A"

      Parameters:
        `ch` - the character to convert
      Returns:
        a String containing the one specified character

    - #### unicodeEscaped

          public static String unicodeEscaped​(char ch)

      Converts the string to the unicode format ' '.

      This format is the Java source code format.

             CharUtils.unicodeEscaped(' ') = " "
             CharUtils.unicodeEscaped('A') = "A"

      Parameters:
        `ch` - the character to convert
      Returns:
        the escaped unicode string

    - #### unicodeEscaped

          public static String unicodeEscaped​(Character ch)

      Converts the string to the unicode format ' '.

      This format is the Java source code format.

      If `null` is passed in, `null` will be returned.

             CharUtils.unicodeEscaped(null) = null
             CharUtils.unicodeEscaped(' ')  = " "
             CharUtils.unicodeEscaped('A')  = "A"

      Parameters:
        `ch` - the character to convert, may be null
      Returns:
        the escaped unicode string, null if null input

    - #### isAscii

          public static boolean isAscii​(char ch)

      Checks whether the character is ASCII 7 bit.

             CharUtils.isAscii('a')  = true
             CharUtils.isAscii('A')  = true
             CharUtils.isAscii('3')  = true
             CharUtils.isAscii('-')  = true
             CharUtils.isAscii('\n') = true
             CharUtils.isAscii('©') = false

      Parameters:
        `ch` - the character to check
      Returns:
        true if less than 128

    - #### isAsciiPrintable

          public static boolean isAsciiPrintable​(char ch)

      Checks whether the character is ASCII 7 bit printable.

             CharUtils.isAsciiPrintable('a')  = true
             CharUtils.isAsciiPrintable('A')  = true
             CharUtils.isAsciiPrintable('3')  = true
             CharUtils.isAsciiPrintable('-')  = true
             CharUtils.isAsciiPrintable('\n') = false
             CharUtils.isAsciiPrintable('©') = false

      Parameters:
        `ch` - the character to check
      Returns:
        true if between 32 and 126 inclusive

    - #### isAsciiControl

          public static boolean isAsciiControl​(char ch)

      Checks whether the character is ASCII 7 bit control.

             CharUtils.isAsciiControl('a')  = false
             CharUtils.isAsciiControl('A')  = false
             CharUtils.isAsciiControl('3')  = false
             CharUtils.isAsciiControl('-')  = false
             CharUtils.isAsciiControl('\n') = true
             CharUtils.isAsciiControl('©') = false

      Parameters:
        `ch` - the character to check
      Returns:
        true if less than 32 or equals 127

    - #### isAsciiAlpha

          public static boolean isAsciiAlpha​(char ch)

      Checks whether the character is ASCII 7 bit alphabetic.

             CharUtils.isAsciiAlpha('a')  = true
             CharUtils.isAsciiAlpha('A')  = true
             CharUtils.isAsciiAlpha('3')  = false
             CharUtils.isAsciiAlpha('-')  = false
             CharUtils.isAsciiAlpha('\n') = false
             CharUtils.isAsciiAlpha('©') = false

      Parameters:
        `ch` - the character to check
      Returns:
        true if between 65 and 90 or 97 and 122 inclusive

    - #### isAsciiAlphaUpper

          public static boolean isAsciiAlphaUpper​(char ch)

      Checks whether the character is ASCII 7 bit alphabetic upper case.

             CharUtils.isAsciiAlphaUpper('a')  = false
             CharUtils.isAsciiAlphaUpper('A')  = true
             CharUtils.isAsciiAlphaUpper('3')  = false
             CharUtils.isAsciiAlphaUpper('-')  = false
             CharUtils.isAsciiAlphaUpper('\n') = false
             CharUtils.isAsciiAlphaUpper('©') = false

      Parameters:
        `ch` - the character to check
      Returns:
        true if between 65 and 90 inclusive

    - #### isAsciiAlphaLower

          public static boolean isAsciiAlphaLower​(char ch)

      Checks whether the character is ASCII 7 bit alphabetic lower case.

             CharUtils.isAsciiAlphaLower('a')  = true
             CharUtils.isAsciiAlphaLower('A')  = false
             CharUtils.isAsciiAlphaLower('3')  = false
             CharUtils.isAsciiAlphaLower('-')  = false
             CharUtils.isAsciiAlphaLower('\n') = false
             CharUtils.isAsciiAlphaLower('©') = false

      Parameters:
        `ch` - the character to check
      Returns:
        true if between 97 and 122 inclusive

    - #### isAsciiNumeric

          public static boolean isAsciiNumeric​(char ch)

      Checks whether the character is ASCII 7 bit numeric.

             CharUtils.isAsciiNumeric('a')  = false
             CharUtils.isAsciiNumeric('A')  = false
             CharUtils.isAsciiNumeric('3')  = true
             CharUtils.isAsciiNumeric('-')  = false
             CharUtils.isAsciiNumeric('\n') = false
             CharUtils.isAsciiNumeric('©') = false

      Parameters:
        `ch` - the character to check
      Returns:
        true if between 48 and 57 inclusive

    - #### isAsciiAlphanumeric

          public static boolean isAsciiAlphanumeric​(char ch)

      Checks whether the character is ASCII 7 bit numeric.

             CharUtils.isAsciiAlphanumeric('a')  = true
             CharUtils.isAsciiAlphanumeric('A')  = true
             CharUtils.isAsciiAlphanumeric('3')  = true
             CharUtils.isAsciiAlphanumeric('-')  = false
             CharUtils.isAsciiAlphanumeric('\n') = false
             CharUtils.isAsciiAlphanumeric('©') = false

      Parameters:
        `ch` - the character to check
      Returns:
        true if between 48 and 57 or 65 and 90 or 97 and 122 inclusive