java.lang.Object

org.apache.commons.lang3.CharUtils

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

Class CharUtils

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Details

LF

CR

NUL

Constructor Details

CharUtils

Method Details

compare

isAscii

isAsciiAlpha

isAsciiAlphaLower

isAsciiAlphanumeric

isAsciiAlphaUpper

isAsciiControl

isAsciiNumeric

isAsciiPrintable

isHex

isOctal

toChar

toChar

toChar

toChar

toCharacterObject

toCharacterObject

toIntValue

toIntValue

toIntValue

toIntValue

toString

toString

unicodeEscaped

unicodeEscaped