Text blocks

A text block is a string literal that spans lines. It starts with three double quotes and a line break, ends with three double quotes, and needs no \n between its lines. Text blocks are final since Java 15, and they exist for the strings that are easier to read as they will be printed: SQL, JSON, HTML and a block of help text.

A text block

The opening delimiter is followed by a line break, and the content starts on the next line. The closing delimiter sits on a line of its own unless the block must end without a newline. Every content line and the closing delimiter share an indentation, and that common part is removed.

The file TextBlock.java:

public class TextBlock { public static void main(String[] args) { String text = """ one two """; System.out.println(text); System.out.println("lines: " + text.lines().count()); System.out.println("length: " + text.length()); } }

javac -Xlint:all TextBlock.java
java TextBlock

one
two

lines: 2
length: 8

The value is the four characters of one, a newline, the three of two and a final newline: eight characters and two lines. println adds one more newline, which is the empty line in the output.

Indentation

The compiler removes the smallest indentation found on a content line or on the closing delimiter, so the block can be indented with the code around it without those spaces reaching the string. The closing delimiter takes part in that decision: it is the line that usually sets the amount.

Moving the closing delimiter to the left strips less, and moving it to the right strips more, including part of the content if a content line is not indented that far. A line that needs more indentation than the rest keeps the difference, which is how the JSON below keeps its nested keys.

JSON as a text block

The double quotes inside a text block need no escape, which is the reason the feature exists. A JSON document written as a block is the document, with its braces and its indentation, and no concatenation of string pieces.

public class Json { public static void main(String[] args) { String json = """ { "name": "Ada", "age": 36, "active": true } """; System.out.println(json); System.out.println("contains: " + json.contains("\"Ada\"")); } }

javac -Xlint:all Json.java
java Json

{
"name": "Ada",
"age": 36,
"active": true
}

contains: true

The block starts with { at the same indentation as the closing delimiter, and the keys keep two extra spaces. The contains call needs the quotes escaped because it is an ordinary string literal, which is the contrast the block was written to show.

Backslash, \s and the line continuation

Escapes work inside a text block as they do in a string, with one addition: a backslash at the end of a line joins it with the next and removes the line break. A trailing \s keeps a space that the indentation stripping would otherwise remove.

public class Escape { public static void main(String[] args) { String joined = """ alpha \ beta \ gamma"""; System.out.println(joined); String spaced = """ name:\s"""; System.out.println("[" + spaced + "]"); } }

javac -Xlint:all Escape.java
java Escape

alpha beta gamma
[name: ]

Every line except the last ends with a backslash, so the three words are joined by single spaces that are written before each backslash. The second block ends with name: and a space that \s makes visible between the brackets.

Exercises

  1. Move the closing delimiter of TextBlock.java to the left by four spaces and run it again. Which lines change?
  2. Write an SQL query as a text block with one condition per line.
  3. Add a line with two extra spaces of indentation to the JSON block and see where they appear in the output.
  4. Remove the \s from Escape.java and compare the brackets.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. How does a text block start?

    Answer

    With three double quotes and a line break

    The opening delimiter is """ followed by a line break; the content begins on the next line.

  2. What decides how much indentation is removed from a text block?

    Answer

    The smallest indentation of a content line or the closing delimiter

    The compiler strips the common indentation, and the closing delimiter usually supplies the smallest one.

  3. What does a backslash at the end of a line inside a text block do?

    Answer

    Joins the line with the next one, without a line break

    The line continuation removes the newline, which is how one logical line is written over several source lines.

  4. What does this program print? public class Q1 { public static void main(String[] args) { String text = """ a b """; System.out.println(text.lines().count()); } }

    Answer

    2

    The value is a newline, b and a final newline, which lines() reads as two lines.

  5. What is the length of this string? public class Q5 { public static void main(String[] args) { String text = """ a b """; System.out.println(text.length()); } }

    Answer

    4

    The characters are a, newline, b and the final newline, four in all.

  6. What does this program print? public class Q2 { public static void main(String[] args) { String text = """ one two"""; System.out.println(text); } }

    Answer

    one / two

    The closing delimiter on the last content line means the block ends without a final newline.

  7. What does \s keep at the end of a line in a text block?

    Answer

    A space that the indentation stripping would remove

    Trailing spaces are stripped from a text block, and \s is the escape that keeps one.

  8. What does this program print? public class Q3 { public static void main(String[] args) { String text = """ x \ y"""; System.out.println(text); } }

    Answer

    x y

    The backslash joins the lines and the space before it is kept, giving one line.

  9. Do double quotes inside a text block need an escape?

    Answer

    No, unless three in a row would end the block

    A lone or paired quote is just a character; the triple quote is the delimiter.

  10. What does the closing delimiter indentation do?

    Answer

    It is part of the common indentation that is stripped

    The delimiter line takes part in the calculation, so its position controls how much is removed.

The code on this page was built with OpenJDK 21.0.13 (javac and java) and run on Alpine Linux in a Docker container.

Article author: Arthur Isaev