: Class Matcher

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

## jregex
Class Matcher

    java.lang.Object
      |
      +--jregex.Matcher

All Implemented Interfaces:
  MatchResult

public class Matcher
extends java.lang.Object
implements MatchResult

Matcher instance is an automaton that actually performs matching. It provides the following methods:

- searching for a matching substrings : matcher.find() or matcher.findAll();
- testing whether a text matches a whole pattern : matcher.matches();
- testing whether the text matches the beginning of a pattern : matcher.matchesPrefix();
- searching with custom options : matcher.find(int options)

  Obtaining results
  After the search succeded, i.e. if one of above methods returned `true` one may obtain an information on the match:

- may check whether some group is captured : matcher.isCaptured(int);
- may obtain start and end positions of the match and its length : matcher.start(int),matcher.end(int),matcher.length(int);
- may obtain match contents as String : matcher.group(int).
  The same way can be obtained the match prefix and suffix information. The appropriate methods are grouped in MatchResult interface, which the Matcher class implements.
  Matcher objects are not thread-safe, so only one thread may use a matcher instance at a time. Note, that Pattern objects are thread-safe(the same instanse may be shared between multiple threads), and the typical tactics in multithreaded applications is to have one Pattern instance per expression(a singleton), and one Matcher object per thread.

  Field Summary
  `static int` | `ACCEPT_INCOMPLETE` Experimental option; if a text ends up before the end of a pattern,report a match.
  `static int` | `ANCHOR_END` The same effect as "$" without REFlags.MULTILINE.
  `static int` | `ANCHOR_LASTMATCH` The same effect as "\\G".
  `static int` | `ANCHOR_START` The same effect as "^" without REFlags.MULTILINE.

  Fields inherited from interface jregex.MatchResult
  `MATCH, PREFIX, SUFFIX, TARGET`

  Method Summary
  `char` | `charAt(int i)`
  `char` | `charAt(int i, int groupId)`
  `int` | `end()`
  `int` | `end(int id)`
  `boolean` | `find()` Searches through a target for a matching substring, starting from just after the end of last match.
  `boolean` | `find(int anchors)` Searches through a target for a matching substring, starting from just after the end of last match.
  `MatchIterator` | `findAll()` The same as findAll(int), but with default behaviour;
  `MatchIterator` | `findAll(int options)` Returns an iterator over the matches found by subsequently calling find(options), the search starts from the zero position.
  `boolean` | `getGroup(int n, java.lang.StringBuffer sb)`
  `boolean` | `getGroup(int n, TextBuffer tb)`
  `boolean` | `getGroup(java.lang.String name, java.lang.StringBuffer sb)`
  `boolean` | `getGroup(java.lang.String name, TextBuffer tb)`
  `java.lang.String` | `group(int n)`
  `java.lang.String` | `group(java.lang.String name)`
  `int` | `groupCount()`
  `java.lang.String[]` | `groups()`
  `java.util.Vector` | `groupv()`
  `boolean` | `isCaptured()`
  `boolean` | `isCaptured(int id)`
  `boolean` | `isCaptured(java.lang.String groupName)`
  `boolean` | `isStart()` Deprecated. Replaced by isPrefix()
  `int` | `length()`
  `int` | `length(int id)`
  `boolean` | `matches()` Tells whether a current target matches the whole pattern.
  `boolean` | `matches(java.lang.String s)` Just a combination of setTarget(String) and matches().
  `boolean` | `matchesPrefix()` Tells whether the entire target matches the beginning of the pattern.
  `Pattern` | `pattern()`
  `java.lang.String` | `prefix()`
  `boolean` | `proceed()` Continues to search from where the last search left off.
  `boolean` | `proceed(int options)` Continues to search from where the last search left off using specified options: Matcher m=new Pattern("\\w+").matcher("abc"); while(m.proceed(0)){ System.out.println(m.group(0)); } Output: abc ab a bc b c For example, let's find all odd nubmers occuring in a text: Matcher m=new Pattern("\\d+").matcher("123"); while(m.proceed(0)){ String match=m.group(0); if(isOdd(Integer.parseInt(match))) System.out.println(match); } static boolean isOdd(int i){ return (i&1)>0; } This outputs: 123 1 23 3 Note that using `find()` method we would find '123' only.
  `void` | `setPosition(int pos)` Allows to set a position the subsequent find()/find(int) will start from.
  `void` | `setTarget(char[] text, int start, int len)` Supplies a text to search in/match with, as a part of char array.
  `void` | `setTarget(char[] text, int start, int len, boolean shared)` To be used with much care.
  `void` | `setTarget(Matcher m, int groupId)` This method allows to efficiently pass data between matchers.
  `void` | `setTarget(java.io.Reader in, int len)` Supplies a text to search in/match with through a stream.
  `void` | `setTarget(java.lang.String text)` Supplies a text to search in/match with.
  `void` | `setTarget(java.lang.String text, int start, int len)` Supplies a text to search in/match with, as a part of String.
  `void` | `skip()` Sets the current search position just after the end of last match.
  `int` | `start()`
  `int` | `start(int id)`
  `java.lang.String` | `suffix()`
  `java.lang.String` | `target()`
  `char[]` | `targetChars()`
  `int` | `targetEnd()`
  `int` | `targetStart()`
  `java.lang.String` | `toString_d()`
  `java.lang.String` | `toString()`

  Methods inherited from class java.lang.Object
  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  Field Detail

  ### ANCHOR_START

      public static final int ANCHOR_START

    The same effect as "^" without REFlags.MULTILINE.
    See Also:
      `find(int)`

  ### ANCHOR_LASTMATCH

      public static final int ANCHOR_LASTMATCH

    The same effect as "\\G".
    See Also:
      `find(int)`

  ### ANCHOR_END

      public static final int ANCHOR_END

    The same effect as "$" without REFlags.MULTILINE.
    See Also:
      `find(int)`

  ### ACCEPT_INCOMPLETE

      public static final int ACCEPT_INCOMPLETE

    Experimental option; if a text ends up before the end of a pattern,report a match.
    See Also:
      `find(int)`

  Method Detail

  ### setTarget

      public final void setTarget(Matcher m,
                                  int groupId)

    This method allows to efficiently pass data between matchers. Note that a matcher may pass data to itself:

           Matcher m=new Pattern("\\w+").matcher(myString);
           if(m.find())m.setTarget(m,m.SUFFIX); //forget all that is not a suffix

    Resets current search position to zero.
    Parameters:
      `m` - - a matcher that is a source of data
      `groupId` - - which group to take data from
    See Also:
      `setTarget(java.lang.String)`, `setTarget(java.lang.String,int,int)`, `setTarget(char[],int,int)`, `setTarget(java.io.Reader,int)`

  ### setTarget

      public void setTarget(java.lang.String text)

    Supplies a text to search in/match with. Resets current search position to zero.
    Parameters:
      `text` - - a data
    See Also:
      `setTarget(jregex.Matcher,int)`, `setTarget(java.lang.String,int,int)`, `setTarget(char[],int,int)`, `setTarget(java.io.Reader,int)`

  ### setTarget

      public void setTarget(java.lang.String text,
                            int start,
                            int len)

    Supplies a text to search in/match with, as a part of String. Resets current search position to zero.
    Parameters:
      `text` - - a data source
      `start` - - where the target starts
      `len` - - how long is the target
    See Also:
      `setTarget(jregex.Matcher,int)`, `setTarget(java.lang.String)`, `setTarget(char[],int,int)`, `setTarget(java.io.Reader,int)`

  ### setTarget

      public void setTarget(char[] text,
                            int start,
                            int len)

    Supplies a text to search in/match with, as a part of char array. Resets current search position to zero.
    Parameters:
      `text` - - a data source
      `start` - - where the target starts
      `len` - - how long is the target
    See Also:
      `setTarget(jregex.Matcher,int)`, `setTarget(java.lang.String)`, `setTarget(java.lang.String,int,int)`, `setTarget(java.io.Reader,int)`

  ### setTarget

      public final void setTarget(char[] text,
                                  int start,
                                  int len,
                                  boolean shared)

    To be used with much care. Supplies a text to search in/match with, as a part of a char array, as above, but also allows to permit to use the array as internal buffer for subsequent inputs. That is, if we call it with `shared=false`:

           myMatcher.setTarget(myCharArray,x,y,false); //we declare that array contents is NEITHER shared NOR will be used later, so may modifications on it are permitted

    then we should expect the array contents to be changed on subsequent setTarget(..) operations. Such method may yield some increase in perfomanse in the case of multiple setTarget() calls. Resets current search position to zero.
    Parameters:
      `text` - - a data source
      `start` - - where the target starts
      `len` - - how long is the target
      `shared` - - if `true`: data are shared or used later, don't modify it; if `false`: possible modifications of the text on subsequent `setTarget()` calls are perceived and allowed.````
    See Also:
      `setTarget(jregex.Matcher,int)`, `setTarget(java.lang.String)`, `setTarget(java.lang.String,int,int)`, `setTarget(char[],int,int)`, `setTarget(java.io.Reader,int)`

  ### setTarget

      public void setTarget(java.io.Reader in,
                            int len)
                     throws java.io.IOException

    Supplies a text to search in/match with through a stream. Resets current search position to zero.
    Parameters:
      `in` - - a data stream;
      `len` - - how much characters should be read; if len is -1, read the entire stream.
    See Also:
      `setTarget(jregex.Matcher,int)`, `setTarget(java.lang.String)`, `setTarget(java.lang.String,int,int)`, `setTarget(char[],int,int)`

  ### matchesPrefix

      public final boolean matchesPrefix()

    Tells whether the entire target matches the beginning of the pattern. The whole pattern is also regarded as its beginning.
    This feature allows to find a mismatch by examining only a beginning part of the target (as if the beginning of the target doesn't match the beginning of the pattern, then the entire target also couldn't match).
    For example the following assertions yield `true`:

           Pattern p=new Pattern("abcd");
           p.matcher("").matchesPrefix();
           p.matcher("a").matchesPrefix();
           p.matcher("ab").matchesPrefix();
           p.matcher("abc").matchesPrefix();
           p.matcher("abcd").matchesPrefix();

    and the following yield `false`:

           p.matcher("b").isPrefix();
           p.matcher("abcdef").isPrefix();
           p.matcher("x").isPrefix();

    ````
    Returns:
      true if the entire target matches the beginning of the pattern

  ### isStart

      public final boolean isStart()

    Deprecated. Replaced by isPrefix()

    Just an old name for isPrefix().
    Retained for backwards compatibility.

  ### matches

      public final boolean matches()

    Tells whether a current target matches the whole pattern. For example the following yields the `true`:

           Pattern p=new Pattern("\\w+");
           p.matcher("a").matches();
           p.matcher("ab").matches();
           p.matcher("abc").matches();

    and the following yields the `false`:

           p.matcher("abc def").matches();
           p.matcher("bcd ").matches();
           p.matcher(" bcd").matches();
           p.matcher("#xyz#").matches();

    ````
    Returns:
      whether a current target matches the whole pattern.

  ### matches

      public final boolean matches(java.lang.String s)

    Just a combination of setTarget(String) and matches().
    Parameters:
      `s` - the target string;
    Returns:
      whether the specified string matches the whole pattern.

  ### setPosition

      public void setPosition(int pos)

    Allows to set a position the subsequent find()/find(int) will start from.
    Parameters:
      `pos` - the position to start from;
    See Also:
      `find()`, `find(int)`

  ### find

      public final boolean find()

    Searches through a target for a matching substring, starting from just after the end of last match. If there wasn't any search performed, starts from zero.
    Returns:
      `true` if a match found.

  ### find

      public final boolean find(int anchors)

    Searches through a target for a matching substring, starting from just after the end of last match. If there wasn't any search performed, starts from zero.
    Parameters:
      `anchors` - a zero or a combination(bitwise OR) of ANCHOR_START,ANCHOR_END,ANCHOR_LASTMATCH,ACCEPT_INCOMPLETE
    Returns:
      `true` if a match found.

  ### findAll

      public MatchIterator findAll()

    The same as findAll(int), but with default behaviour;

  ### findAll

      public MatchIterator findAll(int options)

    Returns an iterator over the matches found by subsequently calling find(options), the search starts from the zero position.

  ### proceed

      public final boolean proceed()

    Continues to search from where the last search left off. The same as proceed(0).
    See Also:
      `proceed(int)`

  ### proceed

      public final boolean proceed(int options)

    Continues to search from where the last search left off using specified options:

         Matcher m=new Pattern("\\w+").matcher("abc");
         while(m.proceed(0)){
            System.out.println(m.group(0));
         }

    Output:

         abc
         ab
         a
         bc
         b
         c

    For example, let's find all odd nubmers occuring in a text:

            Matcher m=new Pattern("\\d+").matcher("123");
            while(m.proceed(0)){
               String match=m.group(0);
               if(isOdd(Integer.parseInt(match))) System.out.println(match);
            }

            static boolean isOdd(int i){
               return (i&1)>0;
            }

    This outputs:

         123
         1
         23
         3

    Note that using `find()` method we would find '123' only.
    Parameters:
      `options` - search options, some of ANCHOR_START|ANCHOR_END|ANCHOR_LASTMATCH|ACCEPT_INCOMPLETE; zero value(default) stands for usual search for substring.

  ### skip

      public final void skip()

    Sets the current search position just after the end of last match.

  ### toString

      public java.lang.String toString()

    Overrides:
      `toString` in class `java.lang.Object`

  ### pattern

      public Pattern pattern()

    Specified by:
      `pattern` in interface `MatchResult`

  ### target

      public java.lang.String target()

    Specified by:
      `target` in interface `MatchResult`

  ### targetChars

      public char[] targetChars()

    Specified by:
      `targetChars` in interface `MatchResult`

  ### targetStart

      public int targetStart()

    Specified by:
      `targetStart` in interface `MatchResult`

  ### targetEnd

      public int targetEnd()

    Specified by:
      `targetEnd` in interface `MatchResult`

  ### charAt

      public char charAt(int i)

    Specified by:
      `charAt` in interface `MatchResult`

  ### charAt

      public char charAt(int i,
                         int groupId)

    Specified by:
      `charAt` in interface `MatchResult`

  ### length

      public final int length()

    Specified by:
      `length` in interface `MatchResult`

  ### start

      public final int start()

    Specified by:
      `start` in interface `MatchResult`

  ### end

      public final int end()

    Specified by:
      `end` in interface `MatchResult`

  ### prefix

      public java.lang.String prefix()

    Specified by:
      `prefix` in interface `MatchResult`

  ### suffix

      public java.lang.String suffix()

    Specified by:
      `suffix` in interface `MatchResult`

  ### groupCount

      public int groupCount()

    Specified by:
      `groupCount` in interface `MatchResult`

  ### group

      public java.lang.String group(int n)

    Specified by:
      `group` in interface `MatchResult`

  ### group

      public java.lang.String group(java.lang.String name)

    Specified by:
      `group` in interface `MatchResult`

  ### getGroup

      public boolean getGroup(int n,
                              TextBuffer tb)

    Specified by:
      `getGroup` in interface `MatchResult`

  ### getGroup

      public boolean getGroup(java.lang.String name,
                              TextBuffer tb)

    Specified by:
      `getGroup` in interface `MatchResult`

  ### getGroup

      public boolean getGroup(int n,
                              java.lang.StringBuffer sb)

    Specified by:
      `getGroup` in interface `MatchResult`

  ### getGroup

      public boolean getGroup(java.lang.String name,
                              java.lang.StringBuffer sb)

    Specified by:
      `getGroup` in interface `MatchResult`

  ### groups

      public java.lang.String[] groups()

  ### groupv

      public java.util.Vector groupv()

  ### isCaptured

      public final boolean isCaptured()

    Specified by:
      `isCaptured` in interface `MatchResult`

  ### isCaptured

      public final boolean isCaptured(int id)

    Specified by:
      `isCaptured` in interface `MatchResult`

  ### isCaptured

      public final boolean isCaptured(java.lang.String groupName)

    Specified by:
      `isCaptured` in interface `MatchResult`

  ### length

      public final int length(int id)

    Specified by:
      `length` in interface `MatchResult`

  ### start

      public final int start(int id)

    Specified by:
      `start` in interface `MatchResult`

  ### end

      public final int end(int id)

    Specified by:
      `end` in interface `MatchResult`

  ### toString_d

      public java.lang.String toString_d()

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