jdk-sandbox: comparison src/java.base/share/classes/java/lang/String.java

equal deleted inserted replaced

-:13588c901957
+:9cf78a70fa4f
 import java.nio.charset.Charset;
 import java.util.ArrayList;
 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;
 import java.util.Spliterator;
 import java.util.StringJoiner;
 * us to avoid recalculating this.
 */
 private boolean hashIsZero; // Default to false;
 /** use serialVersionUID from JDK 1.0.2 for interoperability */
+@java.io.Serial
 private static final long serialVersionUID = -6849794470754667710L;
 /**
 * If String compaction is disabled, the bytes in {@code value} are
 * always encoded in UTF16.
 *
 * A String instance is written into an ObjectOutputStream according to
 * <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];
 /**
 * Initializes a newly created {@code String} object so that it represents
 * value is returned.
 *
 * @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.
 */
 public char charAt(int index) {
 if (isLatin1()) {
 * the {@code char} value at the given index is returned.
 *
 * @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
 */
 public int codePointAt(int index) {
 * 1} is an unpaired low-surrogate or a high-surrogate, the
 * surrogate value is returned.
 *
 * @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
 */
 public int codePointBefore(int index) {
 * the text range.
 * @param endIndex the index after the last {@code char} of
 * 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}.
 * @since  1.5
 */
 * {@code codePointOffset} count as one code point each.
 *
 * @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
 *   than {@code codePointOffset} code points,
 *   or if {@code codePointOffset} is negative and the substring
 *                        to copy.
 * @param      srcEnd     index after the last character in the string
 *                        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}
 *            <li>{@code srcEnd} is greater than the length of this
 *                string
 public static final Comparator<String> CASE_INSENSITIVE_ORDER
 = new CaseInsensitiveComparator();
 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) {
 byte v1[] = s1.value;
 byte v2[] = s2.value;
 return coder == LATIN1 ? StringLatin1.compareToCI_UTF16(v1, v2)
 : StringUTF16.compareToCI_Latin1(v1, v2);
 }
 /** Replaces the de-serialized object. */
+@java.io.Serial
 private Object readResolve() { return CASE_INSENSITIVE_ORDER; }
 }
 /**
 * Compares two strings lexicographically, ignoring case
 * "emptiness".substring(9) returns "" (an empty string)
 * </pre></blockquote>
 *
 * @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) {
+return substring(beginIndex, length());
-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);
 }
 /**
 * Returns a string that is a substring of this string. The
 * substring begins at the specified {@code beginIndex} and
 * </pre></blockquote>
 *
 * @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
 *             {@code beginIndex} is larger than
 *             {@code endIndex}.
 */
 public boolean isBlank() {
 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.
 * <p>
 * A <i>line terminator</i> is one of the following:
 * @return  the stream of lines extracted from this string
 *
 * @since 11
 */
 public Stream<String> lines() {
-return lines(0, 0);
+return isLatin1() ? StringLatin1.lines(value) : StringUTF16.lines(value);
 }
 /**
 * Adjusts the indentation of each line of this string based on the value of
 * {@code n}, and normalizes line termination characters.
 * @see Character#isWhitespace(int)
 *
 * @since 12
 */
 public String indent(int n) {
-return isEmpty() ? "" :  indent(n, false);
+if (isEmpty()) {
-}
+return "";
+}
-private String indent(int n, boolean removeBlanks) {
+Stream<String> stream = lines();
-Stream<String> stream = removeBlanks ? lines(Integer.MAX_VALUE, Integer.MAX_VALUE)
-: lines();
 if (n > 0) {
 final String spaces = " ".repeat(n);
 stream = stream.map(s -> spaces + s);
 } else if (n == Integer.MIN_VALUE) {
 stream = stream.map(s -> s.stripLeading());
 }
 private int lastIndexOfNonWhitespace() {
 return isLatin1() ? StringLatin1.lastIndexOfNonWhitespace(value)
 : StringUTF16.lastIndexOfNonWhitespace(value);
+}
+/**
+* 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 = """
+* ..............&lt;html&gt;
+* ..............    &lt;body&gt;
+* ..............        &lt;p&gt;Hello, world&lt;/p&gt;
+* ..............    &lt;/body&gt;
+* ..............&lt;/html&gt;
+* ..............""";
+* </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>
+* |&lt;html&gt;
+* |    &lt;body&gt;
+* |        &lt;p&gt;Hello, world&lt;/p&gt;
+* |    &lt;/body&gt;
+* |&lt;/html&gt;
+* </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
 public static String format(Locale l, String format, Object... args) {
 return new Formatter(l).format(format, args).toString();
 }
 /**
+* 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}.
 * @return  if the argument is {@code null}, then a string equal to
 *          {@code "null"}; otherwise, the value of
 * @param   data     the character array.
 * @param   offset   initial offset of the subarray.
 * @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}.
 */
 public static String valueOf(char data[], int offset, int count) {
 * @param   data     the character array.
 * @param   offset   initial offset of the subarray.
 * @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}.
 */
 public static String copyValueOf(char data[], int offset, int count) {
 byte[] value() {
 return value;
 }
-private boolean isLatin1() {
+boolean isLatin1() {
 return COMPACT_STRINGS && coder == LATIN1;
 }
 @Native static final byte LATIN1 = 0;
 @Native static final byte UTF16  = 1;
 * negative or greater than or equal to {@code length}.
 */
 static void checkIndex(int index, int length) {
 if (index < 0 || index >= length) {
 throw new StringIndexOutOfBoundsException("index " + index +
-",length " + length);
+", length " + length);
 }
 }
 /*
 * StringIndexOutOfBoundsException  if {@code offset}
 * is negative or greater than {@code length}.
 */
 static void checkOffset(int offset, int length) {
 if (offset < 0 || offset > length) {
 throw new StringIndexOutOfBoundsException("offset " + offset +
-",length " + length);
+", length " + length);
 }
 }
 /*
 * Check {@code offset}, {@code count} against {@code 0} and {@code length}

branch	datagramsocketimpl-branch
changeset 58678	9cf78a70fa4f
parent 55062	45128070fd15
child 58679	9c3209ff7550