8223780: String::translateEscapes (Preview)
authorjlaskey
Thu, 06 Jun 2019 12:24:44 -0300 (2019-06-06)
changeset 55261 dff30b1557ee
parent 55260 cc0f117f4405
child 55262 7d83cf1cfa74
8223780: String::translateEscapes (Preview) Reviewed-by: abuckley, vromero, jlahoda, bchristi, igerasim, smarks
src/java.base/share/classes/java/lang/String.java
test/jdk/java/lang/String/TranslateEscapes.java
--- a/src/java.base/share/classes/java/lang/String.java	Thu Jun 06 12:24:44 2019 -0300
+++ b/src/java.base/share/classes/java/lang/String.java	Thu Jun 06 12:24:44 2019 -0300
@@ -3012,6 +3012,146 @@
     }
 
     /**
+     * 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() {
+        if (isEmpty()) {
+            return "";
+        }
+        char[] chars = toCharArray();
+        int length = chars.length;
+        int from = 0;
+        int to = 0;
+        while (from < length) {
+            char ch = chars[from++];
+            if (ch == '\\') {
+                ch = from < length ? chars[from++] : '\0';
+                switch (ch) {
+                case 'b':
+                    ch = '\b';
+                    break;
+                case 'f':
+                    ch = '\f';
+                    break;
+                case 'n':
+                    ch = '\n';
+                    break;
+                case 'r':
+                    ch = '\r';
+                    break;
+                case 't':
+                    ch = '\t';
+                    break;
+                case '\'':
+                case '\"':
+                case '\\':
+                    // as is
+                    break;
+                case '0': case '1': case '2': case '3':
+                case '4': case '5': case '6': case '7':
+                    int limit = Integer.min(from + (ch <= '3' ? 2 : 1), length);
+                    int code = ch - '0';
+                    while (from < limit) {
+                        ch = chars[from];
+                        if (ch < '0' || '7' < ch) {
+                            break;
+                        }
+                        from++;
+                        code = (code << 3) | (ch - '0');
+                    }
+                    ch = (char)code;
+                    break;
+                default: {
+                    String msg = String.format(
+                        "Invalid escape sequence: \\%c \\\\u%04X",
+                        ch, (int)ch);
+                    throw new IllegalArgumentException(msg);
+                }
+                }
+            }
+
+            chars[to++] = ch;
+        }
+
+        return new String(chars, 0, to);
+    }
+
+    /**
      * This method allows the application of a function to {@code this}
      * string. The function should expect a single String argument
      * and produce an {@code R} result.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/jdk/java/lang/String/TranslateEscapes.java	Thu Jun 06 12:24:44 2019 -0300
@@ -0,0 +1,104 @@
+/*
+ * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug 8223780
+ * @summary This exercises String#translateEscapes patterns and limits.
+ * @run main TranslateEscapes
+ */
+
+public class TranslateEscapes {
+    public static void main(String... arg) {
+        test1();
+        test2();
+        test3();
+    }
+
+    /*
+     * Standard escapes.
+     */
+    static void test1() {
+        verifyEscape("b", '\b');
+        verifyEscape("f", '\f');
+        verifyEscape("n", '\n');
+        verifyEscape("r", '\r');
+        verifyEscape("t", '\t');
+        verifyEscape("'", '\'');
+        verifyEscape("\"", '\"');
+        verifyEscape("\\", '\\');
+    }
+
+    /*
+     * Octal escapes.
+     */
+    static void test2() {
+        verifyOctalEscape("0", 0);
+        verifyOctalEscape("3", 03);
+        verifyOctalEscape("7", 07);
+        verifyOctalEscape("07", 07);
+        verifyOctalEscape("17", 017);
+        verifyOctalEscape("27", 027);
+        verifyOctalEscape("37", 037);
+        verifyOctalEscape("377", 0377);
+
+        verifyOctalEscape("777", 077);
+        verifyOctalEscape("78", 07);
+    }
+
+    /*
+     * Exceptions.
+     */
+    static void test3() {
+        exceptionThrown("+");
+        exceptionThrown("\n");
+    }
+
+    static void verifyEscape(String string, char ch) {
+        String escapes = "\\" + string;
+        if (escapes.translateEscapes().charAt(0) != ch) {
+            System.err.format("\"%s\" not escape \"%s\"'%n", string, escapes);
+            throw new RuntimeException();
+        }
+    }
+
+    static void verifyOctalEscape(String string, int octal) {
+        String escapes = "\\" + string;
+        if (escapes.translateEscapes().charAt(0) != octal) {
+            System.err.format("\"%s\" not octal %o%n", string, octal);
+            throw new RuntimeException();
+        }
+    }
+
+    static void exceptionThrown(String string) {
+        String escapes = "\\" + string;
+        try {
+            escapes.translateEscapes();
+            System.err.format("escape not thrown for %s%n", string);
+            throw new RuntimeException();
+
+        } catch (IllegalArgumentException ex) {
+            // okay
+        }
+    }
+}