Package org.apache.commons.lang3

Class CharUtils

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 behavior in more detail.

#ThreadSafe#

Since:

2.1

Field Summary

Fields

Modifier and Type	Field	Description
static final char	CR	Carriage return character CR ('\r', Unicode 000d).
static final char	LF	Linefeed character LF ('\n', Unicode 000a).
static final char	NUL	null control character ('\0'), abbreviated NUL.

Constructor Summary

Constructors

Constructor	Description
CharUtils()	Deprecated. TODO Make private in 4.0.

Method Summary

Modifier and Type	Method	Description
static int	compare(char x, char y)	Compares two char values numerically.
static boolean	isAscii(char ch)	Tests whether the character is ASCII 7 bit.
static boolean	isAsciiAlpha(char ch)	Tests whether the character is ASCII 7 bit alphabetic.
static boolean	isAsciiAlphaLower(char ch)	Tests whether the character is ASCII 7 bit alphabetic lower case.
static boolean	isAsciiAlphanumeric(char ch)	Tests whether the character is ASCII 7 bit numeric.
static boolean	isAsciiAlphaUpper(char ch)	Tests whether the character is ASCII 7 bit alphabetic upper case.
static boolean	isAsciiControl(char ch)	Tests whether the character is ASCII 7 bit control.
static boolean	isAsciiNumeric(char ch)	Tests whether the character is ASCII 7 bit numeric.
static boolean	isAsciiPrintable(char ch)	Tests whether the character is ASCII 7 bit printable.
static boolean	isHex(char ch)	Tests whether a character is a hexadecimal character.
static boolean	isOctal(char ch)	Tests if the given char is an octal digit.
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 c)	Deprecated. Use Character.valueOf(char).
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 Details

LF

public static final char LF

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

Since:

2.2

See Also:

• JLF: Escape Sequences for Character and String Literals
• Constant Field Values

CR

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
• Constant Field Values

NUL

public static final char NUL

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

Since:

3.6

See Also:

• Constant Field Values

Constructor Details

CharUtils

@Deprecated
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.

Method Details

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

isAscii

public static boolean isAscii(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 - the character to check

Returns:

true if less than 128

isAsciiAlpha

public static boolean isAsciiAlpha(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 - the character to check

Returns:

true if between 65 and 90 or 97 and 122 inclusive

isAsciiAlphaLower

public static boolean isAsciiAlphaLower(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 - the character to check

Returns:

true if between 97 and 122 inclusive

isAsciiAlphanumeric

public static boolean isAsciiAlphanumeric(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 - the character to check

Returns:

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

isAsciiAlphaUpper

public static boolean isAsciiAlphaUpper(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 - the character to check

Returns:

true if between 65 and 90 inclusive

isAsciiControl

public static boolean isAsciiControl(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 - the character to check

Returns:

true if less than 32 or equals 127

isAsciiNumeric

public static boolean isAsciiNumeric(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 - the character to check

Returns:

true if between 48 and 57 inclusive

isAsciiPrintable

public static boolean isAsciiPrintable(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 - the character to check

Returns:

true if between 32 and 126 inclusive

isHex

public static boolean isHex(char ch)

Tests whether a character is a hexadecimal character.

   CharUtils.isAsciiPrintable('0')  = true
   CharUtils.isAsciiPrintable('9')  = true
   CharUtils.isAsciiPrintable('a')  = true
   CharUtils.isAsciiPrintable('f')  = true
   CharUtils.isAsciiPrintable('g')  = false
   CharUtils.isAsciiPrintable('A')  = true
   CharUtils.isAsciiPrintable('F')  = true
   CharUtils.isAsciiPrintable('G')  = false
   CharUtils.isAsciiPrintable('3')  = false
   CharUtils.isAsciiPrintable('-')  = false
   CharUtils.isAsciiPrintable('\n') = false
   CharUtils.isAsciiPrintable('©') = false
 

Parameters:

ch - the character to test.

Returns:

true if character is a hexadecimal character.

Since:

3.18.0

isOctal

public static boolean isOctal(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 - 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

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:

NullPointerException - 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:

NullPointerException - if the string is null

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

toCharacterObject

@Deprecated
public static Character toCharacterObject(char c)

Deprecated.

Use Character.valueOf(char).

Delegates to Character.valueOf(char).

Parameters:

c - the character to convert

Returns:

a Character representing c.

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

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

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 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

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 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 - the character to convert, not null

Returns:

the int value of the character

Throws:

NullPointerException - if the Character is null

IllegalArgumentException - if the Character is not ASCII numeric

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 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

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