Package org.apache.commons.lang

# Class CharSetUtils

java.lang.Object
org.apache.commons.lang.CharSetUtils

public class CharSetUtils extends Object

Operations on `CharSet`s.

This class handles `null` input gracefully. An exception will not be thrown for a `null` input. Each method documents its behaviour in more detail.

#ThreadSafe#

Since:
  1.0
Version:
  $Id: CharSetUtils.java 1057072 2011-01-10 01:55:57Z niallp $
See Also:
  - `CharSet`

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`static int`
`count(String str, String set)`
Takes an argument in set-syntax, see evaluateSet, and returns the number of characters present in the specified string.
`static int`
`count(String str, String[] set)`
Takes an argument in set-syntax, see evaluateSet, and returns the number of characters present in the specified string.
`static String`
`delete(String str, String set)`
Takes an argument in set-syntax, see evaluateSet, and deletes any of characters present in the specified string.
`static String`
`delete(String str, String[] set)`
Takes an argument in set-syntax, see evaluateSet, and deletes any of characters present in the specified string.
`static CharSet`
`evaluateSet(String[] set)`
Deprecated.
Use `CharSet.getInstance(String[])`.
`static String`
`keep(String str, String set)`
Takes an argument in set-syntax, see evaluateSet, and keeps any of characters present in the specified string.
`static String`
`keep(String str, String[] set)`
Takes an argument in set-syntax, see evaluateSet, and keeps any of characters present in the specified string.
`static String`
`squeeze(String str, String set)`
Squeezes any repetitions of a character that is mentioned in the supplied set.
`static String`
`squeeze(String str, String[] set)`
Squeezes any repetitions of a character that is mentioned in the supplied set.
`static String`
`translate(String str, String searchChars, String replaceChars)`
Deprecated.
Use `StringUtils.replaceChars(String, String, String)`.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### CharSetUtils

public CharSetUtils()

CharSetUtils instances should NOT be constructed in standard programming. Instead, the class should be used as `CharSetUtils.evaluateSet(null);`.

This constructor is public to permit tools that require a JavaBean instance to operate.

## Method Details

### evaluateSet

public static CharSet evaluateSet(String[] set)
Deprecated.
Use `CharSet.getInstance(String[])`. Method will be removed in Commons Lang 3.0.

Creates a `CharSet` instance which allows a certain amount of set logic to be performed.

The syntax is:

- "aeio" which implies 'a','e',..
- "^e" implies not e.
- "ej-m" implies e,j->m. e,j,k,l,m.

     CharSetUtils.evaluateSet(null)    = null
     CharSetUtils.evaluateSet([])      = CharSet matching nothing
     CharSetUtils.evaluateSet(["a-e"]) = CharSet matching a,b,c,d,e

Parameters:
  `set` - the set, may be null
Returns:
  a CharSet instance, `null` if null input

### squeeze

public static String squeeze(String str, String set)

Squeezes any repetitions of a character that is mentioned in the supplied set.

     CharSetUtils.squeeze(null, *)        = null
     CharSetUtils.squeeze("", *)          = ""
     CharSetUtils.squeeze(*, null)        = *
     CharSetUtils.squeeze(*, "")          = *
     CharSetUtils.squeeze("hello", "k-p") = "helo"
     CharSetUtils.squeeze("hello", "a-e") = "hello"

Parameters:
  `str` - the string to squeeze, may be null
  `set` - the character set to use for manipulation, may be null
Returns:
  modified String, `null` if null string input
See Also:
  - `for set-syntax.`

### squeeze

public static String squeeze(String str, String[] set)

Squeezes any repetitions of a character that is mentioned in the supplied set.

An example is:

- squeeze("hello", {"el"}) => "helo"

Parameters:
  `str` - the string to squeeze, may be null
  `set` - the character set to use for manipulation, may be null
Returns:
  modified String, `null` if null string input
See Also:
  - `for set-syntax.`

### count

public static int count(String str, String set)

Takes an argument in set-syntax, see evaluateSet, and returns the number of characters present in the specified string.

     CharSetUtils.count(null, *)        = 0
     CharSetUtils.count("", *)          = 0
     CharSetUtils.count(*, null)        = 0
     CharSetUtils.count(*, "")          = 0
     CharSetUtils.count("hello", "k-p") = 3
     CharSetUtils.count("hello", "a-e") = 1

Parameters:
  `str` - String to count characters in, may be null
  `set` - String set of characters to count, may be null
Returns:
  character count, zero if null string input
See Also:
  - `for set-syntax.`

### count

public static int count(String str, String[] set)

Takes an argument in set-syntax, see evaluateSet, and returns the number of characters present in the specified string.

An example would be:

- count("hello", {"c-f", "o"}) returns 2.

Parameters:
  `str` - String to count characters in, may be null
  `set` - String[] set of characters to count, may be null
Returns:
  character count, zero if null string input
See Also:
  - `for set-syntax.`

### keep

public static String keep(String str, String set)

Takes an argument in set-syntax, see evaluateSet, and keeps any of characters present in the specified string.

     CharSetUtils.keep(null, *)        = null
     CharSetUtils.keep("", *)          = ""
     CharSetUtils.keep(*, null)        = ""
     CharSetUtils.keep(*, "")          = ""
     CharSetUtils.keep("hello", "hl")  = "hll"
     CharSetUtils.keep("hello", "le")  = "ell"

Parameters:
  `str` - String to keep characters from, may be null
  `set` - String set of characters to keep, may be null
Returns:
  modified String, `null` if null string input
Since:
  2.0
See Also:
  - `for set-syntax.`

### keep

public static String keep(String str, String[] set)

Takes an argument in set-syntax, see evaluateSet, and keeps any of characters present in the specified string.

An example would be:

- keep("hello", {"c-f", "o"}) returns "eo"

Parameters:
  `str` - String to keep characters from, may be null
  `set` - String[] set of characters to keep, may be null
Returns:
  modified String, `null` if null string input
Since:
  2.0
See Also:
  - `for set-syntax.`

### delete

public static String delete(String str, String set)

Takes an argument in set-syntax, see evaluateSet, and deletes any of characters present in the specified string.

     CharSetUtils.delete(null, *)        = null
     CharSetUtils.delete("", *)          = ""
     CharSetUtils.delete(*, null)        = *
     CharSetUtils.delete(*, "")          = *
     CharSetUtils.delete("hello", "hl")  = "eo"
     CharSetUtils.delete("hello", "le")  = "ho"

Parameters:
  `str` - String to delete characters from, may be null
  `set` - String set of characters to delete, may be null
Returns:
  modified String, `null` if null string input
See Also:
  - `for set-syntax.`

### delete

public static String delete(String str, String[] set)

Takes an argument in set-syntax, see evaluateSet, and deletes any of characters present in the specified string.

An example would be:

- delete("hello", {"c-f", "o"}) returns "hll"

Parameters:
  `str` - String to delete characters from, may be null
  `set` - String[] set of characters to delete, may be null
Returns:
  modified String, `null` if null string input
See Also:
  - `for set-syntax.`

### translate

public static String translate(String str, String searchChars, String replaceChars)
Deprecated.
Use `StringUtils.replaceChars(String, String, String)`. Method will be removed in Commons Lang 3.0. NOTE: StringUtils#replaceChars behaves differently when 'searchChars' is longer than 'replaceChars'. CharSetUtils#translate will use the last char of the replacement string whereas StringUtils#replaceChars will delete

Translate characters in a String. This is a multi character search and replace routine.

An example is:

- translate("hello", "ho", "jy") => jelly

If the length of characters to search for is greater than the length of characters to replace, then the last character is used.

     CharSetUtils.translate(null, *, *) = null
     CharSetUtils.translate("", *, *)   = ""

Parameters:
  `str` - String to replace characters in, may be null
  `searchChars` - a set of characters to search for, must not be null
  `replaceChars` - a set of characters to replace, must not be null or empty ("")
Returns:
  translated String, `null` if null string input
Throws:
  `NullPointerException` - if `searchChars` or `replaceChars` is `null`
  `ArrayIndexOutOfBoundsException` - if `replaceChars` is empty ("")