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)
              For wise people only.
     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)
    For wise people only. 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 being 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