regexodus.regex.MatchResult Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jtransc-rt Show documentation
JVM AOT compiler currently generating JavaScript, C++, Haxe, with initial focus on Kotlin and games.
There is a newer version: 0.6.8
package regexodus.regex;

/**
 * Created by Tommy Ettinger on 6/7/2016.
 */
public interface MatchResult {

    /**
     * Returns the start index of the match.
     * @return  The index of the first character matched
     */
    int start();

    /**
     * Returns the start index of the subsequence captured by the given group
     * during this match.
     * 

     * Capturing groups are indexed from left
     * to right, starting at one.  Group zero denotes the entire pattern, so
     * the expression m.start(0) is equivalent to
     * m.start().
     * @param  group
     *         The index of a capturing group in this matcher's pattern
     * @return  The index of the first character captured by the group,
     *          or -1 if the match was successful but the group
     *          itself did not match anything
     */
    int start(int group);

    /**
     * Returns the start index of the subsequence captured by the given
     * named-capturing group during the previous match operation.
     *
     * @param  name
     *         The name of a named capturing group in this matcher's pattern
     * @return  The index of the first character captured by the group,
     *          or -1 if the match was successful but the group
     *          itself did not match anything
     */
    int start(String name);

    /**
     * Returns the offset after the last character matched.
     * @return  The offset after the last character matched
     */
    int end();

    /**
     * Returns the offset after the last character of the subsequence
     * captured by the given group during this match.
     * 

     * Capturing groups are indexed from left
     * to right, starting at one.  Group zero denotes the entire pattern, so
     * the expression m.end(0) is equivalent to
     * m.end().
     *
     * @param  group
     *         The index of a capturing group in this matcher's pattern
     *
     * @return  The offset after the last character captured by the group,
     *          or -1 if the match was successful
     *          but the group itself did not match anything
     */
    int end(int group);

    /**
     * Returns the offset after the last character of the subsequence captured
     * by the given named-capturing group during the previous match operation.
     *
     * @param  name
     *         The name of a named capturing group in this matcher's pattern
     *
     * @return  The offset after the last character captured by the group,
     *          or -1 if the match was successful
     *          but the group itself did not match anything
     */
    int end(String name);

    /**
     * Returns the input subsequence matched by the previous match.
     * 

     * For a matcher m with input sequence s,
     * the expressions m.group() and
     * s.substring(m.start(), m.end())
     * are equivalent.
     * 

     * Note that some patterns, for example a*, match the empty
     * string.  This method will return the empty string when the pattern
     * successfully matches the empty string in the input.
     *
     * @return The (possibly empty) subsequence matched by the previous match,
     *         in string form
     */
    String group();

    /**
     * Returns the input subsequence captured by the given group during the
     * previous match operation.
     * 

     * For a matcher m, input sequence s, and group index
     * g, the expressions m.group(g) and
     * s.substring(m.start(g), m.end(g))
     * are equivalent.
     * 

     * Capturing groups are indexed from left
     * to right, starting at one.  Group zero denotes the entire pattern, so
     * the expression m.group(0) is equivalent to m.group().
     * 

     * If the match was successful but the group specified failed to match
     * any part of the input sequence, then null is returned. Note
     * that some groups, for example (a*), match the empty string.
     * This method will return the empty string when such a group successfully
     * matches the empty string in the input.
     *
     * @param  group
     *         The index of a capturing group in this matcher's pattern
     *
     * @return  The (possibly empty) subsequence captured by the group
     *          during the previous match, or null if the group
     *          failed to match part of the input
     */
    String group(int group);

    /**
     * Returns the number of capturing groups in this match result's pattern.
     * 

     * Group zero denotes the entire pattern by convention. It is not
     * included in this count.
     * 

     * Any non-negative integer smaller than or equal to the value
     * returned by this method is guaranteed to be a valid group index for
     * this matcher.
     *
     * @return The number of capturing groups in this matcher's pattern
     */
    int groupCount();
}