In this quick tutorial we’ll explore the CharMatcher utility class in Guava.

1. Remove Special Characters from a String

Let’s start by removing all special characters from a String.

In the following example, we remove all characters that aren’t digit or letter using retainFrom():

public void whenRemoveSpecialCharacters_thenRemoved(){
    String input = "H*el.lo,}12";
    CharMatcher matcher = CharMatcher.javaLetterOrDigit();
    String result = matcher.retainFrom(input);

    assertEquals("Hello12", result);

2. Remove Non ASCII Characters From String

We can also use CharMatcher to remove non ASCII characters from a String as in the following example:

public void whenRemoveNonASCIIChars_thenRemoved() {
    String input = "あhello₤";

    String result = CharMatcher.ascii().retainFrom(input);
    assertEquals("hello", result);

    result = CharMatcher.inRange('0', 'z').retainFrom(input);
    assertEquals("hello", result);

3. Remove Characters Not in the Charset

Now – let’s see how to remove Characters that don’t belong to a given Charset. In the following example – we’ll remove characters that don’t belong to the “cp437” Charset:

public void whenRemoveCharsNotInCharset_thenRemoved() {
    Charset charset = Charset.forName("cp437");
    CharsetEncoder encoder = charset.newEncoder();

    Predicate<Character> inRange = new Predicate<Character>() {
        public boolean apply(Character c) {
            return encoder.canEncode(c);

    String result = CharMatcher.forPredicate(inRange)
    assertEquals("hello", result);

Note: We used CharsetEncoder to create a Predicate that check if the given Character can be encoded to the given Charset.

4. Validate String

Next – let’s see how to validate a String using CharMatcher.

We can use matchesAllOf() to check if all characters match a condition. And we can make use of matchesNoneOf() to check if a condition doesn’t apply on any of the String characters.

In the following example, we check if our String is lowercase, contains at least one ‘e‘ character and doesn’t contain any digits:

public void whenValidateString_thenValid(){
    String input = "hello";

    boolean result = CharMatcher.javaLowerCase().matchesAllOf(input);

    result ='e').matchesAnyOf(input);

    result = CharMatcher.javaDigit().matchesNoneOf(input);

5. Trim String

Now – let’s see how trim a String using CharMatcher.

In the following example, we use trimLeading(), trimTrailing and trimFrom() to trim our String:

public void whenTrimString_thenTrimmed() {
    String input = "---hello,,,";

    String result ='-').trimLeadingFrom(input);
    assertEquals("hello,,,", result);

    result =',').trimTrailingFrom(input);
    assertEquals("---hello", result);

    result = CharMatcher.anyOf("-,").trimFrom(input);
    assertEquals("hello", result);

6. Collapse a String

Next – let’s see how to collapse a String using CharMatcher.

In the following example, we use collapseFrom() to replace consecutive spaces with ‘‘:

public void whenCollapseFromString_thenCollapsed() {
    String input = "       hel    lo      ";

    String result =' ').collapseFrom(input, '-');
    assertEquals("-hel-lo-", result);

    result =' ').trimAndCollapseFrom(input, '-');
    assertEquals("hel-lo", result);

7. Replace from String

We can use CharMatcher to replace specific characters from a String as in the following example:

public void whenReplaceFromString_thenReplaced() {
    String input = "apple-banana.";

    String result = CharMatcher.anyOf("-.").replaceFrom(input, '!');
    assertEquals("apple!banana!", result);

    result ='-').replaceFrom(input, " and ");
    assertEquals("apple and banana.", result);

8. Count Character Occurrences

Finally – let’s see how to count the occurrences of characters using CharMatcher.

In the following example, we count the commas and characters between ‘a‘:’h‘:

public void whenCountCharInString_thenCorrect() {
    String input = "a, c, z, 1, 2";

    int result =',').countIn(input);
    assertEquals(4, result);

    result = CharMatcher.inRange('a', 'h').countIn(input);
    assertEquals(2, result);

9. Conclusion

In this article we illustrated some of the more useful APIs and real-world usage examples of using Guava for Strings.

The full source code is available over on GitHub.