--- a/src/java.base/share/classes/java/lang/String.java Thu Oct 17 20:27:44 2019 +0100
+++ b/src/java.base/share/classes/java/lang/String.java Thu Oct 17 20:53:35 2019 +0100
@@ -36,6 +36,7 @@
import java.util.Arrays;
import java.util.Comparator;
import java.util.Formatter;
+import java.util.List;
import java.util.Locale;
import java.util.Objects;
import java.util.Optional;
@@ -171,6 +172,7 @@
private boolean hashIsZero; // Default to false;
/** use serialVersionUID from JDK 1.0.2 for interoperability */
+ @java.io.Serial
private static final long serialVersionUID = -6849794470754667710L;
/**
@@ -223,6 +225,7 @@
* <a href="{@docRoot}/../specs/serialization/protocol.html#stream-elements">
* Object Serialization Specification, Section 6.2, "Stream Elements"</a>
*/
+ @java.io.Serial
private static final ObjectStreamField[] serialPersistentFields =
new ObjectStreamField[0];
@@ -699,7 +702,7 @@
* @param index the index of the {@code char} value.
* @return the {@code char} value at the specified index of this string.
* The first {@code char} value is at index {@code 0}.
- * @exception IndexOutOfBoundsException if the {@code index}
+ * @throws IndexOutOfBoundsException if the {@code index}
* argument is negative or not less than the length of this
* string.
*/
@@ -728,7 +731,7 @@
* @param index the index to the {@code char} values
* @return the code point value of the character at the
* {@code index}
- * @exception IndexOutOfBoundsException if the {@code index}
+ * @throws IndexOutOfBoundsException if the {@code index}
* argument is negative or not less than the length of this
* string.
* @since 1.5
@@ -760,7 +763,7 @@
*
* @param index the index following the code point that should be returned
* @return the Unicode code point value before the given index.
- * @exception IndexOutOfBoundsException if the {@code index}
+ * @throws IndexOutOfBoundsException if the {@code index}
* argument is less than 1 or greater than the length
* of this string.
* @since 1.5
@@ -791,7 +794,7 @@
* the text range.
* @return the number of Unicode code points in the specified text
* range
- * @exception IndexOutOfBoundsException if the
+ * @throws IndexOutOfBoundsException if the
* {@code beginIndex} is negative, or {@code endIndex}
* is larger than the length of this {@code String}, or
* {@code beginIndex} is larger than {@code endIndex}.
@@ -818,7 +821,7 @@
* @param index the index to be offset
* @param codePointOffset the offset in code points
* @return the index within this {@code String}
- * @exception IndexOutOfBoundsException if {@code index}
+ * @throws IndexOutOfBoundsException if {@code index}
* is negative or larger then the length of this
* {@code String}, or if {@code codePointOffset} is positive
* and the substring starting with {@code index} has fewer
@@ -855,7 +858,7 @@
* to copy.
* @param dst the destination array.
* @param dstBegin the start offset in the destination array.
- * @exception IndexOutOfBoundsException If any of the following
+ * @throws IndexOutOfBoundsException If any of the following
* is true:
* <ul><li>{@code srcBegin} is negative.
* <li>{@code srcBegin} is greater than {@code srcEnd}
@@ -1234,6 +1237,7 @@
private static class CaseInsensitiveComparator
implements Comparator<String>, java.io.Serializable {
// use serialVersionUID from JDK 1.2.2 for interoperability
+ @java.io.Serial
private static final long serialVersionUID = 8575799808933029326L;
public int compare(String s1, String s2) {
@@ -1249,6 +1253,7 @@
}
/** Replaces the de-serialized object. */
+ @java.io.Serial
private Object readResolve() { return CASE_INSENSITIVE_ORDER; }
}
@@ -1862,23 +1867,12 @@
*
* @param beginIndex the beginning index, inclusive.
* @return the specified substring.
- * @exception IndexOutOfBoundsException if
+ * @throws IndexOutOfBoundsException if
* {@code beginIndex} is negative or larger than the
* length of this {@code String} object.
*/
public String substring(int beginIndex) {
- if (beginIndex < 0) {
- throw new StringIndexOutOfBoundsException(beginIndex);
- }
- int subLen = length() - beginIndex;
- if (subLen < 0) {
- throw new StringIndexOutOfBoundsException(subLen);
- }
- if (beginIndex == 0) {
- return this;
- }
- return isLatin1() ? StringLatin1.newString(value, beginIndex, subLen)
- : StringUTF16.newString(value, beginIndex, subLen);
+ return substring(beginIndex, length());
}
/**
@@ -1896,7 +1890,7 @@
* @param beginIndex the beginning index, inclusive.
* @param endIndex the ending index, exclusive.
* @return the specified substring.
- * @exception IndexOutOfBoundsException if the
+ * @throws IndexOutOfBoundsException if the
* {@code beginIndex} is negative, or
* {@code endIndex} is larger than the length of
* this {@code String} object, or
@@ -2797,11 +2791,6 @@
return indexOfNonWhitespace() == length();
}
- private Stream<String> lines(int maxLeading, int maxTrailing) {
- return isLatin1() ? StringLatin1.lines(value, maxLeading, maxTrailing)
- : StringUTF16.lines(value, maxLeading, maxTrailing);
- }
-
/**
* Returns a stream of lines extracted from this string,
* separated by line terminators.
@@ -2833,7 +2822,7 @@
* @since 11
*/
public Stream<String> lines() {
- return lines(0, 0);
+ return isLatin1() ? StringLatin1.lines(value) : StringUTF16.lines(value);
}
/**
@@ -2873,12 +2862,10 @@
* @since 12
*/
public String indent(int n) {
- return isEmpty() ? "" : indent(n, false);
- }
-
- private String indent(int n, boolean removeBlanks) {
- Stream<String> stream = removeBlanks ? lines(Integer.MAX_VALUE, Integer.MAX_VALUE)
- : lines();
+ if (isEmpty()) {
+ return "";
+ }
+ Stream<String> stream = lines();
if (n > 0) {
final String spaces = " ".repeat(n);
stream = stream.map(s -> spaces + s);
@@ -2901,6 +2888,265 @@
}
/**
+ * Returns a string whose value is this string, with incidental
+ * {@linkplain Character#isWhitespace(int) white space} removed from
+ * the beginning and end of every line.
+ * <p>
+ * Incidental {@linkplain Character#isWhitespace(int) white space}
+ * is often present in a text block to align the content with the opening
+ * delimiter. For example, in the following code, dots represent incidental
+ * {@linkplain Character#isWhitespace(int) white space}:
+ * <blockquote><pre>
+ * String html = """
+ * ..............<html>
+ * .............. <body>
+ * .............. <p>Hello, world</p>
+ * .............. </body>
+ * ..............</html>
+ * ..............""";
+ * </pre></blockquote>
+ * This method treats the incidental
+ * {@linkplain Character#isWhitespace(int) white space} as indentation to be
+ * stripped, producing a string that preserves the relative indentation of
+ * the content. Using | to visualize the start of each line of the string:
+ * <blockquote><pre>
+ * |<html>
+ * | <body>
+ * | <p>Hello, world</p>
+ * | </body>
+ * |</html>
+ * </pre></blockquote>
+ * First, the individual lines of this string are extracted as if by using
+ * {@link String#lines()}.
+ * <p>
+ * Then, the <i>minimum indentation</i> (min) is determined as follows.
+ * For each non-blank line (as defined by {@link String#isBlank()}), the
+ * leading {@linkplain Character#isWhitespace(int) white space} characters are
+ * counted. The leading {@linkplain Character#isWhitespace(int) white space}
+ * characters on the last line are also counted even if
+ * {@linkplain String#isBlank() blank}. The <i>min</i> value is the smallest
+ * of these counts.
+ * <p>
+ * For each {@linkplain String#isBlank() non-blank} line, <i>min</i> leading
+ * {@linkplain Character#isWhitespace(int) white space} characters are removed,
+ * and any trailing {@linkplain Character#isWhitespace(int) white space}
+ * characters are removed. {@linkplain String#isBlank() Blank} lines are
+ * replaced with the empty string.
+ *
+ * <p>
+ * Finally, the lines are joined into a new string, using the LF character
+ * {@code "\n"} (U+000A) to separate lines.
+ *
+ * @apiNote
+ * This method's primary purpose is to shift a block of lines as far as
+ * possible to the left, while preserving relative indentation. Lines
+ * that were indented the least will thus have no leading
+ * {@linkplain Character#isWhitespace(int) white space}.
+ * The line count of the result will be the same as line count of this
+ * string.
+ * If this string ends with a line terminator then the result will end
+ * with a line terminator.
+ *
+ * @implNote
+ * This method treats all {@linkplain Character#isWhitespace(int) white space}
+ * characters as having equal width. As long as the indentation on every
+ * line is consistently composed of the same character sequences, then the
+ * result will be as described above.
+ *
+ * @return string with incidental indentation removed and line
+ * terminators normalized
+ *
+ * @see String#lines()
+ * @see String#isBlank()
+ * @see String#indent(int)
+ * @see Character#isWhitespace(int)
+ *
+ * @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 stripIndent() {
+ int length = length();
+ if (length == 0) {
+ return "";
+ }
+ char lastChar = charAt(length - 1);
+ boolean optOut = lastChar == '\n' || lastChar == '\r';
+ List<String> lines = lines().collect(Collectors.toList());
+ final int outdent = optOut ? 0 : outdent(lines);
+ return lines.stream()
+ .map(line -> {
+ int firstNonWhitespace = line.indexOfNonWhitespace();
+ int lastNonWhitespace = line.lastIndexOfNonWhitespace();
+ int incidentalWhitespace = Math.min(outdent, firstNonWhitespace);
+ return firstNonWhitespace > lastNonWhitespace
+ ? "" : line.substring(incidentalWhitespace, lastNonWhitespace);
+ })
+ .collect(Collectors.joining("\n", "", optOut ? "\n" : ""));
+ }
+
+ private static int outdent(List<String> lines) {
+ // Note: outdent is guaranteed to be zero or positive number.
+ // If there isn't a non-blank line then the last must be blank
+ int outdent = Integer.MAX_VALUE;
+ for (String line : lines) {
+ int leadingWhitespace = line.indexOfNonWhitespace();
+ if (leadingWhitespace != line.length()) {
+ outdent = Integer.min(outdent, leadingWhitespace);
+ }
+ }
+ String lastLine = lines.get(lines.size() - 1);
+ if (lastLine.isBlank()) {
+ outdent = Integer.min(outdent, lastLine.length());
+ }
+ return outdent;
+ }
+
+ /**
+ * 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="striped">
+ * <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>
+ * <tbody>
+ * <tr>
+ * <th scope="row">{@code \u005Cb}</th>
+ * <td>backspace</td>
+ * <td>{@code U+0008}</td>
+ * </tr>
+ * <tr>
+ * <th scope="row">{@code \u005Ct}</th>
+ * <td>horizontal tab</td>
+ * <td>{@code U+0009}</td>
+ * </tr>
+ * <tr>
+ * <th scope="row">{@code \u005Cn}</th>
+ * <td>line feed</td>
+ * <td>{@code U+000A}</td>
+ * </tr>
+ * <tr>
+ * <th scope="row">{@code \u005Cf}</th>
+ * <td>form feed</td>
+ * <td>{@code U+000C}</td>
+ * </tr>
+ * <tr>
+ * <th scope="row">{@code \u005Cr}</th>
+ * <td>carriage return</td>
+ * <td>{@code U+000D}</td>
+ * </tr>
+ * <tr>
+ * <th scope="row">{@code \u005C"}</th>
+ * <td>double quote</td>
+ * <td>{@code U+0022}</td>
+ * </tr>
+ * <tr>
+ * <th scope="row">{@code \u005C'}</th>
+ * <td>single quote</td>
+ * <td>{@code U+0027}</td>
+ * </tr>
+ * <tr>
+ * <th scope="row">{@code \u005C\u005C}</th>
+ * <td>backslash</td>
+ * <td>{@code U+005C}</td>
+ * </tr>
+ * <tr>
+ * <th scope="row">{@code \u005C0 - \u005C377}</th>
+ * <td>octal escape</td>
+ * <td>code point equivalents</td>
+ * </tr>
+ * </tbody>
+ * </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.
@@ -3063,6 +3309,30 @@
}
/**
+ * Formats using this string as the format string, and the supplied
+ * arguments.
+ *
+ * @implSpec This method is equivalent to {@code String.format(this, args)}.
+ *
+ * @param args
+ * Arguments referenced by the format specifiers in this string.
+ *
+ * @return A formatted string
+ *
+ * @see java.lang.String#format(String,Object...)
+ * @see java.util.Formatter
+ *
+ * @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 formatted(Object... args) {
+ return new Formatter().format(this, args).toString();
+ }
+
+ /**
* Returns the string representation of the {@code Object} argument.
*
* @param obj an {@code Object}.
@@ -3104,7 +3374,7 @@
* @param count length of the subarray.
* @return a {@code String} that contains the characters of the
* specified subarray of the character array.
- * @exception IndexOutOfBoundsException if {@code offset} is
+ * @throws IndexOutOfBoundsException if {@code offset} is
* negative, or {@code count} is negative, or
* {@code offset+count} is larger than
* {@code data.length}.
@@ -3121,7 +3391,7 @@
* @param count length of the subarray.
* @return a {@code String} that contains the characters of the
* specified subarray of the character array.
- * @exception IndexOutOfBoundsException if {@code offset} is
+ * @throws IndexOutOfBoundsException if {@code offset} is
* negative, or {@code count} is negative, or
* {@code offset+count} is larger than
* {@code data.length}.
@@ -3386,7 +3656,7 @@
return value;
}
- private boolean isLatin1() {
+ boolean isLatin1() {
return COMPACT_STRINGS && coder == LATIN1;
}
@@ -3400,7 +3670,7 @@
static void checkIndex(int index, int length) {
if (index < 0 || index >= length) {
throw new StringIndexOutOfBoundsException("index " + index +
- ",length " + length);
+ ", length " + length);
}
}
@@ -3411,7 +3681,7 @@
static void checkOffset(int offset, int length) {
if (offset < 0 || offset > length) {
throw new StringIndexOutOfBoundsException("offset " + offset +
- ",length " + length);
+ ", length " + length);
}
}