Guava: Google Core Libraries for Java 33.1.0-jre · com.google.common.base.CharMatcher

Determines a true or false value for any Java char value, just as Predicate does for any Object. Also offers basic text processing methods based on this function. Implementations are strongly encouraged to be side-effect-free and immutable.

Throughout the documentation of this class, the phrase "matching character" is used to mean "any char value c for which this.matches(c) returns true".

Warning

This class deals only with char values, that is, BMP characters. It does not understand supplementary Unicode code points in the range 0x10000 to 0x10FFFF which includes the majority of assigned characters, including important CJK characters and emoji.

Supplementary characters are encoded into a String using surrogate pairs, and a CharMatcher treats these just as two separate characters. countIn counts each supplementary character as 2 chars.

For up-to-date Unicode character properties (digit, letter, etc.) and support for supplementary code points, use ICU4J UCharacter and UnicodeSet (freeze() after building). For basic text processing based on UnicodeSet use the ICU4J UnicodeSetSpanner.

Example usages:

  String trimmed = whitespace().trimFrom(userInput);
  if (ascii().matchesAllOf(s)) { ... }

See the Guava User Guide article on CharMatcher .

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	CharMatcher.And Implementation of `and(CharMatcher)`.
private static class	CharMatcher.Any Implementation of `any()`.
private static class	CharMatcher.AnyOf Implementation of `anyOf(CharSequence)` for three or more characters.
private static class	CharMatcher.Ascii Implementation of `ascii()`.
private static class	CharMatcher.BitSetMatcher Fast matcher using a `BitSet` table of matching characters.
private static class	CharMatcher.BreakingWhitespace Implementation of `breakingWhitespace()`.
private static class	CharMatcher.Digit Implementation of `digit()`.
pack-priv abstract static class	CharMatcher.FastMatcher A matcher for which precomputation will not yield any significant benefit.
private static class	CharMatcher.ForPredicate Implementation of `forPredicate(Predicate)`.
private static class	CharMatcher.InRange Implementation of `inRange(char, char)`.
private static class	CharMatcher.Invisible Implementation of `invisible()`.
private static class	CharMatcher.Is Implementation of `is(char)`.
private static class	CharMatcher.IsEither Implementation of `anyOf(CharSequence)` for exactly two characters.
private static class	CharMatcher.IsNot Implementation of `isNot(char)`.
private static class	CharMatcher.JavaDigit Implementation of `javaDigit()`.
private static class	CharMatcher.JavaIsoControl Implementation of `javaIsoControl()`.
private static class	CharMatcher.JavaLetter Implementation of `javaLetter()`.
private static class	CharMatcher.JavaLetterOrDigit Implementation of `javaLetterOrDigit()`.
private static class	CharMatcher.JavaLowerCase Implementation of `javaLowerCase()`.
private static class	CharMatcher.JavaUpperCase Implementation of `javaUpperCase()`.
pack-priv abstract static class	CharMatcher.NamedFastMatcher `FastMatcher` which overrides `toString()` with a custom name.
private static class	CharMatcher.Negated Implementation of `negate()`.
private static class	CharMatcher.NegatedFastMatcher Negation of a `FastMatcher`.
private static class	CharMatcher.None Implementation of `none()`.
private static class	CharMatcher.Or Implementation of `or(CharMatcher)`.
private static class	CharMatcher.RangesMatcher Implementation that matches characters that fall within multiple ranges.
private static class	CharMatcher.SingleWidth Implementation of `singleWidth()`.
pack-priv static class	CharMatcher.Whitespace Implementation of `whitespace()`.

Field Summary

Modifier and Type	Field and Description
private static final int	DISTINCT_CHARS

Constructor Summary

Access	Constructor and Description
protected	CharMatcher() Constructor for use by subclasses.

Method Summary

Modifier and Type	Method and Description
public CharMatcher	and(CharMatcher other) Returns a matcher that matches any character matched by both this matcher and `other`.
public static CharMatcher	any() Matches any character.
public static CharMatcher	anyOf(final CharSequence sequence) Returns a `char` matcher that matches any BMP character present in the given character sequence.
public boolean	apply(Character character) Implements com.google.common.base.Predicate.apply. Deprecated Provided only to satisfy the `Predicate` interface; use `matches` instead. Returns the result of applying this predicate to `input` (Java 8+ users, see notes in the class documentation above).
public static CharMatcher	ascii() Determines whether a character is ASCII, meaning that its code point is less than 128.
public static CharMatcher	breakingWhitespace() Determines whether a character is a breaking whitespace (that is, a whitespace which can be interpreted as a break between words for formatting purposes).
public String	Returns: the new string collapseFrom(CharSequence the character sequence to replace matching groups of characters in sequence, char the character to append to the result string in place of each group of matching characters in `sequence` replacement) Returns a string copy of the input character sequence, with each group of consecutive matching BMP characters replaced by a single replacement character.
public int	countIn(CharSequence sequence) Returns the number of matching `char`s found in a character sequence.
public static CharMatcher	digit() Deprecated Many digits are supplementary characters; see the class documentation. Determines whether a character is a BMP digit according to Unicode.
private String	finishCollapseFrom(CharSequence sequence, int start, int end, char replacement, StringBuilder builder, boolean inMatchingGroup)
public static CharMatcher	forPredicate(final Predicate<? super Character> predicate) Returns a matcher with identical behavior to the given `Character`-based predicate, but which operates on primitive `char` instances instead.
public int	Returns: an index, or `-1` if no character matches indexIn(CharSequence the character sequence to examine from the beginning sequence) Returns the index of the first matching BMP character in a character sequence, or `-1` if no matching character is present.
public int	Returns: the index of the first matching character, guaranteed to be no less than `start`, or `-1` if no character matches indexIn(CharSequence the character sequence to examine sequence, int the first index to examine; must be nonnegative and no greater than `sequence.length()` start) Returns the index of the first matching BMP character in a character sequence, starting from a given position, or `-1` if no character matches after that position.
public static CharMatcher	inRange(final char startInclusive, final char endInclusive) Returns a `char` matcher that matches any character in a given BMP range (both endpoints are inclusive).
public static CharMatcher	invisible() Deprecated Most invisible characters are supplementary characters; see the class documentation. Determines whether a character is invisible; that is, if its Unicode category is any of SPACE_SEPARATOR, LINE_SEPARATOR, PARAGRAPH_SEPARATOR, CONTROL, FORMAT, SURROGATE, and PRIVATE_USE according to ICU4J.
public static CharMatcher	is(final char match) Returns a `char` matcher that matches only one specified BMP character.
private static CharMatcher.IsEither	isEither(char c1, char c2)
public static CharMatcher	isNot(final char match) Returns a `char` matcher that matches any character except the BMP character specified.
private static boolean	isSmall(int totalCharacters, int tableLength)
public static CharMatcher	javaDigit() Deprecated Many digits are supplementary characters; see the class documentation. Determines whether a character is a BMP digit according to Java's definition.
public static CharMatcher	javaIsoControl() Determines whether a character is an ISO control character as specified by `Character#isISOControl(char)`.
public static CharMatcher	javaLetter() Deprecated Most letters are supplementary characters; see the class documentation. Determines whether a character is a BMP letter according to Java's definition.
public static CharMatcher	javaLetterOrDigit() Deprecated Most letters and digits are supplementary characters; see the class documentation. Determines whether a character is a BMP letter or digit according to Java's definition.
public static CharMatcher	javaLowerCase() Deprecated Some lowercase characters are supplementary characters; see the class documentation. Determines whether a BMP character is lower case according to Java's definition.
public static CharMatcher	javaUpperCase() Deprecated Some uppercase characters are supplementary characters; see the class documentation. Determines whether a BMP character is upper case according to Java's definition.
public int	Returns: an index, or `-1` if no character matches lastIndexIn(CharSequence the character sequence to examine from the end sequence) Returns the index of the last matching BMP character in a character sequence, or `-1` if no matching character is present.
public abstract boolean	matches(char c) Determines a true or false value for the given character.
public boolean	Returns: `true` if this matcher matches every character in the sequence, including when the sequence is empty matchesAllOf(CharSequence the character sequence to examine, possibly empty sequence) Returns `true` if a character sequence contains only matching BMP characters.
public boolean	Returns: `true` if this matcher matches at least one character in the sequence matchesAnyOf(CharSequence the character sequence to examine, possibly empty sequence) Returns `true` if a character sequence contains at least one matching BMP character.
public boolean	Returns: `true` if this matcher matches no characters in the sequence, including when the sequence is empty matchesNoneOf(CharSequence the character sequence to examine, possibly empty sequence) Returns `true` if a character sequence contains no matching BMP characters.
public CharMatcher	negate() Overrides default java.util.function.Predicate.negate. Returns a matcher that matches any character not matched by this matcher.
public static CharMatcher	none() Matches no characters.
public static CharMatcher	noneOf(CharSequence sequence) Returns a `char` matcher that matches any BMP character not present in the given character sequence.
public CharMatcher	or(CharMatcher other) Returns a matcher that matches any character matched by either this matcher or `other`.
public CharMatcher	precomputed() Returns a `char` matcher functionally equivalent to this one, but which may be faster to query than the original; your mileage may vary.
pack-priv CharMatcher	precomputedInternal() This is the actual implementation of `precomputed`, but we bounce calls through a method on `Platform` so that we can have different behavior in GWT.
private static CharMatcher	precomputedPositive(int totalCharacters, BitSet table, String description) Helper method for `precomputedInternal` that doesn't test if the negation is cheaper.
public String	removeFrom(CharSequence sequence) Returns a string containing all non-matching characters of a character sequence, in order.
public String	Returns: the new string replaceFrom(CharSequence the character sequence to replace matching characters in sequence, char the character to append to the result string in place of each matching character in `sequence` replacement) Returns a string copy of the input character sequence, with each matching BMP character replaced by a given replacement character.
public String	Returns: the new string replaceFrom(CharSequence the character sequence to replace matching characters in sequence, CharSequence the characters to append to the result string in place of each matching character in `sequence` replacement) Returns a string copy of the input character sequence, with each matching BMP character replaced by a given replacement sequence.
public String	retainFrom(CharSequence sequence) Returns a string containing all matching BMP characters of a character sequence, in order.
pack-priv void	setBits(BitSet table) Sets bits in `table` matched by this matcher.
private static String	showCharacter(char c) Returns the Java Unicode escape sequence for the given `char`, in the form "ካ" where "12AB" is the four hexadecimal digits representing the 16-bit code unit.
public static CharMatcher	singleWidth() Deprecated Many such characters are supplementary characters; see the class documentation. Determines whether a character is single-width (not double-width).
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of this `CharMatcher`, such as `CharMatcher.or(WHITESPACE, JAVA_DIGIT)`.
public String	trimAndCollapseFrom(CharSequence sequence, char replacement) Collapses groups of matching characters exactly as `collapseFrom` does, except that groups of matching BMP characters at the start or end of the sequence are removed without replacement.
public String	trimFrom(CharSequence sequence) Returns a substring of the input character sequence that omits all matching BMP characters from the beginning and from the end of the string.
public String	trimLeadingFrom(CharSequence sequence) Returns a substring of the input character sequence that omits all matching BMP characters from the beginning of the string.
public String	trimTrailingFrom(CharSequence sequence) Returns a substring of the input character sequence that omits all matching BMP characters from the end of the string.
public static CharMatcher	whitespace() Determines whether a character is whitespace according to the latest Unicode standard, as illustrated here.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait