info.codesaway.util.regex
Interface MatchResult

All Superinterfaces:
java.lang.Iterable<MatchResult>
All Known Implementing Classes:
Matcher

public interface MatchResult
extends java.lang.Iterable<MatchResult>

The result of a match operation.

This interface is an extension of Java's MatchResult class. Javadocs were copied and appended with the added functionality.

This interface contains query methods used to determine the results of a match against a regular expression. The match boundaries, groups and group boundaries can be seen but not modified through a MatchResult.


Starting with Version 0.2, MatchResult extends Iterable<MatchResult> and is Groovified, adding some useful functionality.

Given the following MatchResult:

 Pattern pattern = Pattern.compile("(a)(b)(c)(d)");
 Matcher matcher = pattern.matcher("abcd");
 matcher.find();
 
 MatchResult result = matcher.toMatchResult();

Loop through each group (by group number):

  // Loops for group = 1 to 3 (group count)
  for (int group : result.keySet()) {
    /*
    * Output:
    *
    * result[1] = a
    * result[2] = b
    * result[3] = c
    */
    System.out.printf("result[%d] = %s%n", group, result.group(group));
  }

Loop through each group's value:

  // Loops for each value
  for (String groupValue : result.values()) {
    /*
    * Output:
    *
    * Value = a
    * Value = b
    * Value = c
    */
    System.out.printf("Value = %s%n", groupValue);
  }

See Also:
Matcher

Method Summary
 boolean asBoolean()
          Alias for matched().
 boolean containsKey(java.lang.Object key)
           
 boolean containsValue(java.lang.Object value)
           
 int end()
          Returns the offset after the last character matched.
 int end(int group)
          Returns the offset after the last character of the subsequence captured by the given group during this match.
 int end(java.lang.String group)
          Returns the offset after the last character of the subsequence captured by the given group during this match.
 int end(java.lang.String groupName, int occurrence)
          Returns the offset after the last character of the subsequence captured by the given group during this match.
 java.util.Set<java.util.Map.Entry<java.lang.Integer,java.lang.String>> entrySet()
           
 java.lang.String get(java.lang.Object key)
           
 java.lang.Object getAt(int group)
          Alias for group(int)
 java.lang.String getAt(java.lang.String group)
          Alias for group(String)
 java.lang.String getGroupName(int group)
          Returns the group name (if any) for the specified group.
 java.lang.String group()
          Returns the input subsequence matched by the previous match.
 java.lang.String group(int group)
          Returns the input subsequence captured by the given group during the previous match operation.
 java.lang.String group(int group, java.lang.String defaultValue)
          Returns the input subsequence captured by the given group during the previous match operation.
 java.lang.String group(java.lang.String group)
          Returns the input subsequence captured by the given group during the previous match operation.
 java.lang.String group(java.lang.String groupName, int occurrence)
          Returns the input subsequence captured by the given group during the previous match operation.
 java.lang.String group(java.lang.String groupName, int occurrence, java.lang.String defaultValue)
          Returns the input subsequence captured by the given group during the previous match operation.
 java.lang.String group(java.lang.String group, java.lang.String defaultValue)
          Returns the input subsequence captured by the given group during the previous match operation.
 int groupCount()
          Returns the number of capturing groups in this match result's pattern.
 int groupCount(int group)
           
 int groupCount(java.lang.String groupName)
          Returns the number of capturing groups (with the given group name) in this match result's pattern.
 boolean isEmpty()
          Returns whether the previous match matched the empty string.
 boolean isEmpty(int group)
          Returns whether the specified group matched the empty string.
 boolean isEmpty(java.lang.String group)
          Returns whether the specified group matched the empty string.
 boolean isEmpty(java.lang.String groupName, int occurrence)
          Returns whether the specified group matched the empty string.
 java.util.Set<java.lang.Integer> keySet()
           
 boolean matched()
          Returns whether the match was successful.
 boolean matched(int group)
          Returns whether the specified group matched any part of the input sequence.
 boolean matched(java.lang.String group)
          Returns whether the specified group matched any part of the input sequence.
 boolean matched(java.lang.String groupName, int occurrence)
          Returns whether the specified group matched any part of the input sequence.
 int occurrence(int groupIndex)
          Returns the occurrence of the first matched group with the given index.
 int occurrence(java.lang.String groupName)
          Returns the occurrence of the first matched group with the given name.
 Pattern pattern()
          Returns the pattern that is interpreted by this matcher.
 int size()
           
 int start()
          Returns the start index of the match.
 int start(int group)
          Returns the start index of the subsequence captured by the given group during this match.
 int start(java.lang.String group)
          Returns the start index of the subsequence captured by the given group during this match.
 int start(java.lang.String groupName, int occurrence)
          Returns the start index of the subsequence captured by the given group during this match.
 java.lang.String text()
          Returns the string being matched.
 boolean treatNullAsEmptyString()
           
 java.util.List<java.lang.String> values()
           
 
Methods inherited from interface java.lang.Iterable
iterator
 

Method Detail

start

int start()
Returns the start index of the match.

Returns:
The index of the first character matched
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed

start

int start(int group)
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().

Parameters:
group - The index of a capturing group in this matcher's pattern
Returns:
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
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IndexOutOfBoundsException - If there is no capturing group in the pattern with the given index

start

int start(java.lang.String group)
Returns the start index of the subsequence captured by the given group during this match.

Parameters:
group - A capturing group in this matcher's pattern
Returns:
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
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

start

int start(java.lang.String groupName,
          int occurrence)
Returns the start index of the subsequence captured by the given group during this match.

An invocation of this convenience method of the form

m.start(groupName, occurrence)

behaves in exactly the same way as

 m.start(groupName + "[" + occurrence + "]")

Parameters:
groupName - The group name for a capturing group in this matcher's pattern
occurrence - The occurrence of the specified group name
Returns:
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
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

end

int end()
Returns the offset after the last character matched.

Returns:
The offset after the last character matched
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed

end

int end(int group)
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().

Parameters:
group - The index of a capturing group in this matcher's pattern
Returns:
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
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IndexOutOfBoundsException - If there is no capturing group in the pattern with the given index

end

int end(java.lang.String group)
Returns the offset after the last character of the subsequence captured by the given group during this match.

Parameters:
group - A capturing group in this matcher's pattern
Returns:
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
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

end

int end(java.lang.String groupName,
        int occurrence)
Returns the offset after the last character of the subsequence captured by the given group during this match.

An invocation of this convenience method of the form

m.end(groupName, occurrence)

behaves in exactly the same way as

 m.end(groupName + "[" + occurrence + "]")

Parameters:
groupName - The group name for a capturing group in this matcher's pattern
occurrence - The occurrence of the specified group name
Returns:
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
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

occurrence

int occurrence(int groupIndex)
Returns the occurrence of the first matched group with the given index.

Branch reset patterns allow multiple capture groups with the same group index to exist. This method offers a way to determine which occurrence matched.

Parameters:
groupIndex - the name of the group
Returns:
the occurrence for the first matched group with the given index


occurrence

int occurrence(java.lang.String groupName)
Returns the occurrence of the first matched group with the given name.

Branch reset patterns and the Pattern.DUPLICATE_NAMES flag allow multiple capture groups with the same group name to exist. This method offers a way to determine which occurrence matched.

Parameters:
groupName - the name of the group
Returns:
the occurrence of the first matched group with the given name.


group

java.lang.String group()
Returns the input subsequence matched by the previous match.

For a matcher m with input sequence s, the expressions om.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.

Returns:
The (possibly empty) subsequence matched by the previous match, in string form
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed

group

java.lang.String group(int 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.

Parameters:
group - The index of a capturing group in this matcher's pattern
Returns:
The (possibly empty) subsequence captured by the group during the previous match, or null if the group failed to match part of the input
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IndexOutOfBoundsException - If there is no capturing group in the pattern with the given index

group

java.lang.String group(int group,
                       java.lang.String defaultValue)
Returns the input subsequence captured by the given group during the previous match operation.

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

If the match was successful but the group specified failed to match any part of the input sequence, then defaultValue is returned, whereas group(int) would return null. Otherwise, the return is equivalent to that of m.group(group).

As a note,

m.group(group, null)

behaves in exactly the same way as

m.group(group)

Parameters:
group - The index of a capturing group in this matcher's pattern
defaultValue - The string to return if group(int) would return null
Returns:
The (possibly empty) subsequence captured by the group during the previous match, or defaultValue if the group failed to match part of the input
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IndexOutOfBoundsException - If there is no capturing group in the pattern with the given index
See Also:
group(int)

group

java.lang.String group(java.lang.String group)
Returns the input subsequence captured by the given group during the previous match operation.

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.

Parameters:
group - A capturing group in this matcher's pattern
Returns:
The (possibly empty) subsequence captured by the group during the previous match, or null if the group failed to match part of the input
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

group

java.lang.String group(java.lang.String group,
                       java.lang.String defaultValue)
Returns the input subsequence captured by the given group during the previous match operation.

If the match was successful but the group specified failed to match any part of the input sequence, then defaultValue is returned, whereas group(String) would return null. Otherwise, the return is equivalent to that of m.group(group).

As a note,

m.group(group, null)

behaves in exactly the same way as

m.group(group)

Parameters:
group - A capturing group in this matcher's pattern
defaultValue - The string to return if group(String) would return null
Returns:
The (possibly empty) subsequence captured by the group during the previous match, or defaultValue if the group failed to match part of the input
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group
See Also:
group(String)

group

java.lang.String group(java.lang.String groupName,
                       int occurrence)
Returns the input subsequence captured by the given group during the previous match operation.

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.

An invocation of this convenience method of the form

m.group(groupName, occurrence)

behaves in exactly the same way as

 m.group(groupName + "[" + occurrence + "]")

Parameters:
groupName - The group name for a capturing group in this matcher's pattern
occurrence - The occurrence of the specified group name
Returns:
The (possibly empty) subsequence captured by the group during the previous match, or null if the group failed to match part of the input
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

group

java.lang.String group(java.lang.String groupName,
                       int occurrence,
                       java.lang.String defaultValue)
Returns the input subsequence captured by the given group during the previous match operation.

If the match was successful but the group specified failed to match any part of the input sequence, then defaultValue is returned, whereas group(String, int) would return null. Otherwise, the return is equivalent to that of m.group(groupName, occurrence).

As a note,

m.group(groupName, occurrence, null)

behaves in exactly the same way as

 m.group(groupName, occurrence)

An invocation of this convenience method of the form

 m.group(groupName, occurrence, defaultValue)

behaves in exactly the same way as

 m.group(groupName + "[" + occurrence + "]", defaultValue)

Parameters:
groupName - The group name for a capturing group in this matcher's pattern
occurrence - The occurrence of the specified group name
defaultValue - The string to return if group(String, int) would return null
Returns:
The (possibly empty) subsequence captured by the group during the previous match, or defaultValue if the group failed to match part of the input
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group
See Also:
group(String, int)

groupCount

int groupCount()
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.

Returns:
The number of capturing groups in this matcher result's pattern

groupCount

int groupCount(int group)
Parameters:
group -
Returns:
Since:
0.2

groupCount

int groupCount(java.lang.String groupName)
Returns the number of capturing groups (with the given group name) 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 occurrence (for a group, groupName[occurrence]) for this matcher.

If groupName is the empty string, this method's return is equal to the return from groupCount().

Note: unlike other methods, this method doesn't throw an exception if the specified group doesn't exist. Instead, zero is returned, since the number of groups with the given (non-existent) group name is zero.

Parameters:
groupName - The group name for a capturing group in this matcher's pattern
Returns:
The number of capturing groups (with the given group name) in this matcher's pattern

matched

boolean matched()
Returns whether the match was successful.

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

Note: unlike the other methods, this method won't throw an exception if no match has been attempted - instead, false will be returned. This method provides a way to check that a match has been attempted, and that it succeeded.

Returns:
true if the match was successful

matched

boolean matched(int group)
Returns whether the specified group matched any part of the input sequence.

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

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

Parameters:
group - The index of a capturing group in this matcher's pattern
Returns:
true if in the previous match, the group matched part of the input.
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IndexOutOfBoundsException - If there is no capturing group in the pattern with the given index

matched

boolean matched(java.lang.String group)
Returns whether the specified group matched any part of the input sequence.

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

Parameters:
group - A capturing group in this matcher's pattern
Returns:
true if in the previous match, the group matched part of the input.
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

matched

boolean matched(java.lang.String groupName,
                int occurrence)
Returns whether the specified group matched any part of the input sequence.

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

An invocation of this convenience method of the form

m.matched(groupName, occurrence)

behaves in exactly the same way as

 m.matched(groupName + "[" + occurrence + "]")

Parameters:
groupName - The group name for a capturing group in this matcher's pattern
occurrence - The occurrence of the specified group name
Returns:
true if in the previous match, the group matched part of the input.
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

isEmpty

boolean isEmpty()
Returns whether the previous match matched the empty string.

Returns:
true if the previous match matched the empty string.
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed

isEmpty

boolean isEmpty(int group)
Returns whether the specified group matched the empty string.

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

If the match was successful but the group specified failed to match any part of the input sequence, then false is returned.

Parameters:
group - The index of a capturing group in this matcher's pattern
Returns:
true if in the previous match, the group matched the empty string.
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IndexOutOfBoundsException - If there is no capturing group in the pattern with the given index

isEmpty

boolean isEmpty(java.lang.String group)
Returns whether the specified group matched the empty string.

If the match was successful but the group specified failed to match any part of the input sequence, then false is returned.

Parameters:
group - A capturing group in this matcher's pattern
Returns:
true if in the previous match, the group matched the empty string.
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

isEmpty

boolean isEmpty(java.lang.String groupName,
                int occurrence)
Returns whether the specified group matched the empty string.

If the match was successful but the group specified failed to match any part of the input sequence, then false is returned.

An invocation of this convenience method of the form

m.isEmpty(groupName, occurrence)

behaves in exactly the same way as

 m.isEmpty(groupName + "[" + occurrence + "]")

Parameters:
groupName - The group name for a capturing group in this matcher's pattern
occurrence - The occurrence of the specified group name
Returns:
true if in the previous match, the group matched the empty string.
Throws:
java.lang.IllegalStateException - If no match has yet been attempted, or if the previous match operation failed
java.lang.IllegalArgumentException - If there is no capturing group in the pattern of the given group

pattern

Pattern pattern()
Returns the pattern that is interpreted by this matcher.

Returns:
The pattern for which this matcher was created

text

java.lang.String text()
Returns the string being matched.

Returns:
the string being matched

getGroupName

java.lang.String getGroupName(int group)
Returns the group name (if any) for the specified group.

If a match has been successful, this function's return is the group name associated with the given group for this match. This group name is match independent, except, possibly, when the group is part of a "branch reset" pattern.

If there is no successful match, this function's return is the group name, only in the case that it is match independent. The only case where the group name is not match independent is when the group is part of a "branch reset" subpattern, and there are at least two groups with the given number.

For example, in the pattern (?|(?<group1a>1a)|(?<group1b>1b), the group name for group 1 depends on whether the pattern matches "1a" or "1b". In this case, an IllegalStateException is thrown, because a match is required to determine the group name.

If there is more than one occurrence of the group, the returned group name includes the occurrence - for example, myGroup[1]. If there is only one occurrence of the group, only the group name is returned - for example, myGroup.

Parameters:
group - The index of a capturing group in this matcher's pattern
Returns:
the group name for the specified group, or null if the group has no associated group name
Throws:
java.lang.IllegalStateException - If the group name is match dependent, and no match has yet been attempted, or if the previous match operation failed

treatNullAsEmptyString

boolean treatNullAsEmptyString()
Since:
0.2

containsKey

boolean containsKey(java.lang.Object key)
Parameters:
key -
Returns:
Since:
0.2

containsValue

boolean containsValue(java.lang.Object value)
Parameters:
value -
Returns:
Since:
0.2

entrySet

java.util.Set<java.util.Map.Entry<java.lang.Integer,java.lang.String>> entrySet()
Returns:
Since:
0.2

get

java.lang.String get(java.lang.Object key)
Parameters:
key -
Returns:
Since:
0.2

keySet

java.util.Set<java.lang.Integer> keySet()
Returns:
Since:
0.2

size

int size()
Returns:
Since:
0.2

values

java.util.List<java.lang.String> values()
Returns:
Since:
0.2

asBoolean

boolean asBoolean()
Alias for matched().

Coerces a Matcher instance to a boolean value, for use in Groovy truth

Since:
0.2

getAt

java.lang.Object getAt(int group)
Alias for group(int)

In Groovy, adds support the subscript operator, e.g. matcher[group], for a regex Matcher.

Parameters:
group -
Returns:
Since:
0.2

getAt

java.lang.String getAt(java.lang.String group)
Alias for group(String)

In Groovy, adds support the subscript operator, e.g. matcher[group], for a regex Matcher.

Parameters:
group -
Returns:
Since:
0.2