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.

Author: dcsobral

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 {
@@ -256,6 +265,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
@@ -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.
@@ -317,6 +332,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
@@ -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
 }

test/files/run/si4750.check

@@ -0,0 +1 @@
+US$ 5.80

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$"))
+}
+