org.fife.ui.rtextarea

## Class SearchEngine

- java.lang.Object
- - org.fife.ui.rtextarea.SearchEngine

    public class SearchEngine
    extends Object

A singleton class that can perform advanced find/replace operations in an `RTextArea`. Simply create a `SearchContext` and call one of the following methods:

- `find(JTextArea, SearchContext)`
- `replace(RTextArea, SearchContext)`
- `replaceAll(RTextArea, SearchContext)`

Version:
  1.0
Author:
  Robert Futrell
See Also:
  `SearchContext`

### Method Summary

Methods
`static boolean` `find(JTextArea textArea, SearchContext context)` Finds the next instance of the string/regular expression specified from the caret position.
`static int` `getNextMatchPos(String searchFor, String searchIn, boolean forward, boolean matchCase, boolean wholeWord)` Searches `searchIn` for an occurrence of `searchFor` either forwards or backwards, matching case or not.
`static String` `getReplacementText(Matcher m, CharSequence template)` Called internally by `getMatches()`.
`static boolean` `replace(RTextArea textArea, SearchContext context)` Finds the next instance of the text/regular expression specified from the caret position.
`static int` `replaceAll(RTextArea textArea, SearchContext context)` Replaces all instances of the text/regular expression specified in the specified document with the specified replacement.

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

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

### Method Detail

#### find

    public static boolean find(JTextArea textArea,
               SearchContext context)

Finds the next instance of the string/regular expression specified from the caret position. If a match is found, it is selected in this text area.

Parameters:
  `textArea` - The text area in which to search.
  `context` - What to search for and all search options.
Returns:
  Whether a match was found (and thus selected).
Throws:
  `PatternSyntaxException` - If this is a regular expression search but the search text is an invalid regular expression.
See Also:
  `replace(RTextArea, SearchContext)`, `replaceAll(RTextArea, SearchContext)`

#### getNextMatchPos

    public static final int getNextMatchPos(String searchFor,
                      String searchIn,
                      boolean forward,
                      boolean matchCase,
                      boolean wholeWord)

Searches `searchIn` for an occurrence of `searchFor` either forwards or backwards, matching case or not.

Most clients will have no need to call this method directly.

Parameters:
  `searchFor` - The string to look for.
  `searchIn` - The string to search in.
  `forward` - Whether to search forward or backward in `searchIn`.
  `matchCase` - If `true`, do a case-sensitive search for `searchFor`.
  `wholeWord` - If `true`, `searchFor` occurrences embedded in longer words in `searchIn` don't count as matches.
Returns:
  The starting position of a match, or `-1` if no match was found.

#### getReplacementText

    public static String getReplacementText(Matcher m,
                            CharSequence template)

Called internally by `getMatches()`. This method assumes that the specified matcher has just found a match, and that you want to get the string with which to replace that match.

Escapes simply insert the escaped character, except for `\n` and `\t`, which insert a newline and tab respectively. Substrings of the form `$\d+` are considered to be matched groups. To include a literal dollar sign in your template, escape it (i.e. `\$`).

Most clients will have no need to call this method directly.

Parameters:
  `m` - The matcher.
  `template` - The template for the replacement string. For example, "`foo`" would yield the replacement string "`foo`", while "`$1 is the greatest`" would yield different values depending on the value of the first captured group in the match.
Returns:
  The string to replace the match with.
Throws:
  `IndexOutOfBoundsException` - If `template` references an invalid group (less than zero or greater than the number of groups matched).

#### replace

    public static boolean replace(RTextArea textArea,
                  SearchContext context)
                           throws PatternSyntaxException

Finds the next instance of the text/regular expression specified from the caret position. If a match is found, it is replaced with the specified replacement string.

Parameters:
  `textArea` - The text area in which to search.
  `context` - What to search for and all search options.
Returns:
  Whether a match was found (and thus replaced).
Throws:
  `PatternSyntaxException` - If this is a regular expression search but the search text is an invalid regular expression.
  `IndexOutOfBoundsException` - If this is a regular expression search but the replacement text references an invalid group (less than zero or greater than the number of groups matched).
See Also:
  `replaceAll(RTextArea, SearchContext)`, `find(JTextArea, SearchContext)`

#### replaceAll

    public static int replaceAll(RTextArea textArea,
                 SearchContext context)
                          throws PatternSyntaxException

Replaces all instances of the text/regular expression specified in the specified document with the specified replacement.

Parameters:
  `textArea` - The text area in which to search.
  `context` - What to search for and all search options.
Returns:
  The number of replacements done.
Throws:
  `PatternSyntaxException` - If this is a regular expression search but the replacement text is an invalid regular expression.
  `IndexOutOfBoundsException` - If this is a regular expression search but the replacement text references an invalid group (less than zero or greater than the number of groups matched).
See Also:
  `replace(RTextArea, SearchContext)`, `find(JTextArea, SearchContext)`