A regular expression is used to determine whether a string matches a pattern and, if it does, to extract or transform the parts that match.
Usage
This class delegates to the java.util.regex package of the Java Platform. See the documentation for java.util.regex.Pattern for details about the regular expression syntax for pattern strings.
An instance of Regex represents a compiled regular expression pattern. Since compilation is expensive, frequently used Regexes should be constructed once, outside of loops and perhaps in a companion object.
The canonical way to create a Regex is by using the method r, provided implicitly for strings:
val date = raw"(\d{4})-(\d{2})-(\d{2})".r
Since escapes are not processed in multi-line string literals, using triple quotes avoids having to escape the backslash character, so that "\\d" can be written """\d""". The same result is achieved with certain interpolators, such as raw"\d".r or a custom interpolator r"\d" that also compiles the Regex.
Extraction
To extract the capturing groups when a Regex is matched, use it as an extractor in a pattern match:
"2004-01-20" match {
case date(year, month, day) => s"$year was a good year for PLs."
}
To check only whether the Regex matches, ignoring any groups, use a sequence wildcard:
"2004-01-20" match {
case date(_*) => "It's a date!"
}
That works because a Regex extractor produces a sequence of strings. Extracting only the year from a date could also be expressed with a sequence wildcard:
"2004-01-20" match {
case date(year, _*) => s"$year was a good year for PLs."
}
In a pattern match, Regex normally matches the entire input. However, an unanchored Regex finds the pattern anywhere in the input.
val embeddedDate = date.unanchored
"Date: 2004-01-20 17:25:18 GMT (10 years, 28 weeks, 5 days, 17 hours and 51 minutes ago)" match {
case embeddedDate("2004", "01", "20") => "A Scala is born."
}
Find Matches
To find or replace matches of the pattern, use the various find and replace methods. For each method, there is a version for working with matched strings and another for working with Match objects.
For example, pattern matching with an unanchored Regex, as in the previous example, can also be accomplished using findFirstMatchIn. The findFirst methods return an Option which is non-empty if a match is found, or None for no match:
val dates = "Important dates in history: 2004-01-20, 1958-09-05, 2010-10-06, 2011-07-15"
val firstDate = date.findFirstIn(dates).getOrElse("No date found.")
val firstYear = for (m <- date.findFirstMatchIn(dates)) yield m.group(1)
To find all matches:
val allYears = for (m <- date.findAllMatchIn(dates)) yield m.group(1)
To check whether input is matched by the regex:
date.matches("2018-03-01") // true
date.matches("Today is 2018-03-01") // false
date.unanchored.matches("Today is 2018-03-01") // true
To iterate over the matched strings, use findAllIn, which returns a special iterator that can be queried for the MatchData of the last match:
val mi = date.findAllIn(dates)
while (mi.hasNext) {
val d = mi.next
if (mi.group(1).toInt < 1960) println(s"$d: An oldie but goodie.")
}
Although the MatchIterator returned by findAllIn is used like any Iterator, with alternating calls to hasNext and next, hasNext has the additional side effect of advancing the underlying matcher to the next unconsumed match. This effect is visible in the MatchData representing the "current match".
val r = "(ab+c)".r
val s = "xxxabcyyyabbczzz"
r.findAllIn(s).start // 3
val mi = r.findAllIn(s)
mi.hasNext // true
mi.start // 3
mi.next() // "abc"
mi.start // 3
mi.hasNext // true
mi.start // 9
mi.next() // "abbc"
The example shows that methods on MatchData such as start will advance to the first match, if necessary. It also shows that hasNext will advance to the next unconsumed match, if next has already returned the current match.
The current MatchData can be captured using the matchData method. Alternatively, findAllMatchIn returns an Iterator[Match], where there is no interaction between the iterator and Match objects it has already produced.
Note that findAllIn finds matches that don't overlap. (See findAllIn for more examples.)
val num = raw"(\d+)".r
val all = num.findAllIn("123").toList // List("123"), not List("123", "23", "3")
Replace Text
Text replacement can be performed unconditionally or as a function of the current match:
val redacted = date.replaceAllIn(dates, "XXXX-XX-XX")
val yearsOnly = date.replaceAllIn(dates, m => m.group(1))
val months = (0 to 11).map { i => val c = Calendar.getInstance; c.set(2014, i, 1); f"$c%tb" }
val reformatted = date.replaceAllIn(dates, _ match { case date(y,m,d) => f"${months(m.toInt - 1)} $d, $y" })
Pattern matching the Match against the Regex that created it does not reapply the Regex. In the expression for reformatted, each date match is computed once. But it is possible to apply a Regex to a Match resulting from a different pattern:
val docSpree = """2011(?:-\d{2}){2}""".r
val docView = date.replaceAllIn(dates, _ match {
case docSpree() => "Historic doc spree!"
case _ => "Something else happened"
})
A regular expression is used to determine whether a string matches a pattern and, if it does, to extract or transform the parts that match.
Usage
This class delegates to the java.util.regex package of the Java Platform. See the documentation for java.util.regex.Pattern for details about the regular expression syntax for pattern strings.
An instance of
Regex
represents a compiled regular expression pattern. Since compilation is expensive, frequently usedRegex
es should be constructed once, outside of loops and perhaps in a companion object.The canonical way to create a
Regex
is by using the methodr
, provided implicitly for strings:Since escapes are not processed in multi-line string literals, using triple quotes avoids having to escape the backslash character, so that
"\\d"
can be written"""\d"""
. The same result is achieved with certain interpolators, such asraw"\d".r
or a custom interpolatorr"\d"
that also compiles theRegex
.Extraction
To extract the capturing groups when a
Regex
is matched, use it as an extractor in a pattern match:To check only whether the
Regex
matches, ignoring any groups, use a sequence wildcard:That works because a
Regex
extractor produces a sequence of strings. Extracting only the year from a date could also be expressed with a sequence wildcard:In a pattern match,
Regex
normally matches the entire input. However, an unanchoredRegex
finds the pattern anywhere in the input.Find Matches
To find or replace matches of the pattern, use the various find and replace methods. For each method, there is a version for working with matched strings and another for working with
Match
objects.For example, pattern matching with an unanchored
Regex
, as in the previous example, can also be accomplished usingfindFirstMatchIn
. ThefindFirst
methods return anOption
which is non-empty if a match is found, orNone
for no match:To find all matches:
To check whether input is matched by the regex:
To iterate over the matched strings, use
findAllIn
, which returns a special iterator that can be queried for theMatchData
of the last match:Although the
MatchIterator
returned byfindAllIn
is used like anyIterator
, with alternating calls tohasNext
andnext
,hasNext
has the additional side effect of advancing the underlying matcher to the next unconsumed match. This effect is visible in theMatchData
representing the "current match".The example shows that methods on
MatchData
such asstart
will advance to the first match, if necessary. It also shows thathasNext
will advance to the next unconsumed match, ifnext
has already returned the current match.The current
MatchData
can be captured using thematchData
method. Alternatively,findAllMatchIn
returns anIterator[Match]
, where there is no interaction between the iterator andMatch
objects it has already produced.Note that
findAllIn
finds matches that don't overlap. (See findAllIn for more examples.)Replace Text
Text replacement can be performed unconditionally or as a function of the current match:
Pattern matching the
Match
against theRegex
that created it does not reapply theRegex
. In the expression forreformatted
, eachdate
match is computed once. But it is possible to apply aRegex
to aMatch
resulting from a different pattern:java.util.regex.Pattern