diff options
author | Josh Suereth <joshua.suereth@gmail.com> | 2012-09-26 16:26:30 -0400 |
---|---|---|
committer | Josh Suereth <joshua.suereth@gmail.com> | 2012-09-27 10:43:06 -0400 |
commit | 0d0b03d47e77ac7082818a92a363af9d96618aa6 (patch) | |
tree | 5428fb53fc632aa3abbdf4a80545637de2914188 /src | |
parent | 709bb01175c512d124da9874dcaea50022374715 (diff) | |
download | scala-0d0b03d47e77ac7082818a92a363af9d96618aa6.tar.gz scala-0d0b03d47e77ac7082818a92a363af9d96618aa6.tar.bz2 scala-0d0b03d47e77ac7082818a92a363af9d96618aa6.zip |
Finish docs for string interpolation.
Diffstat (limited to 'src')
-rw-r--r-- | src/library/scala/StringContext.scala | 63 |
1 files changed, 60 insertions, 3 deletions
diff --git a/src/library/scala/StringContext.scala b/src/library/scala/StringContext.scala index 1201b1accd..17c1d0d2ba 100644 --- a/src/library/scala/StringContext.scala +++ b/src/library/scala/StringContext.scala @@ -8,10 +8,43 @@ package scala -/** A class to support string interpolation. - * This class supports string interpolation as outlined in Scala SIP-11. - * It needs to be fully documented once the SIP is accepted. +/** This class provides the basic mechanism to do String Interpolation. + * String Interpolation allows users + * to embed variable references directly in *processed* string literals. + * Here's an example: + * {{{ + * val name = "James" + * println(s"Hello, $name") // Hello, James + * }}} * + * Any processed string literal is rewritten as an instantiation and + * method call against this class. For example: + * {{{ + * s"Hello, $name" + * }}} + * + * is rewritten to be: + * + * {{{ + * new StringContext("Hello, ", "").s(name) + * }}} + * + * By default, this class provides the `raw`, `s` and `f` methods as + * available interpolators. + * + * To provide your own string interpolator, create an implicit class + * which adds a method to `StringContext`. Here's an example: + * {{{ + * implicit class JsonHelper(val sc: StringContext) extends AnyVal { + * def json(args: Any*): JSONObject = ... + * } + * val x: JSONObject = json"{ a: $a }" + * }}} + * + * Here the `JsonHelper` extenion class implicitly adds the `json` method to + * `StringContext` which can be used for `json` string literals. + * + * @since 2.10.0 * @param parts The parts that make up the interpolated string, * without the expressions that get inserted by interpolation. */ @@ -33,6 +66,20 @@ case class StringContext(parts: String*) { * * It inserts its arguments between corresponding parts of the string context. * It also treats standard escape sequences as defined in the Scala specification. + * Here's an example of usage: + * {{{ + * val name = "James" + * println(s"Hello, $name") // Hello, James + * }}} + * In this example, the expression $name is replaced with the `toString` of the + * variable `name`. + * The `s` interpolator can take the `toString` of any arbitrary expression within + * a `${}` block, for example: + * {{{ + * println(s"1 + 1 = ${1 + 1}") + * }}} + * will print the string `1 + 1 = 2`. + * * @param `args` The arguments to be inserted into the resulting string. * @throws An `IllegalArgumentException` * if the number of `parts` in the enclosing `StringContext` does not exceed @@ -47,6 +94,9 @@ case class StringContext(parts: String*) { * It inserts its arguments between corresponding parts of the string context. * As opposed to the simple string interpolator `s`, this one does not treat * standard escape sequences as defined in the Scala specification. + * + * For example, the raw processed string `raw"a\nb"` is equal to the scala string `"a\\nb"`. + * * @param `args` The arguments to be inserted into the resulting string. * @throws An `IllegalArgumentException` * if the number of `parts` in the enclosing `StringContext` does not exceed @@ -76,6 +126,13 @@ case class StringContext(parts: String*) { * that starts with a formatting specifier, the expression is formatted according to that * specifier. All specifiers allowed in Java format strings are handled, and in the same * way they are treated in Java. + * + * For example: + * {{{ + * val height = 1.9d + * val name = "James" + * println(f"$name%s is $height%2.2f meters tall") // James is 1.90 meters tall + * }}} * * @param `args` The arguments to be inserted into the resulting string. * @throws An `IllegalArgumentException` |