Class Matcher

└ Object

Represents the process of scanning a string for matches to a regular expression. Matcher objects are created by RegularExpression to scan particular strings, and return matches one at a time.

Source Code:: View Source

Field Summary

start:Index: Returns the index of the beginning of the last match located by find().
end:Index: Returns the index of the end of the last match located by find().
groupCount:Int: Returns the number of groups contained in the match.

Inherited Fields:

toString

Instance Method Summary

matches():Bit: Checks to see if the regular expression matches the entire string.
find():Bit: Returns the next occurrence of the matcher's regular expression within the string, starting just past the last match (or at the beginning of the string, if this is the first call to find()).
find(start:Index):Bit: Returns the first occurrence of the matcher's regular expression within the string starting at the character start.
appendReplacement(target:MutableString, replacement:String): After a successful match, appends a replacement for the match to a MutableString.
appendReplacement(target:MutableString, replacement:String, allowGroupReferences:Bit): As appendReplacement(MutableString, String), but allows the interpretation of $1-style group references to be controlled.
appendTail(target:MutableString): Appends all remaining unmatched text to the target MutableString.
group(index:Int):String?: Returns the contents of the indicated match group.

Fields

property start:Index

Returns the index of the beginning of the last match located by find(). It is a safety violation to read this property unless the last call to matches() or find() was successful.

property end:Index

Returns the index of the end of the last match located by find(). It is a safety violation to read this property unless the last call to matches() or find() was successful.

property groupCount:Int

Returns the number of groups contained in the match. This is always at least 1, as group zero represents the entire matched text. It is a safety violation to read this property unless the last call to matches() or find() was successful.

Instance Methods


method matches

():Bit

Checks to see if the regular expression matches the entire string. While find() tolerates additional unmatched text before or after the match, matches() does not.

@pre(matched | replacementIndex = searchText.start)

method find

():Bit

Returns the next occurrence of the matcher's regular expression within the string, starting just past the last match (or at the beginning of the string, if this is the first call to find()). Returns a Bit indicating whether or not a match was found. Use start, end, and group(Int) for more information about the match.

Returns:: true if a match was found

See also:: matches()
find(String.Index)


method find

(start:Index
):Bit

Returns the first occurrence of the matcher's regular expression within the string starting at the character start. Returns whether or not a match was found. Use start, end, and group(Int) for more information about the match.

Parameters:: start - the index to start the search at

Returns:: true if a match was found

See also:: matches()
find()

@pre(matched)

method appendReplacement

(target:MutableString,
 replacement:String)

After a successful match, appends a replacement for the match to a MutableString. The text appended to the MutableString will include all unmatched characters between the last match and the current match, and the replacement string may include references to match groups using the syntax $1, $2, etc.

appendReplacement is intended to be used in a loop with find() and completed with appendTail(), such as in this example:

def result := MutableString()
def regex := /\s+/ -- match all whitespace
def matcher := regex.matcher("Hello, can anyone hear me?")
while matcher.find() {
    matcher.appendReplacement(result, "|")
}
matcher.appendTail(result)
Console.printLine(result)

Try it!

This will display the text "Hello,|can|anyone|hear|me?".

Parameters:: target - the MutableString to append to
replacement - the replacement string, optionally containing $1-style group references

@pre(matched)

method appendReplacement

(target:MutableString,
 replacement:String,
 allowGroupReferences:Bit)

As appendReplacement(MutableString, String), but allows the interpretation of $1-style group references to be controlled. With allowGroupReferences set to false, the replacement string is treated literally, with no special handling for $1-style sequences.

Parameters:: target - the MutableString to append to
replacement - the replacement string
allowGroupReferences - if false, $1-style group references are ignored


method appendTail

(target:MutableString)

Appends all remaining unmatched text to the target MutableString. See appendReplacement for a usage example.

Parameters:: target - the string to append to

@pre(matched)

function group

(index:Int
):String?

Returns the contents of the indicated match group. Group zero is the entire matched text, and additional groups are defined by parentheses in the regular expression. For example:

def m := /(\d+) plus (\d+) equals (\d+)/.matcher("12 plus 8 equals 20")
if m.matches() {
    for i in 0 .. m.groupCount {
        Console.printLine(m.group(i))
    }
}

Try it!

This will display:

12 plus 8 equals 20
12
8
20

Parameters:: index - value of type Int