Top Description Fields Constructors Methods
org.apache.commons.lang3

public Class CharUtils

extends Object
Class Inheritance
Imports
java.util.Objects
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 behavior in more detail.

#ThreadSafe#

Since
2.1

Field Summary

Modifier and TypeField and Description
private static final String[]
CHAR_STRING_ARRAY

public static final char
CR

Carriage return character CR ('\r', Unicode 000d).

private static final char[]
HEX_DIGITS

public static final char
LF

Linefeed character LF ('\n', Unicode 000a).

public static final char
NUL

\0 null control character ('\0'), abbreviated NUL.

Constructor Summary

AccessConstructor and Description
public
CharUtils()
Deprecated TODO Make private in 4.0.

CharUtils instances should NOT be constructed in standard programming.

Method Summary

Modifier and TypeMethod and Description
public static int

Returns:

the value 0 if x == y; a value less than 0 if x < y; and a value greater than 0 if x > y
compare(final char
the first char to compare
x, final char
the second char to compare
y)

Compares two char values numerically.

public static boolean

Returns:

true if less than 128
isAscii(final char
the character to check
ch)

Tests whether the character is ASCII 7 bit.

public static boolean

Returns:

true if between 65 and 90 or 97 and 122 inclusive
isAsciiAlpha(final char
the character to check
ch)

Tests whether the character is ASCII 7 bit alphabetic.

public static boolean

Returns:

true if between 97 and 122 inclusive
isAsciiAlphaLower(final char
the character to check
ch)

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

public static boolean

Returns:

true if between 48 and 57 or 65 and 90 or 97 and 122 inclusive
isAsciiAlphanumeric(final char
the character to check
ch)

Tests whether the character is ASCII 7 bit numeric.

public static boolean

Returns:

true if between 65 and 90 inclusive
isAsciiAlphaUpper(final char
the character to check
ch)

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

public static boolean

Returns:

true if less than 32 or equals 127
isAsciiControl(final char
the character to check
ch)

Tests whether the character is ASCII 7 bit control.

public static boolean

Returns:

true if between 48 and 57 inclusive
isAsciiNumeric(final char
the character to check
ch)

Tests whether the character is ASCII 7 bit numeric.

public static boolean

Returns:

true if between 32 and 126 inclusive
isAsciiPrintable(final char
the character to check
ch)

Tests whether the character is ASCII 7 bit printable.

public static boolean

Returns:

true if character is a hexadecimal character.
isHex(final char
the character to test.
ch)

Tests whether a character is a hexadecimal character.

public static boolean

Returns:

true if the given char is the character representation of one of the digits from 0 to 7
isOctal(final char
the char to check
ch)

Tests if the given char is an octal digit.

public static char

Returns:

the char value of the Character
toChar(final Character
the character to convert
ch)

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

public static char

Returns:

the char value of the Character or the default if null
toChar(final Character
the character to convert
ch, final char
the value to use if the Character is null
defaultValue)

Converts the Character to a char handling null.

public static char

Returns:

the char value of the first letter of the String
toChar(final String
the character to convert
str)

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

public static char

Returns:

the char value of the first letter of the String or the default if null
toChar(final String
the character to convert
str, final char
the value to use if the Character is null
defaultValue)

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

public static Character

Returns:

a Character representing c.
toCharacterObject(final char
the character to convert
c)
Deprecated Use Character#valueOf(char).

Delegates to Character#valueOf(char).

public static Character

Returns:

the Character value of the first letter of the String
toCharacterObject(final String
the character to convert
str)

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

public static int

Returns:

the int value of the character
toIntValue(final char
the character to convert
ch)

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

public static int

Returns:

the int value of the character
toIntValue(final char
the character to convert
ch, final int
the default value to use if the character is not numeric
defaultValue)

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

public static int

Returns:

the int value of the character
toIntValue(final Character
the character to convert, not null
ch)

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

public static int

Returns:

the int value of the character
toIntValue(final Character
the character to convert
ch, final int
the default value to use if the character is not numeric
defaultValue)

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

public static String

Returns:

a String containing the one specified character
toString(final char
the character to convert
ch)

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

public static String

Returns:

a String containing the one specified character
toString(final Character
the character to convert
ch)

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

public static String

Returns:

the escaped Unicode string
unicodeEscaped(final char
the character to convert
ch)

Converts the string to the Unicode format ' '.

public static String

Returns:

the escaped Unicode string, null if null input
unicodeEscaped(final Character
the character to convert, may be null
ch)

Converts the string to the Unicode format ' '.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

CHAR_STRING_ARRAYback to summary
private static final String[] CHAR_STRING_ARRAY
CRback to summary
public static final char CR

Carriage return character CR ('\r', Unicode 000d).

Since
2.2
See Also
JLF: Escape Sequences for Character and String Literals
HEX_DIGITSback to summary
private static final char[] HEX_DIGITS
LFback to summary
public static final char LF

Linefeed character LF ('\n', Unicode 000a).

Since
2.2
See Also
JLF: Escape Sequences for Character and String Literals
NULback to summary
public static final char NUL

\0 null control character ('\0'), abbreviated NUL.

Since
3.6

Constructor Detail

CharUtilsback to summary
public CharUtils()

Deprecated

TODO Make private in 4.0.

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.

Annotations
@Deprecated

Method Detail

compareback to summary
public static int compare(final char x, final char y)

Compares two char values numerically. This is the same functionality as provided in Java 7.

Parameters
x:char

the first char to compare

y:char

the second char to compare

Returns:int

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
isAsciiback to summary
public static boolean isAscii(final char ch)

Tests 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:char

the character to check

Returns:boolean

true if less than 128

isAsciiAlphaback to summary
public static boolean isAsciiAlpha(final char ch)

Tests 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:char

the character to check

Returns:boolean

true if between 65 and 90 or 97 and 122 inclusive

isAsciiAlphaLowerback to summary
public static boolean isAsciiAlphaLower(final char ch)

Tests 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:char

the character to check

Returns:boolean

true if between 97 and 122 inclusive

isAsciiAlphanumericback to summary
public static boolean isAsciiAlphanumeric(final char ch)

Tests 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:char

the character to check

Returns:boolean

true if between 48 and 57 or 65 and 90 or 97 and 122 inclusive

isAsciiAlphaUpperback to summary
public static boolean isAsciiAlphaUpper(final char ch)

Tests 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:char

the character to check

Returns:boolean

true if between 65 and 90 inclusive

isAsciiControlback to summary
public static boolean isAsciiControl(final char ch)

Tests 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:char

the character to check

Returns:boolean

true if less than 32 or equals 127

isAsciiNumericback to summary
public static boolean isAsciiNumeric(final char ch)

Tests 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:char

the character to check

Returns:boolean

true if between 48 and 57 inclusive

isAsciiPrintableback to summary
public static boolean isAsciiPrintable(final char ch)

Tests 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:char

the character to check

Returns:boolean

true if between 32 and 126 inclusive

isHexback to summary
public static boolean isHex(final char ch)

Tests whether a character is a hexadecimal character. 

  CharUtils.isHex('0')  = true
  CharUtils.isHex('3')  = true
  CharUtils.isHex('9')  = true
  CharUtils.isHex('a')  = true
  CharUtils.isHex('f')  = true
  CharUtils.isHex('g')  = false
  CharUtils.isHex('A')  = true
  CharUtils.isHex('F')  = true
  CharUtils.isHex('G')  = false
  CharUtils.isHex('#')  = false
  CharUtils.isHex('-')  = false
  CharUtils.isHex('\n') = false
  CharUtils.isHex('©') = false
Parameters
ch:char

the character to test.

Returns:boolean

true if character is a hexadecimal character.

Since
3.18.0
isOctalback to summary
public static boolean isOctal(final char ch)

Tests if the given char is an octal digit. Octal digits are the character representations of the digits 0 to 7.

Parameters
ch:char

the char to check

Returns:boolean

true if the given char is the character representation of one of the digits from 0 to 7

Since
3.18.0
toCharback to summary
public static char toChar(final 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:Character

the character to convert

Returns:char

the char value of the Character

Exceptions
NullPointerException:
if the Character is null
toCharback to summary
public static char toChar(final Character ch, final 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:Character

the character to convert

defaultValue:char

the value to use if the Character is null

Returns:char

the char value of the Character or the default if null

toCharback to summary
public static char toChar(final 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:String

the character to convert

Returns:char

the char value of the first letter of the String

Exceptions
NullPointerException:
if the string is null
IllegalArgumentException:
if the String is empty
toCharback to summary
public static char toChar(final String str, final 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:String

the character to convert

defaultValue:char

the value to use if the Character is null

Returns:char

the char value of the first letter of the String or the default if null

toCharacterObjectback to summary
public static Character toCharacterObject(final char c)

Deprecated

Use Character#valueOf(char).

Delegates to Character#valueOf(char).

Parameters
c:char

the character to convert

Returns:Character

a Character representing c.

Annotations
@Deprecated
toCharacterObjectback to summary
public static Character toCharacterObject(final 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:String

the character to convert

Returns:Character

the Character value of the first letter of the String

toIntValueback to summary
public static int toIntValue(final char ch)

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

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

  CharUtils.toIntValue('3')  = 3
  CharUtils.toIntValue('A')  throws IllegalArgumentException
Parameters
ch:char

the character to convert

Returns:int

the int value of the character

Exceptions
IllegalArgumentException:
if the character is not ASCII numeric
toIntValueback to summary
public static int toIntValue(final char ch, final int defaultValue)

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

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

  CharUtils.toIntValue('3', -1)  = 3
  CharUtils.toIntValue('A', -1)  = -1
Parameters
ch:char

the character to convert

defaultValue:int

the default value to use if the character is not numeric

Returns:int

the int value of the character

toIntValueback to summary
public static int toIntValue(final Character ch)

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

This method converts 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:Character

the character to convert, not null

Returns:int

the int value of the character

Exceptions
NullPointerException:
if the Character is null
IllegalArgumentException:
if the Character is not ASCII numeric
toIntValueback to summary
public static int toIntValue(final Character ch, final int defaultValue)

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

This method converts 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:Character

the character to convert

defaultValue:int

the default value to use if the character is not numeric

Returns:int

the int value of the character

toStringback to summary
public static String toString(final 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:char

the character to convert

Returns:String

a String containing the one specified character

toStringback to summary
public static String toString(final 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:Character

the character to convert

Returns:String

a String containing the one specified character

unicodeEscapedback to summary
public static String unicodeEscaped(final 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:char

the character to convert

Returns:String

the escaped Unicode string

unicodeEscapedback to summary
public static String unicodeEscaped(final 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:Character

the character to convert, may be null

Returns:String

the escaped Unicode string, null if null input