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