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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `TextMatcher.Method`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TextMatcher()`
  Creates a basic matcher.
  `TextMatcher(TextMatcher textMatcher)`
  Copy constructor.
  `TextMatcher(TextMatcher.Method method)`
  Creates a matcher with the specified method.
  `TextMatcher(String pattern)`
  Creates a basic matcher with the given pattern.
  `TextMatcher(String pattern, TextMatcher.Method method)`
  Creates a basic matcher with the given pattern.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `anyMatches(List<TextMatcher> matchers, CharSequence text)`
  Tests that at least one matcher matches the provided text.
  `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`).
  `String`
  `apply(String text, String replacement)`
  Replaces this class matching text with replacement value.
  `static TextMatcher`
  `basic(String pattern)`
  Creates a new text matcher initialized with basic matching.
  `protected boolean`
  `canEqual(Object other)`
  `void`
  `copyFrom(TextMatcher tm)`
  `void`
  `copyTo(TextMatcher tm)`
  `static TextMatcher`
  `csv(String pattern)`
  Creates a new text matcher initialized with comma-separated-value matching.
  `boolean`
  `equals(Object o)`
  `TextMatcher.Method`
  `getMethod()`
  `String`
  `getPattern()`
  `int`
  `hashCode()`
  `TextMatcher`
  `ignoreCase()`
  `TextMatcher`
  `ignoreDiacritic()`
  `boolean`
  `isIgnoreCase()`
  `boolean`
  `isIgnoreDiacritic()`
  `boolean`
  `isMatchEmpty()`
  Gets whether `null` or empty strings should be considered a positive match.
  `boolean`
  `isNegateMatches()`
  Whether to negates the result of invoking `matches(CharSequence)`.
  `boolean`
  `isPartial()`
  `boolean`
  `isReplaceAll()`
  `boolean`
  `isSet()`
  Checks whether this text matcher was given a pattern.
  `boolean`
  `isTrim()`
  Gets whether values should be trimmed before being evaluated (as per `String.trim()`).
  `TextMatcher`
  `matchEmpty()`
  Sets that `null` or empty strings should be considered a positive match.
  `boolean`
  `matches(CharSequence text)`
  Matches this class pattern against its text.
  `TextMatcher`
  `negateMatches()`
  Sets the negation of the result of invoking `matches(CharSequence)` to `true`.
  `TextMatcher`
  `partial()`
  `static TextMatcher`
  `regex(String pattern)`
  Creates a new text matcher initialized with regular expression matching.
  `String`
  `replace(String text, String replacement)`
  Replaces this class matching text with replacement value.
  `TextMatcher`
  `replaceAll()`
  `TextMatcher`
  `setIgnoreCase(boolean ignoreCase)`
  `TextMatcher`
  `setIgnoreDiacritic(boolean ignoreDiacritic)`
  `TextMatcher`
  `setMatchEmpty(boolean matchEmpty)`
  Sets whether `null` or empty strings should be considered a positive match.
  `TextMatcher`
  `setMethod(TextMatcher.Method method)`
  `TextMatcher`
  `setNegateMatches(boolean negateMatches)`
  Sets whether to negates the result of invoking `matches(CharSequence)`.
  `TextMatcher`
  `setPartial(boolean partial)`
  `TextMatcher`
  `setPattern(String pattern)`
  `TextMatcher`
  `setReplaceAll(boolean replaceAll)`
  `TextMatcher`
  `setTrim(boolean trim)`
  Sets whether values should be trimmed before being evaluated (as per `String.trim()`).
  `boolean`
  `test(CharSequence text)`
  Matches this class pattern against its text.
  `Matcher`
  `toRegexMatcher(CharSequence text)`
  Converts this text matcher to a pattern `Matcher`.
  `Pattern`
  `toRegexPattern()`
  Compiles this text matcher to create a regular expression `Pattern`.
  `String`
  `toString()`
  `TextMatcher`
  `trim()`
  Sets that values should be trimmed before being evaluated (as per `String.trim()`).
  `static TextMatcher`
  `wildcard(String pattern)`
  Creates a new text matcher initialized with wildcard matching.
  `TextMatcher`
  `withIgnoreCase(boolean ignoreCase)`
  `TextMatcher`
  `withIgnoreDiacritic(boolean ignoreDiacritic)`
  `TextMatcher`
  `withMatchEmpty(boolean matchEmpty)`
  Sets whether `null` or empty strings should be considered a positive match.
  `TextMatcher`
  `withMethod(TextMatcher.Method method)`
  `TextMatcher`
  `withNegateMatches(boolean negateMatches)`
  Sets whether to negates the result of invoking `matches(CharSequence)` on a copy of this instance.
  `TextMatcher`
  `withPartial(boolean partial)`
  `TextMatcher`
  `withPattern(String pattern)`
  `TextMatcher`
  `withReplaceAll(boolean replaceAll)`
  `TextMatcher`
  `withTrim(boolean trim)`
  Sets whether values should be trimmed before being evaluated (as per `String.trim()`).

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.util.function.BiFunction

  `andThen`

  ### Methods inherited from interface java.util.function.Predicate

  `and, negate, or`

- ## 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`