CharUtils¶

public class org.apache.commons.lang3.CharUtils[source]¶

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

Constructors¶

CharUtils()

Deprecated. CharUtils instances should NOT be constructed in standard programming.

@Deprecated public CharUtils()[source]¶

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.

Fields and constants¶

`CR`	Carriage return character CR (‘\r’, Unicode 000d).
`LF`	Linefeed character LF (`'\n'`, Unicode 000a).
`NUL`	`\u0000` null control character (‘\0’), abbreviated NUL.

public static final char CR = '\r'[source]¶

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

See also:: JLF: Escape Sequences for Character and String Literals
Since:: 2.2

public static final char LF = '\n'[source]¶

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

See also:: JLF: Escape Sequences for Character and String Literals
Since:: 2.2

public static final char NUL = '\u0000'[source]¶

\u0000 null control character (‘\0’), abbreviated NUL.

Since:: 3.6

Methods¶

`compare(char, char)`	Compares two `char` values numerically.
`isAscii(char)`	Tests whether the character is ASCII 7 bit.
`isAsciiAlpha(char)`	Tests whether the character is ASCII 7 bit alphabetic.
`isAsciiAlphaLower(char)`	Tests whether the character is ASCII 7 bit alphabetic lower case.
`isAsciiAlphaUpper(char)`	Tests whether the character is ASCII 7 bit alphabetic upper case.
`isAsciiAlphanumeric(char)`	Tests whether the character is ASCII 7 bit alphanumeric character.
`isAsciiControl(char)`	Tests whether the character is ASCII 7 bit control.
`isAsciiNumeric(char)`	Tests whether the character is ASCII 7 bit numeric.
`isAsciiNumeric(int)`	Tests whether the character is ASCII 7 bit numeric.
`isAsciiPrintable(char)`	Tests whether the character is ASCII 7 bit printable.
`isHex(char)`	Tests whether a character is a hexadecimal character.
`isHex(int)`	Tests whether a character is a hexadecimal character.
`isOctal(byte)`	Tests if the given char is an octal digit.
`isOctal(char)`	Tests if the given char is an octal digit.
`toChar(Character)`	Converts the Character to a char throwing an exception for `null`.
`toChar(Character, char)`	Converts the Character to a char handling `null`.
`toChar(String)`	Converts the String to a char using the first character, throwing an exception on empty Strings.
`toChar(String, char)`	Converts the String to a char using the first character, defaulting the value on empty Strings.
`toCharacterObject(char)`	Deprecated. Delegates to `Character#valueOf(char)`.
`toCharacterObject(String)`	Converts the String to a Character using the first character, returning null for empty Strings.
`toIntValue(char)`	Converts the character to the Integer it represents, throwing an exception if the character is not numeric.
`toIntValue(char, int)`	Converts the character to the Integer it represents, throwing an exception if the character is not numeric.
`toIntValue(Character)`	Converts the character to the Integer it represents, throwing an exception if the character is not numeric.
`toIntValue(Character, int)`	Converts the character to the Integer it represents, throwing an exception if the character is not numeric.
`toString(char)`	Converts the character to a String that contains the one character.
`toString(Character)`	Converts the character to a String that contains the one character.
`unicodeEscaped(char)`	Converts the string to the Unicode format ‘ ‘.
`unicodeEscaped(Character)`	Converts the string to the Unicode format ‘ ‘.

public static int compare(char x, char y)[source]¶

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

public static boolean isAscii(char ch)[source]¶

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 – The character to check
Returns:: true if less than 128

public static boolean isAsciiAlpha(char ch)[source]¶

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 – The character to check
Returns:: true if between 65 and 90 or 97 and 122 inclusive

public static boolean isAsciiAlphaLower(char ch)[source]¶

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 – The character to check
Returns:: true if between 97 and 122 inclusive

public static boolean isAsciiAlphaUpper(char ch)[source]¶

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 – The character to check
Returns:: true if between 65 and 90 inclusive

public static boolean isAsciiAlphanumeric(char ch)[source]¶

Tests whether the character is ASCII 7 bit alphanumeric character.

  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

public static boolean isAsciiControl(char ch)[source]¶

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 – The character to check
Returns:: true if less than 32 or equals 127

public static boolean isAsciiNumeric(char ch)[source]¶

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 – The character to check
Returns:: true if between 48 and 57 inclusive

public static boolean isAsciiNumeric(int ch)[source]¶

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 – The code point to check.
Returns:: true if between 48 and 57 inclusive.
Since:: 3.21.0

public static boolean isAsciiPrintable(char ch)[source]¶

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 – The character to check
Returns:: true if between 32 and 126 inclusive

public static boolean isHex(char ch)[source]¶

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 – The character to test.
Returns:: true if character is a hexadecimal character.
Since:: 3.18.0

public static boolean isHex(int ch)[source]¶

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 – The code point to test.
Returns:: true if character is a hexadecimal character.
Since:: 3.21.0

public static boolean isOctal(byte ch)[source]¶

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

Parameters:: ch – The byte to check.
Returns:: true if the given char is the character representation of one of the digits from 0 to 7.
Since:: 3.21.0

public static boolean isOctal(char ch)[source]¶

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

Parameters:: ch – The char to check.
Returns:: true if the given char is the character representation of one of the digits from 0 to 7.
Since:: 3.18.0

public static char toChar(Character ch)[source]¶

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

  CharUtils.toChar(' ')  = ' '
  CharUtils.toChar('A')  = 'A'
  CharUtils.toChar(null) throws NullPointerException

Parameters:: ch – The character to convert
Returns:: The char value of the Character
Throws:: java.lang.NullPointerException – Thrown if the Character is null.

public static char toChar(Character ch, char defaultValue)[source]¶

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

public static char toChar(String str)[source]¶

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 NullPointerException
  CharUtils.toChar("")   throws IllegalArgumentException

Parameters:

str – The character to convert

Returns:

The char value of the first letter of the String

Throws:

java.lang.NullPointerException – Thrown if the string is null.
java.lang.IllegalArgumentException – Thrown if the String is empty.

public static char toChar(String str, char defaultValue)[source]¶

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

@Deprecated public static Character toCharacterObject(char c)[source]¶

Deprecated: Use Character#valueOf(char).

Delegates to Character#valueOf(char).

Parameters:: c – The character to convert
Returns:: A Character representing c.

public static Character toCharacterObject(String str)[source]¶

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

public static int toIntValue(char ch)[source]¶

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 – The character to convert
Returns:: The int value of the character
Throws:: java.lang.IllegalArgumentException – Thrown if the character is not ASCII numeric.

public static int toIntValue(char ch, int defaultValue)[source]¶

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 – The character to convert
defaultValue – The default value to use if the character is not numeric

Returns:

The int value of the character

public static int toIntValue(Character ch)[source]¶

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 NullPointerException
  CharUtils.toIntValue('A')  throws IllegalArgumentException

Parameters:

ch – The character to convert, not null

Returns:

The int value of the character

Throws:

java.lang.NullPointerException – Thrown if the Character is null.
java.lang.IllegalArgumentException – Thrown if the Character is not ASCII numeric.

public static int toIntValue(Character ch, int defaultValue)[source]¶

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 – The character to convert
defaultValue – The default value to use if the character is not numeric

Returns:

The int value of the character

public static String toString(char ch)[source]¶

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

public static String toString(Character ch)[source]¶

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

public static String unicodeEscaped(char ch)[source]¶

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

public static String unicodeEscaped(Character ch)[source]¶

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