8223780: String::translateEscapes (Preview)
Reviewed-by: abuckley, vromero, jlahoda, bchristi, igerasim, smarks
--- 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
+ }
+ }
+}