SearchEngine
Date: 2017-02-11

org.fife.ui.rtextarea

## Class SearchEngine

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

-     public class SearchEngine
      extends java.lang.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)`
  - `markAll(RTextArea, SearchContext)`
  See Also:
    `SearchContext`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static SearchResult` | `find(javax.swing.JTextArea textArea, SearchContext context)` Finds the next instance of the string/regular expression specified from the caret position.
    `static int` | `getNextMatchPos(java.lang.String searchFor, java.lang.String searchIn, boolean forward, boolean matchCase, boolean wholeWord)` Searches `searchIn` for an occurrence of `searchFor` either forwards or backwards, matching case or not.
    `static java.lang.String` | `getReplacementText(java.util.regex.Matcher m, java.lang.CharSequence template)` Called internally by `getMatches()`.
    `static SearchResult` | `markAll(RTextArea textArea, SearchContext context)` Marks all instances of the specified text in this text area.
    `static SearchResult` | `replace(RTextArea textArea, SearchContext context)` Finds the next instance of the text/regular expression specified from the caret position.
    `static SearchResult` | `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 SearchResult find(javax.swing.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:
        The result of the operation.
      Throws:
        `java.util.regex.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(java.lang.String searchFor,
                            java.lang.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 java.lang.String getReplacementText(java.util.regex.Matcher m,
                                            java.lang.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:
        `java.lang.IndexOutOfBoundsException` - If `template` references an invalid group (less than zero or greater than the number of groups matched).

    - #### markAll

          public static final SearchResult markAll(RTextArea textArea,
                             SearchContext context)

      Marks all instances of the specified text in this text area. This method is typically only called directly in response to search events of type `SearchEvent.Type.MARK_ALL`. "Mark all" behavior is automatically performed when `find(JTextArea, SearchContext)` or `replace(RTextArea, SearchContext)` is called.
      Parameters:
        `textArea` - The text area in which to mark occurrences.
        `context` - The search context specifying the text to search for. It is assumed that `context.getMarkAll()` has already been checked and returns `true`.
      Returns:
        The results of the operation.

    - #### replace

          public static SearchResult replace(RTextArea textArea,
                             SearchContext context)
                                      throws java.util.regex.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:
        The result of the operation.
      Throws:
        `java.util.regex.PatternSyntaxException` - If this is a regular expression search but the search text is an invalid regular expression.
        `java.lang.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 SearchResult replaceAll(RTextArea textArea,
                                SearchContext context)
                                         throws java.util.regex.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 result of the operation.
      Throws:
        `java.util.regex.PatternSyntaxException` - If this is a regular expression search but the replacement text is an invalid regular expression.
        `java.lang.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)`