MatchResult (Jakarta-ORO 2.0.8 API)
Keywords: org.apache.oro.text.regex.MatchResult interface

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.oro.text.regex
Interface MatchResult

All Known Implementing Classes:
  Perl5Util

public interface MatchResult

The MatchResult interface allows PatternMatcher implementors to return results storing match information in whatever format they like, while presenting a consistent way of accessing that information. However, MatchResult implementations should strictly follow the behavior described for the interface methods.

A MatchResult instance contains a pattern match and its saved groups. You can access the entire match directly using the `group(int)` method with an argument of 0, or by the `toString()` method which is defined to return the same thing. It is also possible to obtain the beginning and ending offsets of a match relative to the input producing the match by using the `beginOffset(int)` and `endOffset(int)` methods. The `begin(int)` and `end(int)` are useful in some circumstances and return the begin and end offsets of the subgroups of a match relative to the beginning of the match.

You might use a MatchResult as follows:

>      int groups;
>      PatternMatcher matcher;
>      PatternCompiler compiler;
>      Pattern pattern;
>      PatternMatcherInput input;
>      MatchResult result;

>      compiler = new Perl5Compiler();
>      matcher  = new Perl5Matcher();

>      try {
>        pattern = compiler.compile(somePatternString);
>      } catch(MalformedPatternException e) {
>        System.out.println("Bad pattern.");
>        System.out.println(e.getMessage());
>        return;
>      }

>      input   = new PatternMatcherInput(someStringInput);

>      while(matcher.contains(input, pattern)) {
>        result = matcher.getMatch();
>        // Perform whatever processing on the result you want.
>        // Here we just print out all its elements to show how its
>        // methods are used.

>        System.out.println("Match: " + result.toString());
>        System.out.println("Length: " + result.length());
>        groups = result.groups();
>        System.out.println("Groups: " + groups);
>        System.out.println("Begin offset: " + result.beginOffset(0));
>        System.out.println("End offset: " + result.endOffset(0));
>        System.out.println("Saved Groups: ");

>        // Start at 1 because we just printed out group 0
>        for(int group = 1; group < groups; group++) {
>     	 System.out.println(group + ": " + result.group(group));
>     	 System.out.println("Begin: " + result.begin(group));
>     	 System.out.println("End: " + result.end(group));
>        }
>      }

Since:
  1.0
Version:
  2.0.8
See Also:
  `PatternMatcher`

Method Summary
`int` | `begin(int group)`
`int` | `beginOffset(int group)` Returns an offset marking the beginning of the pattern match relative to the beginning of the input from which the match was extracted.
`int` | `end(int group)`
`int` | `endOffset(int group)` Returns an offset marking the end of the pattern match relative to the beginning of the input from which the match was extracted.
`java.lang.String` | `group(int group)` Returns the contents of the parenthesized subgroups of a match, counting parentheses from left to right and starting from 1.
`int` | `groups()`
`int` | `length()` A convenience method returning the length of the entire match.
`java.lang.String` | `toString()` Returns the same as group(0).

Method Detail

### length

    public int length()

  A convenience method returning the length of the entire match. If you want to get the length of a particular subgroup you should use the `group(int)` method to get the string and then access its length() method as follows:

  >      int length = -1; // Use -1 to indicate group doesn't exist
  >      MatchResult result;
  >      String subgroup;

  >      // Initialization of result omitted

  >      subgroup = result.group(1);
  >      if(subgroup != null)
  >        length = subgroup.length();

  The length() method serves as a more a more efficient way to do:

  >      length = result.group(0).length();

  Returns:
    The length of the match.

### groups

    public int groups()

  Returns:
    The number of groups contained in the result. This number includes the 0th group. In other words, the result refers to the number of parenthesized subgroups plus the entire match itself.

### group

    public java.lang.String group(int group)

  Returns the contents of the parenthesized subgroups of a match, counting parentheses from left to right and starting from 1. Group 0 always refers to the entire match. For example, if the pattern `foo(\d+)` is used to extract a match from the input `abfoo123` , then `group(0)` will return `foo123` and `group(1)` will return `123` . `group(2)` will return `null` because there is only one subgroup in the original pattern.

  Parameters:
    `group` - The pattern subgroup to return.
  Returns:
    A string containing the indicated pattern subgroup. Group 0 always refers to the entire match. If a group was never matched, it returns null. This is not to be confused with a group matching the null string, which will return a String of length 0.

### begin

    public int begin(int group)

  Parameters:
    `group` - The pattern subgroup.
  Returns:
    The offset into group 0 of the first token in the indicated pattern subgroup. If a group was never matched or does not exist, returns -1. Be aware that a group that matches the null string at the end of a match will have an offset equal to the length of the string, so you shouldn't blindly use the offset to index an array or String.

### end

    public int end(int group)

  Parameters:
    `group` - The pattern subgroup.
  Returns:
    Returns one plus the offset into group 0 of the last token in the indicated pattern subgroup. If a group was never matched or does not exist, returns -1. A group matching the null string will return its start offset.

### beginOffset

    public int beginOffset(int group)

  Returns an offset marking the beginning of the pattern match relative to the beginning of the input from which the match was extracted.

  Parameters:
    `group` - The pattern subgroup.
  Returns:
    The offset of the first token in the indicated pattern subgroup. If a group was never matched or does not exist, returns -1.

### endOffset

    public int endOffset(int group)

  Returns an offset marking the end of the pattern match relative to the beginning of the input from which the match was extracted.

  Parameters:
    `group` - The pattern subgroup.
  Returns:
    Returns one plus the offset of the last token in the indicated pattern subgroup. If a group was never matched or does not exist, returns -1. A group matching the null string will return its start offset.

### toString

    public java.lang.String toString()

  Returns the same as group(0).

  Returns:
    A string containing the entire match.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright ? 2000-2003 Apache Software Foundation. All Rights Reserved.