diff options
author | Andrew Phillips <demobox1@yahoo.co.uk> | 2014-01-29 23:43:58 -0500 |
---|---|---|
committer | Andrew Phillips <demobox1@yahoo.co.uk> | 2014-02-01 13:11:50 -0500 |
commit | 9c0ca62f53df4bb1ea2b9b1a89a41f185355c400 (patch) | |
tree | a800534e31ce3eb2be6ec6bc2a9497feb5dc7e0d | |
parent | 9956245ac35c4e8bab38dc0b96de999c608ee19a (diff) | |
download | scala-9c0ca62f53df4bb1ea2b9b1a89a41f185355c400.tar.gz scala-9c0ca62f53df4bb1ea2b9b1a89a41f185355c400.tar.bz2 scala-9c0ca62f53df4bb1ea2b9b1a89a41f185355c400.zip |
SI-8215 Documenting the possibility of IllegalStateExceptions when using MatchIterator
See https://groups.google.com/forum/#!topic/scala-language/2T2wKVQiyVg
-rw-r--r-- | src/library/scala/util/matching/Regex.scala | 29 |
1 files changed, 27 insertions, 2 deletions
diff --git a/src/library/scala/util/matching/Regex.scala b/src/library/scala/util/matching/Regex.scala index 1b2def0b55..b70426a145 100644 --- a/src/library/scala/util/matching/Regex.scala +++ b/src/library/scala/util/matching/Regex.scala @@ -67,7 +67,21 @@ import java.util.regex.{ Pattern, Matcher } * Regex, such as `findFirstIn` or `findAllIn`, or using it as an extractor in a * pattern match. * - * Note, however, that when Regex is used as an extractor in a pattern match, it + * Note that, when calling `findAllIn`, the resulting [[scala.util.matching.Regex.MatchIterator]] + * needs to be initialized (by calling `hasNext` or `next()`, or causing these to be + * called) before information about a match can be retrieved: + * + * {{{ + * val msg = "I love Scala" + * + * // val start = " ".r.findAllIn(msg).start // throws an IllegalStateException + * + * val matches = " ".r.findAllIn(msg) + * matches.hasNext // initializes the matcher + * val start = matches.start + * }}} + * + * When Regex is used as an extractor in a pattern match, note that it * only succeeds if the whole text can be matched. For this reason, one usually * calls a method to find the matching substrings, and then use it as an extractor * to break match into subgroups. @@ -267,6 +281,10 @@ class Regex private[matching](val pattern: Pattern, groupNames: String*) extends * that can be queried for data such as the text that precedes the * match, subgroups, etc. * + * Attempting to retrieve information about a match before initializing + * the iterator can result in [[java.lang.IllegalStateException]]s. See + * [[scala.util.matching.Regex.MatchIterator]] for details. + * * @param source The text to match against. * @return A [[scala.util.matching.Regex.MatchIterator]] of all matches. * @example {{{for (words <- """\w+""".r findAllIn "A simple example.") yield words}}} @@ -626,7 +644,14 @@ object Regex { def unapplySeq(m: Match): Option[Seq[String]] = if (m.groupCount > 0) Some(1 to m.groupCount map m.group) else None } - /** A class to step through a sequence of regex matches + /** A class to step through a sequence of regex matches. + * + * All methods inherited from [[scala.util.matching.Regex.MatchData]] will throw + * an [[java.lang.IllegalStateException]] until the matcher is initialized by + * calling `hasNext` or `next()` or causing these methods to be called, such as + * by invoking `toString` or iterating through the iterator's elements. + * + * @see [[java.util.regex.Matcher]] */ class MatchIterator(val source: CharSequence, val regex: Regex, val groupNames: Seq[String]) extends AbstractIterator[String] with Iterator[String] with MatchData { self => |