# 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

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static final class`
`StringMatcher.Position`
Start and end positions of a shortest match found by `find(String, int, int)`.

## Constructor Summary

Constructors
Constructor
Description
`StringMatcher(String pattern, boolean ignoreCase, boolean ignoreWildCards)`
StringMatcher constructor takes in a String object that is a simple pattern.

## Method Summary

Modifier and Type
Method
Description
`StringMatcher.Position`
`find(String text, int start, int end)`
Finds the first occurrence of the pattern between `start` (inclusive) and `end` (exclusive).
`static String[]`
`getWords(String text)`
Splits a given text into words.
`boolean`
`match(String text)`
Determines whether the given `text` matches the pattern.
`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.
`boolean`
`matchWords(String text)`
Similar to `match(String)`, this methods matches a pattern that may contain the wildcards '?'
`String`
`toString()`
`void`
`usePrefixMatch()`
Configures this `StringMatcher` to also match on prefix-only matches.

### Methods inherited from class Object

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

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