string-interpolation.md

title	type	description	languages	num	previous-page	next-page	redirect_from
String Interpolation	chapter	This page provides more information about creating strings and using string interpolation.	ru zh-cn	18	first-look-at-types	control-structures	/overviews/core/string-interpolation.html

Introduction

String interpolation provides a way to use variables inside strings. For instance:

{% tabs example-1 %} {% tab 'Scala 2 and 3' for=example-1 %}

valname="James"valage=30 println(s"$name is $age years old") // "James is 30 years old"

{% endtab %} {% endtabs %}

Using string interpolation consists of putting an s in front of your string quotes, and prefixing any variable names with a $ symbol.

String Interpolators

The s that you place before the string is just one possible interpolator that Scala provides.

Scala provides three string interpolation methods out of the box: s, f and raw. Further, a string interpolator is just a special method, so it is possible to define your own. For instance, some database libraries define a sql interpolator that returns a database query.

The s Interpolator (s-Strings)

Prepending s to any string literal allows the usage of variables directly in the string. You've already seen an example here:

{% tabs example-2 %} {% tab 'Scala 2 and 3' for=example-2 %}

valname="James"valage=30 println(s"$name is $age years old") // "James is 30 years old"

{% endtab %} {% endtabs %}

Here, the $name and $age placeholders in the string are replaced by the results of calling name.toString and age.toString, respectively. The s-String will have access to all variables that are currently in scope.

While it may seem obvious, it's important to note here that string interpolation will not happen in normal string literals:

{% tabs example-3 %} {% tab 'Scala 2 and 3' for=example-3 %}

valname="James"valage=30 println("$name is $age years old") // "$name is $age years old"

{% endtab %} {% endtabs %}

String interpolators can also take arbitrary expressions. For example:

{% tabs example-4 %} {% tab 'Scala 2 and 3' for=example-4 %}

println(s"2 + 2 = ${2+2}") // "2 + 2 = 4"valx=-1 println(s"x.abs = ${x.abs}") // "x.abs = 1"

{% endtab %} {% endtabs %}

Any arbitrary expression can be embedded in ${}.

For some special characters, it is necessary to escape them when embedded within a string. To represent an actual dollar sign you can double it $$, like here:

{% tabs example-5 %} {% tab 'Scala 2 and 3' for=example-5 %}

println(s"New offers starting at $$14.99") // "New offers starting at $14.99"

{% endtab %} {% endtabs %}

Double quotes also need to be escaped. This can be done by using triple quotes as shown:

{% tabs example-6 %} {% tab 'Scala 2 and 3' for=example-6 %}

println(s"""{"name":"James"}""") // `{"name":"James"}`

{% endtab %} {% endtabs %}

Finally, all multi-line string literals can also be interpolated

{% tabs example-7 %} {% tab 'Scala 2 and 3' for=example-7 %}

println(s"""name: "$name", |age: $age""".stripMargin)

This will print as follows:

name: "James" age: 30 

{% endtab %} {% endtabs %}

The f Interpolator (f-Strings)

Prepending f to any string literal allows the creation of simple formatted strings, similar to printf in other languages. When using the f interpolator, all variable references should be followed by a printf-style format string, like %d. Let's look at an example:

{% tabs example-8 %} {% tab 'Scala 2 and 3' for=example-8 %}

valheight=1.9dvalname="James" println(f"$name%s is $height%2.2f meters tall") // "James is 1.90 meters tall"

{% endtab %} {% endtabs %}

The f interpolator is typesafe. If you try to pass a format string that only works for integers but pass a double, the compiler will issue an error. For example:

{% tabs f-interpolator-error class=tabs-scala-version %}

{% tab 'Scala 2' for=f-interpolator-error %}

valheight:Double=1.9d scala>f"$height%4d" <console>:9:error: typemismatch; found : Doublerequired: Intf"$height%4d"^

{% endtab %}

{% tab 'Scala 3' for=f-interpolator-error %}

valheight:Double=1.9d scala>f"$height%4d"--Error:----------------------------------------------------------------------1|f"$height%4d"|^^^^^^|Found: (height : Double), Required:Int, Long, Byte, Short, BigInt1 error found 

{% endtab %} {% endtabs %}

The f interpolator makes use of the string format utilities available from Java. The formats allowed after the % character are outlined in the Formatter javadoc. If there is no % character after a variable definition a formatter of %s (String) is assumed.

Finally, as in Java, use %% to get a literal % character in the output string:

{% tabs literal-percent %} {% tab 'Scala 2 and 3' for=literal-percent %}

println(f"3/19 is less than 20%%") // "3/19 is less than 20%"

{% endtab %} {% endtabs %}

The raw Interpolator

The raw interpolator is similar to the s interpolator except that it performs no escaping of literals within the string. Here's an example processed string:

{% tabs example-9 %} {% tab 'Scala 2 and 3' for=example-9 %}

scala>s"a\nb" res0:String= a b

{% endtab %} {% endtabs %}

Here the s string interpolator replaced the characters \n with a return character. The raw interpolator will not do that.

{% tabs example-10 %} {% tab 'Scala 2 and 3' for=example-10 %}

scala>raw"a\nb" res1:String= a\nb

{% endtab %} {% endtabs %}

The raw interpolator is useful when you want to avoid having expressions like \n turn into a return character.

Furthermore, the raw interpolator allows the usage of variables, which are replaced with their value, just as the s interpolator.

{% tabs example-11 %} {% tab 'Scala 2 and 3' for=example-11 %}

scala>valfoo=42 scala>raw"a\n$foo" res1:String= a\n42

{% endtab %} {% endtabs %}

Advanced Usage

In addition to the three default string interpolators, users can define their own.

The literal s"Hi $name" is parsed by Scala as a processed string literal. This means that the compiler does some additional work to this literal. The specifics of processed strings and string interpolation are described in [SIP-11][sip-11], but here's a quick example to help illustrate how they work.

Custom Interpolators

In Scala, all processed string literals are simple code transformations. Anytime the compiler encounters a processed string literal of the form:

{% tabs example-12 %} {% tab 'Scala 2 and 3' for=example-12 %}

id"string content"

{% endtab %} {% endtabs %}

it transforms it into a method call (id) on an instance of StringContext. This method can also be available on implicit scope. To define our own string interpolation, we need to create an implicit class (Scala 2) or an extension method (Scala 3) that adds a new method to StringContext.

As a trivial example, let's assume we have a simple Point class and want to create a custom interpolator that turns p"a,b" into a Point object.

{% tabs custom-interpolator-1 %} {% tab 'Scala 2 and 3' for=custom-interpolator-1 %}

caseclassPoint(x: Double, y: Double) valpt=p"1,-2"// Point(1.0,-2.0)

{% endtab %} {% endtabs %}

We'd create a custom p-interpolator by first implementing a StringContext extension with something like:

{% tabs custom-interpolator-2 class=tabs-scala-version %}

{% tab 'Scala 2' for=custom-interpolator-2 %}

implicitclassPointHelper(valsc:StringContext) extendsAnyVal { defp(args: Any*):Point=??? }

Note: It's important to extend AnyVal in Scala 2.x to prevent runtime instantiation on each interpolation. See the [value class]({% link _overviews/core/value-classes.md %}) documentation for more.

{% endtab %}

{% tab 'Scala 3' for=custom-interpolator-2 %}

extension (sc: StringContext) defp(args: Any*):Point=???

{% endtab %}

{% endtabs %}

Once this extension is in scope and the Scala compiler encounters p"some string", it will process some string to turn it into String tokens and expression arguments for each embedded variable in the string.

For example, p"1, $someVar" would turn into:

{% tabs extension-desugaring class=tabs-scala-version %}

{% tab 'Scala 2' for=extension-desugaring %}

newStringContext("1, ", "").p(someVar)

The implicit class is then used to rewrite it to the following:

newPointHelper(newStringContext("1, ", "")).p(someVar)

{% endtab %}

{% tab 'Scala 3' for=extension-desugaring %}

StringContext("1, ","").p(someVar)

{% endtab %}

{% endtabs %}

As a result, each of the fragments of the processed String are exposed in the StringContext.parts member, while any expressions values in the string are passed in to the method's args parameter.

Example Implementation

A naive implementation of our Point interpolator method might look something like below, though a more sophisticated method may choose to have more precise control over the processing of the string parts and expression args instead of reusing the s-Interpolator.

{% tabs naive-implementation class=tabs-scala-version %}

{% tab 'Scala 2' for=naive-implementation %}

implicitclassPointHelper(valsc:StringContext) extendsAnyVal { defp(args: Double*):Point= { // reuse the `s`-interpolator and then split on ','valpts= sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) } Point(pts(0), pts(1)) } } valx=12.0p"1, -2"// Point(1.0, -2.0)p"${x/5}, $x"// Point(2.4, 12.0)

{% endtab %}

{% tab 'Scala 3' for=naive-implementation %}

extension (sc: StringContext) defp(args: Double*):Point= { // reuse the `s`-interpolator and then split on ','valpts= sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) } Point(pts(0), pts(1)) } valx=12.0p"1, -2"// Point(1.0, -2.0)p"${x/5}, $x"// Point(2.4, 12.0)

{% endtab %} {% endtabs %}

While string interpolators were originally used to create some form of a String, the use of custom interpolators as above can allow for powerful syntactic shorthand, and the community has already made swift use of this syntax for things like ANSI terminal color expansion, executing SQL queries, magic $"identifier" representations, and many others.

[value-class]: {% link _overviews/core/value-classes.md %} [sip-11]: {% link _sips/sips/string-interpolation.md %}