Text of docs.oracle.com › en › java › javase › 15 › text-blocks › index.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Programmer's Guide to Text Blocks

Programmer's Guide to Text Blocks Jim Laskey Stuart Marks 2020-09-15 Introduction Using Text Blocks Text Block Syntax That Final New Line Incidental White Space Trailing White Space Detecting Potential Issues with White Space Normalization Of Line Terminators Translation Of Escape Sequences New Escape Sequences Style Guidelines For Text Blocks String Methods Related to Text Blocks String formatted(Object... args) String stripIndent() String translateEscapes() References JEP 378 adds the language feature text blocks to Java SE 15 and later.

While the JEP explains the feature in great detail, it's not always apparent how the feature can and should be used. This guide assembles practical usage advice for text blocks, along with some style guidelines. Introduction A text block's principalis munus is to provide clarity by way of minimizing the Java syntax required to render a string that spans multiple lines. In earlier releases of the JDK, embedding multi-line code snippets required a tangled mess of explicit line terminators, string concatenations, and delimiters.

Text blocks eliminate most of these obstructions, allowing you to embed code snippets and text sequences more or less as-is. A text block is an alternative form of Java string representation that can be used anywhere a traditional double quoted string literal can be used. For example: // Using a literal string String dqName = "Pat Q. Smith"; // Using a text block String tbName = """ Pat Q. Smith"""; The object produced from a text block is a java.lang.String with the same characteristics as a traditional double quoted string.

This includes object representation and interning. Continuing with dqName and tbName from the examples above, // Both dqName and tbName are strings of equal value dqName.equals(tbName) // true // Both dqName and tbName intern to the same string dqName == tbName // true Text blocks can be used anywhere a string literal can be used. For example, text blocks may be intermixed with string literals in a string concatentation expression: String str = "The old"; String tb = """ the new"""; String together = str + " and " + tb + "."; Text blocks may be used as a method argument: System.out.println(""" This is the first line This is the second line This is the third line """); String methods may be applied to a text block: """ John Q.

Smith""".substring(8).equals("Smith") // true A text block can be used in place of a string literal to improve the readability and clarity of the code. This primarily occurs when a string literal is used to represent a multi-line string. In this case there is considerable clutter from quotation marks, newline escapes, and concatentation operators: // ORIGINAL String message = "'The time has come,' the Walrus said,\n" + "'To talk of many things:\n" + "Of shoes -- and ships -- and sealing-wax --\n" + "Of cabbages -- and kings --\n" + "And why the sea is boiling hot --\n" + "And whether pigs have wings.'\n"; Using text blocks removes much of the clutter: // BETTER String message = """ 'The time has come,' the Walrus said, 'To talk of many things: Of shoes -- and ships -- and sealing-wax -- Of cabbages -- and kings -- And why the sea is boiling hot -- And whether pigs have wings.' """; Using Text Blocks Text Block Syntax A text block begins with three double-quote characters followed by a line terminator.

You can't put a text block on a single line, nor can the contents of the text block follow the three opening double-quotes without an intervening line terminator. The reason for this is that text blocks are primarily designed to support multi-line strings, and requiring the initial line terminator simplifies the indentation handling rules (see the section below, Incidental White Space ). // ERROR String name = """Pat Q.

Smith"""; // ERROR String name = """red green blue """; // OK String name = """ red green blue """; This last example is equivalent to the following string literal: String name = "red\n" + "green\n" + "blue\n"; Here's an example of a snippet of Java code within a text block: String source = """ String message = "Hello, World!"; System.out.println(message); """; Note that there is no need to escape the embedded double quotes.

The equivalent string literal would be: String source = "String message = \"Hello, World!\";\n" + "System.out.println(message);\n"; That Final New Line Note that the example above, String name = """ red green blue """; is equivalent to "red\ngreen\nblue\n" . What if you want to represent a multi-line string without that final \n ? String name = """ red green blue"""; This text block is equivalent to is "red\ngreen\nblue" .

Thus, placing the closing delimiter on the last visible line effectively drops the last \n . Incidental White Space Ideally, a text block would be indented to match the indentation of the surrounding code. For example: void writeHTML() { String html = """ <html> <body> <p>Hello World.</p> </body> </html> """; writeOutput(html); } However, this raises the question of how spaces used for indentation affect the contents of the string.

A naïve interpretation would include all of this whitespace in the text block. The consequence would be that reindenting the code would affect the contents of the text block. This is quite likely to be an error. To avoid this problem, a text block differentiates incidental white space from essential white space. The Java compiler automatically strips away the incidental white space. The indentation to the left of <html> and </html> is considered incidental, since these lines are indented the least.

Thus, they effectively determine the left margin of the text in the text block. However, the indentation of <body> relative to <html> is not considered to be incidental white space. Presumably, this relative indentation is intended to be part of the string's contents. The example below uses " · " to visualize the incidental white space, with essential white space shown as actual white space. void writeHTML() { String html = """ ········<html> ········ <body> ········ <p>Hello World.</p> ········ </body> ········</html> ········"""; writeOutput(html); } After the incidental white space is stripped, the resulting contents of the text block are as follows: <html> <body> <p>Hello World.</p> </body> </html> The algorithm for determining incidental white space is described in JEP 355 in scary detail.

Nevertheless, the net effect is quite simple. The entire contents of the text block is shifted to the left until the line with the least leading white space has no leading white space. To preserve some white space and not have it be considered incidental white space, simply shift the content lines of the text block to the right, while keeping the closing triple-quote delimiter at the indentation appropriate for the surrounding code.

For example: void writeHTML() { String html = """ ········ <html> ········ <body> ········ <p>Hello World.</p> ········ </body> ········ </html> ········"""; writeOutput(html); } results in the following: <html> <body> <p>Hello World.</p> </body> </html> A text block can opt out of incidental white space stripping by positioning the closing delimiter in the first character position of a source line: void writeHTML() { String html = """ <html> <body> <p>Hello World.</p> </body> </html> """; writeOutput(html); } The result is that there is no incidental white space that is stripped, and the string includes leading white space on each line. <html> <body> <p>Hello World.</p> </body> </html> This technique for controlling the amount of indentation that is preserved only works if the last line of the text block ends with a line terminator.

If the last line does not end with a line terminator, you need to use String::indent to control the indentation explicitly. In the following example, String colors = """ red green blue"""; all of the indentation is treated as inci

The rest of this page is on the live site.