diff options
author | Daniel C. Sobral <dcsobral@gmail.com> | 2012-01-25 15:34:12 -0200 |
---|---|---|
committer | Daniel C. Sobral <dcsobral@gmail.com> | 2012-03-26 11:27:17 -0300 |
commit | 11cb35986347f6e79813e6c53595bfb872ccefc2 (patch) | |
tree | 01721b5842c510d3a4de7a9a9dcfe0e84dd893b9 | |
parent | 7c0a74ac257cb0be7ef39b2734fa8265266f935e (diff) | |
download | scala-11cb35986347f6e79813e6c53595bfb872ccefc2.tar.gz scala-11cb35986347f6e79813e6c53595bfb872ccefc2.tar.bz2 scala-11cb35986347f6e79813e6c53595bfb872ccefc2.zip |
Document regex replacement strings behavior.
All replacement methods use dolar signs to identify groups in the
matched string, and backslashes to escape characters. Document this
behavior, and provide a method that can be used to properly quote
replacement strings when this behavior is not desired.
Closes SI-4750.
-rw-r--r-- | src/library/scala/util/matching/Regex.scala | 35 | ||||
-rw-r--r-- | test/files/run/si4750.check | 1 | ||||
-rw-r--r-- | test/files/run/si4750.scala | 7 |
3 files changed, 41 insertions, 2 deletions
diff --git a/src/library/scala/util/matching/Regex.scala b/src/library/scala/util/matching/Regex.scala index 37534693c9..76c08a05c0 100644 --- a/src/library/scala/util/matching/Regex.scala +++ b/src/library/scala/util/matching/Regex.scala @@ -132,6 +132,15 @@ import java.util.regex.{ Pattern, Matcher } * * @param regex A string representing a regular expression * @param groupNames A mapping from names to indices in capture groups + * + * @define replacementString + * In the replacement String, a dollar sign (`$`) followed by a number will be + * interpreted as a reference to a group in the matched pattern, with numbers + * 1 through 9 corresponding to the first nine groups, and 0 standing for the + * whole match. Any other character is an error. The backslash (`\`) character + * will be interpreted as an escape character, and can be used to escape the + * dollar sign. One can use [[scala.util.matching.Regex]]'s `quoteReplacement` + * to automatically escape these characters. */ @SerialVersionUID(-2094783597747625537L) class Regex(regex: String, groupNames: String*) extends Serializable { @@ -257,6 +266,8 @@ class Regex(regex: String, groupNames: String*) extends Serializable { /** Replaces all matches by a string. * + * $replacementString + * * @param target The string to match * @param replacement The string that will replace each match * @return The resulting string @@ -279,6 +290,8 @@ class Regex(regex: String, groupNames: String*) extends Serializable { * val repl = datePattern replaceAllIn (text, m => m.group("month")+"/"+m.group("day")) * }}} * + * $replacementString + * * @param target The string to match. * @param replacer The function which maps a match to another string. * @return The target string after replacements. @@ -297,13 +310,15 @@ class Regex(regex: String, groupNames: String*) extends Serializable { * {{{ * import scala.util.matching.Regex._ * - * val map = Map("x" -> "a var", "y" -> "another var") + * val map = Map("x" -> "a var", "y" -> """some $ and \ signs""") * val text = "A text with variables %x, %y and %z." * val varPattern = """%(\w+)""".r - * val mapper = (m: Match) => map get (m group 1) + * val mapper = (m: Match) => map get (m group 1) map (quoteReplacement(_)) * val repl = varPattern replaceSomeIn (text, mapper) * }}} * + * $replacementString + * * @param target The string to match. * @param replacer The function which optionally maps a match to another string. * @return The target string after replacements. @@ -318,6 +333,8 @@ class Regex(regex: String, groupNames: String*) extends Serializable { /** Replaces the first match by a string. * + * $replacementString + * * @param target The string to match * @param replacement The string that will replace the match * @return The resulting string @@ -568,4 +585,18 @@ object Regex { def replace(rs: String) = matcher.appendReplacement(sb, rs) } + + /** Quotes replacement strings to be used in replacement methods. + * + * Replacement methods give special meaning to backslashes (`\`) and + * dollar signs (`$`) in replacement strings, so they are not treated + * as literals. This method escapes these characters so the resulting + * string can be used as a literal replacement representing the input + * string. + * + * @param text The string one wishes to use as literal replacement. + * @return A string that can be used to replace matches with `text`. + * @example {{{"CURRENCY".r.replaceAllIn(input, Regex quoteReplacement "US$")}}} + */ + def quoteReplacement(text: String): String = Matcher quoteReplacement text } diff --git a/test/files/run/si4750.check b/test/files/run/si4750.check new file mode 100644 index 0000000000..bf55f70df3 --- /dev/null +++ b/test/files/run/si4750.check @@ -0,0 +1 @@ +US$ 5.80 diff --git a/test/files/run/si4750.scala b/test/files/run/si4750.scala new file mode 100644 index 0000000000..96d2c4fec7 --- /dev/null +++ b/test/files/run/si4750.scala @@ -0,0 +1,7 @@ +import scala.util.matching.Regex + +object Test extends App { + val input = "CURRENCY 5.80" + println("CURRENCY".r.replaceAllIn(input, Regex quoteReplacement "US$")) +} + |