Text of docs.oracle.com › en › java › javase › 13 › 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 2019-08-06 Introduction Using Text Blocks Preview Feature 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 Style Guidelines For Text Blocks Preview String Methods String formatted(Object... args) String stripIndent() String translateEscapes() References JEP 355 introduces text blocks into Java SE 13 as a Preview feature.

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 Preview Feature Text blocks exist as a Preview feature of the Java Language.

In order to use text blocks in Java code, you must use the --enable-preview and -source 13 flags on the javac command line and the --enable-preview flag on the java command line: javac --enable-preview -source 13 -d classes TextBlockExample.java java --enable-preview -cp classes com.example.TextBlockExample Using jshell to experiment with text blocks requires using the --enable-preview flag as well: jshell --enable-preview Use --enable-preview and --source flags (note: two hyphens) with the java command to compile and run a single source file with a main program: java --enable-preview --source 13 TextBlockExample.java (Single-file source code programs are described in JEP 330 .) 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 th

The rest of this page is on the live site.