jtulach@1348: /* jtulach@1348: * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. jtulach@1348: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jtulach@1348: * jtulach@1348: * This code is free software; you can redistribute it and/or modify it jtulach@1348: * under the terms of the GNU General Public License version 2 only, as jtulach@1348: * published by the Free Software Foundation. Oracle designates this jtulach@1348: * particular file as subject to the "Classpath" exception as provided jtulach@1348: * by Oracle in the LICENSE file that accompanied this code. jtulach@1348: * jtulach@1348: * This code is distributed in the hope that it will be useful, but WITHOUT jtulach@1348: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jtulach@1348: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jtulach@1348: * version 2 for more details (a copy is included in the LICENSE file that jtulach@1348: * accompanied this code). jtulach@1348: * jtulach@1348: * You should have received a copy of the GNU General Public License version jtulach@1348: * 2 along with this work; if not, write to the Free Software Foundation, jtulach@1348: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jtulach@1348: * jtulach@1348: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jtulach@1348: * or visit www.oracle.com if you need additional information or have any jtulach@1348: * questions. jtulach@1348: */ jtulach@1348: jtulach@1348: package java.util.regex; jtulach@1348: jtulach@1348: /** jtulach@1348: * The result of a match operation. jtulach@1348: * jtulach@1348: *

This interface contains query methods used to determine the jtulach@1348: * results of a match against a regular expression. The match boundaries, jtulach@1348: * groups and group boundaries can be seen but not modified through jtulach@1348: * a MatchResult. jtulach@1348: * jtulach@1348: * @author Michael McCloskey jtulach@1348: * @see Matcher jtulach@1348: * @since 1.5 jtulach@1348: */ jtulach@1348: public interface MatchResult { jtulach@1348: jtulach@1348: /** jtulach@1348: * Returns the start index of the match. jtulach@1348: * jtulach@1348: * @return The index of the first character matched jtulach@1348: * jtulach@1348: * @throws IllegalStateException jtulach@1348: * If no match has yet been attempted, jtulach@1348: * or if the previous match operation failed jtulach@1348: */ jtulach@1348: public int start(); jtulach@1348: jtulach@1348: /** jtulach@1348: * Returns the start index of the subsequence captured by the given group jtulach@1348: * during this match. jtulach@1348: * jtulach@1348: *

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

jtulach@1348: * jtulach@1348: * @param group jtulach@1348: * The index of a capturing group in this matcher's pattern jtulach@1348: * jtulach@1348: * @return The index of the first character captured by the group, jtulach@1348: * or -1 if the match was successful but the group jtulach@1348: * itself did not match anything jtulach@1348: * jtulach@1348: * @throws IllegalStateException jtulach@1348: * If no match has yet been attempted, jtulach@1348: * or if the previous match operation failed jtulach@1348: * jtulach@1348: * @throws IndexOutOfBoundsException jtulach@1348: * If there is no capturing group in the pattern jtulach@1348: * with the given index jtulach@1348: */ jtulach@1348: public int start(int group); jtulach@1348: jtulach@1348: /** jtulach@1348: * Returns the offset after the last character matched.

jtulach@1348: * jtulach@1348: * @return @return The offset after the last character matched jtulach@1348: * jtulach@1348: * @throws IllegalStateException jtulach@1348: * If no match has yet been attempted, jtulach@1348: * or if the previous match operation failed jtulach@1348: */ jtulach@1348: public int end(); jtulach@1348: jtulach@1348: /** jtulach@1348: * Returns the offset after the last character of the subsequence jtulach@1348: * captured by the given group during this match. jtulach@1348: * jtulach@1348: *

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

jtulach@1348: * jtulach@1348: * @param group jtulach@1348: * The index of a capturing group in this matcher's pattern jtulach@1348: * jtulach@1348: * @return The offset after the last character captured by the group, jtulach@1348: * or -1 if the match was successful jtulach@1348: * but the group itself did not match anything jtulach@1348: * jtulach@1348: * @throws IllegalStateException jtulach@1348: * If no match has yet been attempted, jtulach@1348: * or if the previous match operation failed jtulach@1348: * jtulach@1348: * @throws IndexOutOfBoundsException jtulach@1348: * If there is no capturing group in the pattern jtulach@1348: * with the given index jtulach@1348: */ jtulach@1348: public int end(int group); jtulach@1348: jtulach@1348: /** jtulach@1348: * Returns the input subsequence matched by the previous match. jtulach@1348: * jtulach@1348: *

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

jtulach@1348: * jtulach@1348: *

Note that some patterns, for example a*, match the empty jtulach@1348: * string. This method will return the empty string when the pattern jtulach@1348: * successfully matches the empty string in the input.

jtulach@1348: * jtulach@1348: * @return The (possibly empty) subsequence matched by the previous match, jtulach@1348: * in string form jtulach@1348: * jtulach@1348: * @throws IllegalStateException jtulach@1348: * If no match has yet been attempted, jtulach@1348: * or if the previous match operation failed jtulach@1348: */ jtulach@1348: public String group(); jtulach@1348: jtulach@1348: /** jtulach@1348: * Returns the input subsequence captured by the given group during the jtulach@1348: * previous match operation. jtulach@1348: * jtulach@1348: *

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

jtulach@1348: * jtulach@1348: *

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

jtulach@1348: * jtulach@1348: *

If the match was successful but the group specified failed to match jtulach@1348: * any part of the input sequence, then null is returned. Note jtulach@1348: * that some groups, for example (a*), match the empty string. jtulach@1348: * This method will return the empty string when such a group successfully jtulach@1348: * matches the empty string in the input.

jtulach@1348: * jtulach@1348: * @param group jtulach@1348: * The index of a capturing group in this matcher's pattern jtulach@1348: * jtulach@1348: * @return The (possibly empty) subsequence captured by the group jtulach@1348: * during the previous match, or null if the group jtulach@1348: * failed to match part of the input jtulach@1348: * jtulach@1348: * @throws IllegalStateException jtulach@1348: * If no match has yet been attempted, jtulach@1348: * or if the previous match operation failed jtulach@1348: * jtulach@1348: * @throws IndexOutOfBoundsException jtulach@1348: * If there is no capturing group in the pattern jtulach@1348: * with the given index jtulach@1348: */ jtulach@1348: public String group(int group); jtulach@1348: jtulach@1348: /** jtulach@1348: * Returns the number of capturing groups in this match result's pattern. jtulach@1348: * jtulach@1348: *

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

Any non-negative integer smaller than or equal to the value jtulach@1348: * returned by this method is guaranteed to be a valid group index for jtulach@1348: * this matcher.

jtulach@1348: * jtulach@1348: * @return The number of capturing groups in this matcher's pattern jtulach@1348: */ jtulach@1348: public int groupCount(); jtulach@1348: jtulach@1348: }