com.google.gwt.regexp.shared

## Class RegExp

- java.lang.Object
- - com.google.gwt.regexp.shared.RegExp

-     public class RegExp
      extends java.lang.Object

  A class for regular expressions with features like Javascript's RegExp, plus Javascript String's replace and split methods (which can take a RegExp parameter). The pure Java implementation (for server-side use) uses Java's Pattern class, unavailable under GWT. The super-sourced GWT implementation simply calls on to the native Javascript classes.

  There are a few small incompatibilities between the two implementations. Java-specific constructs in the regular expression syntax (e.g. [a-z&&[^bc]], (?<=foo), \A, \Q) work only in the pure Java implementation, not the GWT implementation, and are not rejected by either. Also, the Javascript-specific constructs $` and $' in the replacement expression work only in the GWT implementation, not the pure Java implementation, which rejects them.

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static RegExp` | `compile(java.lang.String pattern)` Creates a regular expression object from a pattern with no flags.
    `static RegExp` | `compile(java.lang.String pattern, java.lang.String flags)` Creates a regular expression object from a pattern using the given flags.
    `MatchResult` | `exec(java.lang.String input)` Applies the regular expression to the given string.
    `boolean` | `getGlobal()` Returns whether the regular expression captures all occurrences of the pattern.
    `boolean` | `getIgnoreCase()` Returns whether the regular expression ignores case.
    `int` | `getLastIndex()` Returns the zero-based position at which to start the next match.
    `boolean` | `getMultiline()` Returns whether '$' and '^' match line returns ('\n' and '\r') in addition to the beginning or end of the string.
    `java.lang.String` | `getSource()` Returns the pattern string of the regular expression.
    `static java.lang.String` | `quote(java.lang.String input)` Returns a literal pattern `String` for the specified `String`.
    `java.lang.String` | `replace(java.lang.String input, java.lang.String replacement)` Returns the input string with the part(s) matching the regular expression replaced with the replacement string.
    `void` | `setLastIndex(int lastIndex)` Sets the zero-based position at which to start the next match.
    `SplitResult` | `split(java.lang.String input)` Splits the input string around matches of the regular expression.
    `SplitResult` | `split(java.lang.String input, int limit)` Splits the input string around matches of the regular expression.
    `boolean` | `test(java.lang.String input)` Determines if the regular expression matches the given string.

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

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

- - ### Method Detail

    - #### compile

          public static RegExp compile(java.lang.String pattern)

      Creates a regular expression object from a pattern with no flags.
      Parameters:
        `pattern` - the Javascript regular expression pattern to compile
      Returns:
        a new regular expression
      Throws:
        `java.lang.RuntimeException` - if the pattern is invalid

    - #### compile

          public static RegExp compile(java.lang.String pattern,
                                       java.lang.String flags)

      Creates a regular expression object from a pattern using the given flags.
      Parameters:
        `pattern` - the Javascript regular expression pattern to compile
        `flags` - the flags string, containing at most one occurrence of `'g'` (`getGlobal()`), `'i'` (`getIgnoreCase()`), or `'m'` (`getMultiline()`).
      Returns:
        a new regular expression
      Throws:
        `java.lang.RuntimeException` - if the pattern or the flags are invalid

    - #### quote

          public static java.lang.String quote(java.lang.String input)

      Returns a literal pattern `String` for the specified `String`.

      This method produces a `String` that can be used to create a `RegExp` that would match the string `s` as if it were a literal pattern.

      Metacharacters or escape sequences in the input sequence will be given no special meaning.
      Parameters:
        `input` - The string to be literalized
      Returns:
        A literal string replacement

    - #### exec

          public MatchResult exec(java.lang.String input)

      Applies the regular expression to the given string. This call affects the value returned by `getLastIndex()` if the global flag is set.
      Parameters:
        `input` - the string to apply the regular expression to
      Returns:
        a match result if the string matches, else `null`

    - #### getGlobal

          public boolean getGlobal()

      Returns whether the regular expression captures all occurrences of the pattern.

    - #### getIgnoreCase

          public boolean getIgnoreCase()

      Returns whether the regular expression ignores case.

    - #### getLastIndex

          public int getLastIndex()

      Returns the zero-based position at which to start the next match. The return value is not defined if the global flag is not set. After a call to `exec(String)` or `test(String)`, this method returns the next position following the most recent match.
      See Also:
        `getGlobal()`

    - #### getMultiline

          public boolean getMultiline()

      Returns whether '$' and '^' match line returns ('\n' and '\r') in addition to the beginning or end of the string.

    - #### getSource

          public java.lang.String getSource()

      Returns the pattern string of the regular expression.

    - #### replace

          public java.lang.String replace(java.lang.String input,
                                          java.lang.String replacement)

      Returns the input string with the part(s) matching the regular expression replaced with the replacement string. If the global flag is set, replaces all matches of the regular expression. Otherwise, replaces the first match of the regular expression. As per Javascript semantics, backslashes in the replacement string get no special treatment, but the replacement string can use the following special patterns:
      - $1, $2, ... $99 - inserts the n'th group matched by the regular expression.
      - $& - inserts the entire string matched by the regular expression.
      - $$ - inserts a $.
      Note: $` and $' are *not* supported in the pure Java implementation, and throw an exception.
      Parameters:
        `input` - the string in which the regular expression is to be searched.
        `replacement` - the replacement string.
      Returns:
        the input string with the regular expression replaced by the replacement string.
      Throws:
        `java.lang.RuntimeException` - if `replacement` is invalid

    - #### setLastIndex

          public void setLastIndex(int lastIndex)

      Sets the zero-based position at which to start the next match.

    - #### split

          public SplitResult split(java.lang.String input)

      Splits the input string around matches of the regular expression. If the regular expression is completely empty, splits the input string into its constituent characters. If the regular expression is not empty but matches an empty string, the results are not well defined.
      Parameters:
        `input` - the string to be split.
      Returns:
        the strings split off, any of which may be empty.

    - #### split

          public SplitResult split(java.lang.String input,
                                   int limit)

      Splits the input string around matches of the regular expression. If the regular expression is completely empty, splits the input string into its constituent characters. If the regular expression is not empty but matches an empty string, the results are not well defined. Note: There are some browser inconsistencies with this implementation, as it is delegated to the browser, and no browser follows the spec completely. A major difference is that IE will exclude empty strings in the result.
      Parameters:
        `input` - the string to be split.
        `limit` - the maximum number of strings to split off and return, ignoring the rest of the input string. If negative, there is no limit.
      Returns:
        the strings split off, any of which may be empty.

    - #### test

          public boolean test(java.lang.String input)

      Determines if the regular expression matches the given string. This call affects the value returned by `getLastIndex()` if the global flag is set. Equivalent to: `exec(input) != null`
      Parameters:
        `input` - the string to apply the regular expression to
      Returns:
        whether the regular expression matches the given string.