CharUtils (Apache Commons Lang 3.6 API)

java.lang.Object
- org.apache.commons.lang3.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

Field Summary

Fields
Modifier and Type	Field and Description
`static char`	`CR` carriage return CR ('\r').
`static char`	`LF` linefeed LF ('\n').
`static char`	`NUL` null control character ('\0'), abbreviated NUL.

Constructor Summary

Constructors
Constructor and Description

CharUtils()
CharUtils instances should NOT be constructed in standard programming.

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

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static int`	`compare(char x, char y)` Compares two `char` values numerically.
`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)` Deprecated. Java 5 introduced `Character.valueOf(char)` which caches chars 0 through 127.
`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(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 int`	`toIntValue(char 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
  - NUL
```
public static final char NUL
```
    null control character ('\0'), abbreviated NUL.
    
    Since:
    
    3.6
    
    See Also:
    
    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
```
@Deprecated
public static Character toCharacterObject(char ch)
```
    Deprecated. Java 5 introduced Character.valueOf(char) which caches chars 0 through 127.
    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(' ')  = ' '
   CharUtils.toChar('A')  = 'A'
   CharUtils.toChar(null) throws IllegalArgumentException
 
```
    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("A")  = 'A'
   CharUtils.toChar("BA") = 'B'
   CharUtils.toChar(null) throws IllegalArgumentException
   CharUtils.toChar("")   throws IllegalArgumentException
 
```
    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')  throws 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('3')  = 3
   CharUtils.toIntValue(null) throws IllegalArgumentException
   CharUtils.toIntValue('A')  throws 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
  - compare
```
public static int compare(char x,
                          char y)
```
    Compares two char values numerically. This is the same functionality as provided in Java 7.
    
    Parameters:
    
    x - the first char to compare
    
    y - the second char to compare
    
    Returns:
    
    the value 0 if x == y; a value less than 0 if x < y; and a value greater than 0 if x > y
    
    Since:
    
    3.4

Class CharUtils

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LF

CR

NUL

Constructor Detail

CharUtils

Method Detail

toCharacterObject

toCharacterObject

toChar

toChar

toChar

toChar

toIntValue

toIntValue

toIntValue

toIntValue

toString

toString

unicodeEscaped

unicodeEscaped

isAscii

isAsciiPrintable

isAsciiControl

isAsciiAlpha

isAsciiAlphaUpper

isAsciiAlphaLower

isAsciiNumeric

isAsciiAlphanumeric

compare