Package com.norconex.commons.lang.text

Class TextMatcher

java.lang.Object
com.norconex.commons.lang.text.TextMatcher
All Implemented Interfaces:
BiFunction<String,String,String>, BinaryOperator<String>, Predicate<CharSequence>
public class TextMatcher extends Object implements Predicate<CharSequence>, BinaryOperator<String>

A configurable class offering a few different ways to perform text matching and replacing. Supported methods are:

  • BASIC: Default. Text is matched as specified.
  • CSV: Same has having multiple BASIC, separated with commas.
  • WILDCARD: An asterisk (*) matches a series made of any characters. A question mark (?) matches any single character. If you need to escape wildcards, use REGEX instead.
  • REGEX: Matching/replacing is done using Java-style regular expressions.

Match/replace methods are case-sensitive by default.

This class is not thread-safe.

Empty and null values

Since 3.0.0, null or empty strings are not matched by default. To have those considered as positive matches, set matchEmpty to true. To have blank values (containing white spaces only) considered as positive matches, also set trim to true. When matching empties, doing replacement on a null value behaves as if the value is an empty string.

null pattern

Unless otherwise stated by consuming classes, a null expressions will match everything, but replace nothing. when invoking matches(CharSequence) or replace(String, String).

Since:
2.0.0

  • Constructor Details

    • TextMatcher

      public TextMatcher()
      Creates a basic matcher.

    • TextMatcher

      public TextMatcher(String pattern)
      Creates a basic matcher with the given pattern. Default behavior will match the pattern exactly.
      Parameters:
      pattern - expression used for matching

    • TextMatcher

      public TextMatcher(TextMatcher.Method method)
      Creates a matcher with the specified method.
      Parameters:
      method - matching method

    • TextMatcher

      public TextMatcher(String pattern, TextMatcher.Method method)
      Creates a basic matcher with the given pattern.
      Parameters:
      pattern - expression used for matching
      method - matching method

    • TextMatcher

      public TextMatcher(TextMatcher textMatcher)
      Copy constructor. Supplying null is the same as evoking the empty constructor.
      Parameters:
      textMatcher - instance to copy

  • Method Details

    • getMethod

      public TextMatcher.Method getMethod()

    • setMethod

      public TextMatcher setMethod(TextMatcher.Method method)

    • withMethod

      public TextMatcher withMethod(TextMatcher.Method method)

    • isPartial

      public boolean isPartial()

    • setPartial

      public TextMatcher setPartial(boolean partial)

    • partial

      public TextMatcher partial()

    • withPartial

      public TextMatcher withPartial(boolean partial)

    • getPattern

      public String getPattern()

    • setPattern

      public TextMatcher setPattern(String pattern)

    • withPattern

      public TextMatcher withPattern(String pattern)

    • isIgnoreCase

      public boolean isIgnoreCase()

    • setIgnoreCase

      public TextMatcher setIgnoreCase(boolean ignoreCase)

    • ignoreCase

      public TextMatcher ignoreCase()

    • withIgnoreCase

      public TextMatcher withIgnoreCase(boolean ignoreCase)

    • isIgnoreDiacritic

      public boolean isIgnoreDiacritic()

    • setIgnoreDiacritic

      public TextMatcher setIgnoreDiacritic(boolean ignoreDiacritic)

    • ignoreDiacritic

      public TextMatcher ignoreDiacritic()

    • withIgnoreDiacritic

      public TextMatcher withIgnoreDiacritic(boolean ignoreDiacritic)

    • isReplaceAll

      public boolean isReplaceAll()

    • setReplaceAll

      public TextMatcher setReplaceAll(boolean replaceAll)

    • replaceAll

      public TextMatcher replaceAll()

    • withReplaceAll

      public TextMatcher withReplaceAll(boolean replaceAll)

    • isNegateMatches

      public boolean isNegateMatches()
      Whether to negates the result of invoking matches(CharSequence). Note: only applies to the matches(CharSequence) method.
      Returns:
      true if negating matches.
      Since:
      3.0.0

    • setNegateMatches

      public TextMatcher setNegateMatches(boolean negateMatches)
      Sets whether to negates the result of invoking matches(CharSequence). Note: only applies to the matches(CharSequence) method.
      Parameters:
      negateMatches - true to negate matches
      Returns:
      this
      Since:
      3.0.0

    • negateMatches

      public TextMatcher negateMatches()
      Sets the negation of the result of invoking matches(CharSequence) to true. Same as invoking setNegateMatches(boolean) with true. Note: only applies to the matches(CharSequence) method.
      Returns:
      this
      Since:
      3.0.0

    • withNegateMatches

      public TextMatcher withNegateMatches(boolean negateMatches)
      Sets whether to negates the result of invoking matches(CharSequence) on a copy of this instance. Note: only applies to the matches(CharSequence) method.
      Parameters:
      negateMatches - true to negate matches
      Returns:
      this
      Since:
      3.0.0

    • isSet

      public boolean isSet()
      Checks whether this text matcher was given a pattern.
      Returns:
      true if a pattern is set (i.e., not null).

    • isMatchEmpty

      public boolean isMatchEmpty()
      Gets whether null or empty strings should be considered a positive match.
      Returns:
      true if null and empty strings are considered a match
      Since:
      3.0.0

    • setMatchEmpty

      public TextMatcher setMatchEmpty(boolean matchEmpty)
      Sets whether null or empty strings should be considered a positive match. To also consider blank values as positive matches, use setTrim(boolean).
      Parameters:
      matchEmpty - true to have null and empty strings are considered a match.
      Returns:
      this instance
      Since:
      3.0.0

    • matchEmpty

      public TextMatcher matchEmpty()
      Sets that null or empty strings should be considered a positive match. Same as invoking setMatchEmpty(boolean) with true.
      Returns:
      this instance
      Since:
      3.0.0

    • withMatchEmpty

      public TextMatcher withMatchEmpty(boolean matchEmpty)
      Sets whether null or empty strings should be considered a positive match. To also consider blank values as positive matches, use setTrim(boolean).
      Parameters:
      matchEmpty - true to have null and empty strings are considered a match.
      Returns:
      a copy of this instance, leaving this instance unchanged
      Since:
      3.0.0

    • isTrim

      public boolean isTrim()
      Gets whether values should be trimmed before being evaluated (as per String.trim()).
      Returns:
      true if values are trimmed before evaluation
      Since:
      3.0.0

    • setTrim

      public TextMatcher setTrim(boolean trim)
      Sets whether values should be trimmed before being evaluated (as per String.trim()).
      Parameters:
      trim - true to trim values before evaluation
      Returns:
      this instance
      Since:
      3.0.0

    • trim

      public TextMatcher trim()
      Sets that values should be trimmed before being evaluated (as per String.trim()). Same as invoking setTrim(boolean) with true.
      Returns:
      this instance
      Since:
      3.0.0

    • withTrim

      public TextMatcher withTrim(boolean trim)
      Sets whether values should be trimmed before being evaluated (as per String.trim()).
      Parameters:
      trim - true to trim values before evaluation
      Returns:
      a copy of this instance, leaving this instance unchanged
      Since:
      3.0.0

    • copyTo

      public void copyTo(TextMatcher tm)

    • copyFrom

      public void copyFrom(TextMatcher tm)

    • basic

      public static TextMatcher basic(String pattern)

      Creates a new text matcher initialized with basic matching. Same as invoking new TextMatcher(Method.BASIC).setPattern(pattern).

      Parameters:
      pattern - expression to match against values
      Returns:
      basic text matcher

    • csv

      public static TextMatcher csv(String pattern)

      Creates a new text matcher initialized with comma-separated-value matching. Same as invoking new TextMatcher(Method.CSV).setPattern(pattern).

      Parameters:
      pattern - expression to match against values
      Returns:
      csv text matcher

    • wildcard

      public static TextMatcher wildcard(String pattern)

      Creates a new text matcher initialized with wildcard matching. Same as invoking new TextMatcher(Method.WILDCARD).setPattern(pattern).

      Parameters:
      pattern - expression to match against values
      Returns:
      wildcard text matcher

    • regex

      public static TextMatcher regex(String pattern)

      Creates a new text matcher initialized with regular expression matching. Same as invoking new TextMatcher(Method.REGEX).setPattern(pattern).

      Parameters:
      pattern - expression to match against values
      Returns:
      regex text matcher

    • test

      public boolean test(CharSequence text)
      Matches this class pattern against its text. For compatibility with Predicate. Same as invoking matches(CharSequence).
      Specified by:
      test in interface Predicate<CharSequence>
      Parameters:
      text - text to match
      Returns:
      true if matching

    • matches

      public boolean matches(CharSequence text)
      Matches this class pattern against its text. A null pattern will match all.
      Parameters:
      text - text to match
      Returns:
      true if matching

    • apply

      public String apply(String text, String replacement)
      Replaces this class matching text with replacement value. For compatibility with BinaryOperator. Same as invoking replace(String, String).
      Specified by:
      apply in interface BiFunction<String,String,String>
      Parameters:
      text - text to match
      replacement - text replacement
      Returns:
      replaced text

    • replace

      public String replace(String text, String replacement)
      Replaces this class matching text with replacement value.
      Parameters:
      text - text to match
      replacement - text replacement
      Returns:
      replaced text

    • toRegexMatcher

      public Matcher toRegexMatcher(CharSequence text)
      Converts this text matcher to a pattern Matcher.
      Parameters:
      text - text to match using this text matcher method
      Returns:
      matcher

    • toRegexPattern

      public Pattern toRegexPattern()
      Compiles this text matcher to create a regular expression Pattern.
      Returns:
      pattern

    • anyMatchesOrEmpty

      public static boolean anyMatchesOrEmpty(List<TextMatcher> matchers, CharSequence text)
      Tests that at least one matcher matches the provided text, treating an empty or null list as a match (returning true).
      Parameters:
      matchers - matchers to test against supplied text
      text - the text being tested
      Returns:
      true if an empty list or at least one matcher matches the text
      Since:
      3.0.0

    • anyMatches

      public static boolean anyMatches(List<TextMatcher> matchers, CharSequence text)
      Tests that at least one matcher matches the provided text. If matchers is empty or null, it is considered not to match (returns false).
      Parameters:
      matchers - matchers to test against supplied text
      text - the text being tested
      Returns:
      true if at least one matcher matches the text
      Since:
      3.0.0

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • canEqual

      protected boolean canEqual(Object other)

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object