Package org.eclipse.core.text

Class StringMatcher

java.lang.Object
org.eclipse.core.text.StringMatcher
public final class StringMatcher extends Object
A string pattern matcher. Supports '*' and '?' wildcards.
Since:
3.12

  • Constructor Details

    • StringMatcher

      public StringMatcher(String pattern, boolean ignoreCase, boolean ignoreWildCards)
      StringMatcher constructor takes in a String object that is a simple pattern. The pattern may contain '*' for 0 and many characters and '?' for exactly one character.

      Literal '*' and '?' characters must be escaped in the pattern e.g., "\*" means literal "*", etc.

      The escape character '\' is an escape only if followed by '*', '?', or '\'. All other occurrences are taken literally.

      If invoking the StringMatcher with string literals in Java, don't forget escape characters are represented by "\\".

      An empty pattern matches only an empty text, unless usePrefixMatch() is used, in which case it always matches.

      Parameters:
      pattern - the pattern to match text against, must not be null
      ignoreCase - if true, case is ignored
      ignoreWildCards - if true, wild cards and their escape sequences are ignored (everything is taken literally).
      Throws:
      IllegalArgumentException - if pattern == null

  • Method Details

    • usePrefixMatch

      public void usePrefixMatch()
      Configures this StringMatcher to also match on prefix-only matches.

      If the matcher was created with ignoreWildCards == true, any wildcard characters in the pattern will still be matched literally.

      If the pattern is empty, it will match any text.

      Since:
      3.13

    • find

      public StringMatcher.Position find(String text, int start, int end)
      Finds the first occurrence of the pattern between start (inclusive) and end (exclusive).

      If wildcards are enabled: If the pattern contains only '*' wildcards a full match is reported, otherwise leading and trailing '*' wildcards are ignored. If the pattern contains interior '*' wildcards, the first shortest match is returned.

      Parameters:
      text - the String object to search in; must not be null
      start - the starting index of the search range, inclusive
      end - the ending index of the search range, exclusive
      Returns:
      a StringMatcher.Position object for the match found, or null if there's no match or the text range to search is empty (end <= start). If the pattern is empty, the position will describe a null-match in the text at start (getStart() == getEnd() == start).
      Note: for patterns like "*abc*" with leading and trailing stars, the position of "abc" is returned. For a pattern like"*??*" in text "abcdf", (0,2) is returned. Interior '*'s yield the shortest match: for pattern "a*b" and text "axbyb", (0,3) is returned, not (0,5).
      Throws:
      IllegalArgumentException - if text == null

    • match

      public boolean match(String text)
      Determines whether the given text matches the pattern.
      Parameters:
      text - String to match; must not be null
      Returns:
      true if the whole text matches the pattern; false otherwise
      Throws:
      IllegalArgumentException - if text == null

    • match

      public boolean match(String text, int start, int end)
      Determines whether the given sub-string of text from start (inclusive) to end (exclusive) matches the pattern.
      Parameters:
      text - String to match in; must not be null
      start - start index (inclusive) within text of the sub-string to match
      end - end index (exclusive) within text of the sub-string to match
      Returns:
      true if the given slice of text matches the pattern; false otherwise
      Throws:
      IllegalArgumentException - if text == null

    • matchWords

      public boolean matchWords(String text)
      Similar to match(String), this methods matches a pattern that may contain the wildcards '?' or '*' against a text. However, the matching is not only done on the full text, but also on individual words from the text, and if the pattern contains whitespace, the pattern is split into sub-patterns and those are matched, too.

      The precise rules are:

      • If the full pattern matches the full text, the match succeeds.
      • If the full pattern matches a single word of the text, the match succeeds.
      • If all sub-patterns match a prefix of the whole text or any prefix of any word, the match succeeds.
      • Otherwise, the match fails.

      An empty pattern matches only the empty text.

      Since:
      3.20

    • getWords

      public static String[] getWords(String text)
      Splits a given text into words.
      Parameters:
      text - to split
      Returns:
      the words of the text
      Since:
      3.20

    • toString

      public String toString()
      Overrides:
      toString in class Object