src/java.base/share/classes/java/lang/String.java

rev 51726 : 8202442: String::unescape
Reviewed-by: smarks, rriggs, sherman

@@ -2970,10 +2970,92 @@
                              .orElse(0);
         return indent(n - outdent, true);
     }
 
     /**
+     * Translates all Unicode escapes and escape sequences in this string into
+     * characters represented by those escapes specified in sections 3.3 and
+     * 3.10.6 of the <cite>The Java&trade; Language Specification</cite>.
+     * <p>
+     * Each unicode escape in the form \unnnn is translated to the
+     * unicode character whose code point is {@code 0xnnnn}. Care should be
+     * taken when using UTF-16 surrogate pairs to ensure that the high
+     * surrogate (U+D800..U+DBFF) is immediately followed by a low surrogate
+     * (U+DC00..U+DFFF) otherwise a
+     * {@link java.nio.charset.CharacterCodingException} may occur during UTF-8
+     * decoding.
+     * <p>
+     * Backslash escape sequences are translated as follows;
+     * <table class="plain">
+     *   <caption style="display:none">Escape sequences</caption>
+     *   <thead>
+     *   <tr>
+     *     <th scope="col">Escape</th>
+     *     <th scope="col">Name</th>
+     *     <th scope="col">Unicode</th>
+     *   </tr>
+     *   </thead>
+     *   <tr>
+     *     <td>{@code \b}</td>
+     *     <td>backspace</td>
+     *     <td>U+0008</td>
+     *   </tr>
+     *   <tr>
+     *     <td>{@code \t}</td>
+     *     <td>horizontal tab</td>
+     *     <td>U+0009</td>
+     *   </tr>
+     *   <tr>
+     *     <td>{@code \n}</td>
+     *     <td>line feed</td>
+     *     <td>U+000A</td>
+     *   </tr>
+     *   <tr>
+     *     <td>{@code \f}</td>
+     *     <td>form feed</td>
+     *     <td>U+000C</td>
+     *   </tr>
+     *   <tr>
+     *     <td>{@code \r}</td>
+     *     <td>carriage return</td>
+     *     <td>U+000D</td>
+     *   </tr>
+     *   <tr>
+     *     <td>{@code \"}</td>
+     *     <td>double quote</td>
+     *     <td>U+0022</td>
+     *   </tr>
+     *   <tr>
+     *     <td>{@code \'}</td>
+     *     <td>single quote</td>
+     *     <td>U+0027</td>
+     *   </tr>
+     *   <tr>
+     *     <td>{@code \\}</td>
+     *     <td>backslash</td>
+     *     <td>U+005C</td>
+     *   </tr>
+     * </table>
+     * <p>
+     * Octal escapes {@code \0 - \377} are translated to their code
+     * point equivalents.
+     *
+     * @return String with all escapes translated.
+     *
+     * @throws IllegalArgumentException when escape sequence is malformed.
+     *
+     * @since 12
+     *
+     * @deprecated  Preview feature associated with Raw String Literals.
+     *              Use at your own risk.
+     */
+    @Deprecated(forRemoval=true, since="12")
+    public String unescape() throws IllegalArgumentException {
+        return isLatin1() ? StringLatin1.unescape(value) : StringUTF16.unescape(value);
+    }
+
+    /**
      * This object (which is already a string!) is itself returned.
      *
      * @return  the string itself.
      */
     public String toString() {