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()