Matcher (RegExodus 0.1.3)

java.lang.Object
- regexodus.Matcher

All Implemented Interfaces:

MatchResult
```
public class Matcher
extends Object
implements MatchResult
```
Matcher is an automaton that actually performs matching. It provides the following methods:
- searching for a matching sub-strings : 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 succeeded, 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.
You typically obtain a Matcher through a Pattern instance's matcher() method. See the Pattern documentation for the normal ways to create a Pattern; if you are already familiar with java.util.regex.Pattern, constructing a regexodus Pattern should be no different.
Matcher (and Pattern) objects are not thread-safe, so only one thread may use a matcher instance at a time.

Field Summary
- Fields inherited from interface regexodus.MatchResult
  MATCH, PREFIX, SUFFIX, TARGET

Constructor Summary

Constructors
Constructor and Description

Matcher(Pattern regex)

Constructors
Constructor and Description
`Matcher(Pattern regex)`

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`char`	`charAt(int i)`
`char`	`charAt(int i, int groupId)`
`int`	`end()`
`int`	`end(int id)`
`boolean`	`equals(Object o)`
`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.
`void`	`flush()` Resets the internal state.
`boolean`	`getGroup(int n, StringBuilder sb)`
`boolean`	`getGroup(int n, TextBuffer tb)`
`boolean`	`getGroup(String name, StringBuilder sb)`
`boolean`	`getGroup(String name, TextBuffer tb)`
`String`	`getString(int start, int end)`
`String`	`group(int n)`
`String`	`group(String name)`
`int`	`groupCount()`
`String[]`	`groups()`
`ArrayList<String>`	`groupv()`
`int`	`hashCode()`
`boolean`	`isCaptured()`
`boolean`	`isCaptured(int id)`
`boolean`	`isCaptured(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(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()`
`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:
`String`	`replaceAll(String replacement)`
`String`	`replaceAmount(String replacement, int amount)`
`String`	`replaceFirst(String replacement)`
`boolean`	`search(int anchors)`
`void`	`setAll(Reader in)`
`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(CharSequence text)` Supplies a text to search in/match with.
`void`	`setTarget(CharSequence text, int start, int len)` Supplies a text to search in/match with, as a part of String.
`void`	`setTarget(Matcher m, int groupId)` This method allows to efficiently pass data between matchers.
`void`	`setTarget(Reader in, int len)` Supplies a text to search in/match with through a stream.
`void`	`skip()` Sets the current search position just after the end of last match.
`int`	`start()`
`int`	`start(int id)`
`String`	`suffix()`
`String`	`target()`
`char[]`	`targetChars()`
`int`	`targetEnd()`
`int`	`targetStart()`
`String`	`toString()`

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

- Constructor Detail
  - Matcher
```
public Matcher(Pattern regex)
```
- 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.CharSequence), setTarget(java.lang.CharSequence, int, int), setTarget(char[], int, int), setTarget(java.io.Reader, int)
  - setTarget
```
public void setTarget(CharSequence text)
```
    Supplies a text to search in/match with. Resets current search position to zero.
    
    Parameters:
    
    text - - a data
    
    See Also:
    
    setTarget(regexodus.Matcher, int), setTarget(java.lang.CharSequence, int, int), setTarget(char[], int, int), setTarget(java.io.Reader, int)
  - setTarget
```
public void setTarget(CharSequence 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(regexodus.Matcher, int), setTarget(java.lang.CharSequence), 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(regexodus.Matcher, int), setTarget(java.lang.CharSequence), setTarget(java.lang.CharSequence, int, int), setTarget(java.io.Reader, int)
  - setTarget
```
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. 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 perfomance 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(regexodus.Matcher, int), setTarget(java.lang.CharSequence), setTarget(java.lang.CharSequence, int, int), setTarget(char[], int, int), setTarget(java.io.Reader, int)
  - setTarget
```
public void setTarget(Reader in,
                      int len)
               throws 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.
    
    Throws:
    
    IOException
    
    See Also:
    
    setTarget(regexodus.Matcher, int), setTarget(java.lang.CharSequence), setTarget(java.lang.CharSequence, int, int), setTarget(char[], int, int)
  - setAll
```
public void setAll(Reader in)
            throws IOException
```
    Throws:
    
    IOException
  - getString
```
public String getString(int start,
                        int end)
```
  - 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(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 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 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 numbers occurring 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 void skip()
```
    Sets the current search position just after the end of last match.
  - flush
```
public void flush()
```
    Resets the internal state.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - pattern
```
public Pattern pattern()
```
    Specified by:
    
    pattern in interface MatchResult
  - target
```
public 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 String prefix()
```
    Specified by:
    
    prefix in interface MatchResult
  - suffix
```
public String suffix()
```
    Specified by:
    
    suffix in interface MatchResult
  - groupCount
```
public int groupCount()
```
    Specified by:
    
    groupCount in interface MatchResult
  - group
```
public String group(int n)
```
    Specified by:
    
    group in interface MatchResult
  - group
```
public String group(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(String name,
                        TextBuffer tb)
```
    Specified by:
    
    getGroup in interface MatchResult
  - getGroup
```
public boolean getGroup(int n,
                        StringBuilder sb)
```
    Specified by:
    
    getGroup in interface MatchResult
  - getGroup
```
public boolean getGroup(String name,
                        StringBuilder sb)
```
    Specified by:
    
    getGroup in interface MatchResult
  - groups
```
public String[] groups()
```
  - groupv
```
public ArrayList<String> 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(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
  - search
```
public boolean search(int anchors)
```
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - replaceFirst
```
public String replaceFirst(String replacement)
```
  - replaceAmount
```
public String replaceAmount(String replacement,
                            int amount)
```
  - replaceAll
```
public String replaceAll(String replacement)
```

Class Matcher

Field Summary

Fields inherited from interface regexodus.MatchResult

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Matcher

Method Detail

setTarget

setTarget

setTarget

setTarget

setTarget

setTarget

setAll

getString

matchesPrefix

isStart

matches

matches

setPosition

find

find

findAll

findAll

proceed

proceed

skip

flush

toString

pattern

target

targetChars

targetStart

targetEnd

charAt

charAt

length

start

end

prefix

suffix

groupCount

group

group

getGroup

getGroup

getGroup

getGroup

groups

groupv

isCaptured

isCaptured

isCaptured

length

start

end

search

equals

hashCode

replaceFirst

replaceAmount

replaceAll