Summary

This feature introduces a new String instance method to translate escape sequences, such as \n, \t, \', \", and \\, as described in full in section 3.10.6 of the The Java™ Language Specification.

This will be a preview language feature as part of Text Blocks

Problem

The specification of Text Blocks requires that the Java compiler defer processing of escape sequences until after line terminator translation and re-indentation. To provide consistency with the Java Language Specification and long term maintainability, escape translation will be provided by a library method.

Solution

The solution is to provide a new String instance method which adheres to Java™ Language Specification section 3.10.7. This method takes the receiver String and replaces escape sequences with character equivalents. Attempts to translate strings containing invalid escapes sequences raise an IllegalArgumentException.

Specification

    /**
     * Returns a string whose value is this string, with escape sequences
     * translated as if in a string literal.
     * <p>
     * Escape sequences are translated as follows;
     * <table class="plain">
     *   <caption style="display:none">Translation</caption>
     *   <thead>
     *   <tr>
     *     <th scope="col">Escape</th>
     *     <th scope="col">Name</th>
     *     <th scope="col">Translation</th>
     *   </tr>
     *   </thead>
     *   <tr>
     *     <td>{@code \u005Cb}</td>
     *     <td>backspace</td>
     *     <td>{@code U+0008}</td>
     *   </tr>
     *   <tr>
     *     <td>{@code \u005Ct}</td>
     *     <td>horizontal tab</td>
     *     <td>{@code U+0009}</td>
     *   </tr>
     *   <tr>
     *     <td>{@code \u005Cn}</td>
     *     <td>line feed</td>
     *     <td>{@code U+000A}</td>
     *   </tr>
     *   <tr>
     *     <td>{@code \u005Cf}</td>
     *     <td>form feed</td>
     *     <td>{@code U+000C}</td>
     *   </tr>
     *   <tr>
     *     <td>{@code \u005Cr}</td>
     *     <td>carriage return</td>
     *     <td>{@code U+000D}</td>
     *   </tr>
     *   <tr>
     *     <td>{@code \u005C"}</td>
     *     <td>double quote</td>
     *     <td>{@code U+0022}</td>
     *   </tr>
     *   <tr>
     *     <td>{@code \u005C'}</td>
     *     <td>single quote</td>
     *     <td>{@code U+0027}</td>
     *   </tr>
     *   <tr>
     *     <td>{@code \u005C\u005C}</td>
     *     <td>backslash</td>
     *     <td>{@code U+005C}</td>
     *   </tr>
     *   <tr>
     *     <td>{@code \u005C0 - \u005C377}</td>
     *     <td>octal escape</td>
     *     <td>code point equivalents</td>
     *   </tr>
     * </table>
     *
     * @implNote
     * This method does <em>not</em> translate Unicode escapes such as "{@code \u005cu2022}".
     * Unicode escapes are translated by the Java compiler when reading input characters and
     * are not part of the string literal specification.
     *
     * @throws IllegalArgumentException when an escape sequence is malformed.
     *
     * @return String with escape sequences translated.
     *
     * @jls 3.10.7 Escape Sequences
     *
     * @since 13
     *
     * @deprecated  This method is associated with text blocks, a preview language feature.
     *              Text blocks and/or this method may be changed or removed in a future release.
     */
    @Deprecated(forRemoval=true, since="13")
    public String translateEscapes() {