| java.lang.Object
 jregex.Matcher
| Matcher | | public class Matcher implements MatchResult(Code) | | 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 | |
| final public static int | ACCEPT_INCOMPLETE
Experimental option; if a text ends up before the end of a pattern,report a match. | | final public static int | ANCHOR_END
The same effect as "$" without REFlags.MULTILINE. | | final public static int | ANCHOR_LASTMATCH
The same effect as "\\G". | | final public static int | ANCHOR_START
The same effect as "^" without REFlags.MULTILINE. |
| Method Summary | |
| public char | charAt(int i)
| | public char | charAt(int i, int groupId)
| | final public int | end()
| | final public int | end(int id)
| | final public boolean | find()
Searches through a target for a matching substring, starting from just after the end of last match. | | final public boolean | find(int anchors)
Searches through a target for a matching substring, starting from just after the end of last match. | | public MatchIterator | 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. | | public boolean | getGroup(int n, TextBuffer tb)
| | public boolean | getGroup(String name, TextBuffer tb)
| | public boolean | getGroup(int n, StringBuffer sb)
| | public boolean | getGroup(String name, StringBuffer sb)
| | public String | group(int n)
| | public String | group(String name)
| | public int | groupCount()
| | public String[] | groups()
| | public Vector | groupv()
| | final public boolean | isCaptured()
| | final public boolean | isCaptured(int id)
| | final public boolean | isCaptured(String groupName)
| | final public boolean | isStart()
Just an old name for isPrefix().
Retained for backwards compatibility. | | final public int | length()
| | final public int | length(int id)
| | final public boolean | matches()
Tells whether a current target matches the whole pattern. | | final public boolean | matches(String s)
Just a combination of setTarget(String) and matches(). | | final public boolean | matchesPrefix()
Tells whether the entire target matches the beginning of the pattern. | | public Pattern | pattern()
| | public String | prefix()
| | final public boolean | proceed()
Continues to search from where the last search left off. | | final public 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. | | public void | setOffset(int offset)
| | public void | setPosition(int pos)
Allows to set a position the subsequent find()/find(int) will start from. | | final public void | setTarget(Matcher m, int groupId)
This method allows to efficiently pass data between matchers. | | public void | setTarget(String text)
Supplies a text to search in/match with. | | public void | setTarget(String text, int start, int len)
Supplies a text to search in/match with, as a part of String. | | public void | setTarget(char[] text, int start, int len)
Supplies a text to search in/match with, as a part of char array. | | final public 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. | | public void | setTarget(Reader in, int len)
Supplies a text to search in/match with through a stream. | | final public void | skip()
Sets the current search position just after the end of last match. | | final public int | start()
| | final public int | start(int id)
| | public String | suffix()
| | public String | target()
| | public char[] | targetChars()
| | public int | targetEnd()
| | public int | targetStart()
| | public String | toString()
| | public String | toString_d()
|
| ACCEPT_INCOMPLETE | | final public static int ACCEPT_INCOMPLETE(Code) | | Experimental option; if a text ends up before the end of a pattern,report a match.
See Also: Matcher.find(int) |
| ANCHOR_END | | final public static int ANCHOR_END(Code) | | The same effect as "$" without REFlags.MULTILINE.
See Also: Matcher.find(int) |
| ANCHOR_LASTMATCH | | final public static int ANCHOR_LASTMATCH(Code) | | The same effect as "\\G".
See Also: Matcher.find(int) |
| ANCHOR_START | | final public static int ANCHOR_START(Code) | | The same effect as "^" without REFlags.MULTILINE.
See Also: Matcher.find(int) |
| charAt | | public char charAt(int i)(Code) | | |
| charAt | | public char charAt(int i, int groupId)(Code) | | |
| end | | final public int end()(Code) | | |
| end | | final public int end(int id)(Code) | | |
| find | | final public boolean find()(Code) | | 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.
true if a match found. |
| find | | final public boolean find(int anchors)(Code) | | 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 true if a match found. |
| findAll | | public MatchIterator findAll()(Code) | | The same as findAll(int), but with default behaviour;
|
| findAll | | public MatchIterator findAll(int options)(Code) | | Returns an iterator over the matches found by subsequently calling find(options), the search starts from the zero position.
|
| groupCount | | public int groupCount()(Code) | | |
| isCaptured | | final public boolean isCaptured()(Code) | | |
| isCaptured | | final public boolean isCaptured(int id)(Code) | | |
| isCaptured | | final public boolean isCaptured(String groupName)(Code) | | |
| isStart | | final public boolean isStart()(Code) | | Just an old name for isPrefix().
Retained for backwards compatibility.
|
| length | | final public int length()(Code) | | |
| length | | final public int length(int id)(Code) | | |
| matches | | final public boolean matches()(Code) | | 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();
whether a current target matches the whole pattern. |
| matches | | final public boolean matches(String s)(Code) | | Just a combination of setTarget(String) and matches().
Parameters:
s - the target string; whether the specified string matches the whole pattern. |
| matchesPrefix | | final public boolean matchesPrefix()(Code) | | 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();
true if the entire target matches the beginning of the pattern |
| proceed | | final public boolean proceed()(Code) | | Continues to search from where the last search left off.
The same as proceed(0).
See Also: Matcher.proceed(int) |
| proceed | | final public boolean proceed(int options)(Code) | | 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. |
| setOffset | | public void setOffset(int offset)(Code) | | |
| setPosition | | public void setPosition(int pos)(Code) | | Allows to set a position the subsequent find()/find(int) will start from.
Parameters:
pos - the position to start from;
See Also: Matcher.find
See Also: Matcher.find(int) |
| setTarget | | final public void setTarget(char[] text, int start, int len, boolean shared)(Code) | | 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
Parameters:
start - - where the target starts
Parameters:
len - - how long is the target
Parameters:
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: Matcher.setTarget(jregex.Matcherint)
See Also: Matcher.setTarget(java.lang.String)
See Also: Matcher.setTarget(java.lang.Stringintint)
See Also: Matcher.setTarget(char[]intint)
See Also: Matcher.setTarget(java.io.Readerint) |
| skip | | final public void skip()(Code) | | Sets the current search position just after the end of last match.
|
| start | | final public int start()(Code) | | |
| start | | final public int start(int id)(Code) | | |
| targetChars | | public char[] targetChars()(Code) | | |
| targetEnd | | public int targetEnd()(Code) | | |
| targetStart | | public int targetStart()(Code) | | |
|
|