changeset 51192:e83c0a50dc87 raw-string-literal

0000000: Update indent align APIs
author jlaskey
date Fri, 15 Jun 2018 13:44:06 -0300
parents 1430028afefa
children 042e527cb0a2
files src/java.base/share/classes/java/lang/String.java
diffstat 1 files changed, 80 insertions(+), 124 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/String.java	Mon Jun 11 12:42:58 2018 -0300
+++ b/src/java.base/share/classes/java/lang/String.java	Fri Jun 15 13:44:06 2018 -0300
@@ -2751,56 +2751,7 @@
         return indexOfNonWhitespace() == length();
     }
 
-    /**
-     * Returns a stream of substrings extracted from this string
-     * partitioned by line terminators.
-     * <p>
-     * Line terminators recognized are line feed
-     * {@code "\n"} ({@code U+000A}),
-     * carriage return
-     * {@code "\r"} ({@code U+000D})
-     * and a carriage return followed immediately by a line feed
-     * {@code "\r\n"} ({@code U+000D U+000A}).
-     * <p>
-     * The stream returned by this method contains each line of
-     * this string that is terminated by a line terminator except that
-     * the last line can either be terminated by a line terminator or the
-     * end of the string.
-     * The lines in the stream are in the order in which
-     * they occur in this string and do not include the line terminators
-     * partitioning the lines.
-     * <p>
-     * The {@code maxLeading} and {@code maxTrailing} arguments can be
-     * used to remove incidental blank lines from the beginning and
-     * end of a multi-line sequence. A value of {@code 1} will remove
-     * at most one blank line. A value of {@link Integer.MAX_VALUE}
-     * will all leading or trailing blank lines.
-     *
-     * @implNote This method provides better performance than
-     *           split("\R") by supplying elements lazily and
-     *           by faster search of new line terminators.
-     *
-     * @param  maxLeading   the maximum number of leading blank lines
-     *                      to remove
-     *
-     * @param  maxTrailing  the maximum number of trailing blank lines
-     *                      to remove
-     *
-     * @return  the stream of strings extracted from this string
-     *          partitioned by line terminators
-     *
-     * @throws  IllegalArgumentException if {@code maxLeading} or
-     *          {@code maxTrailing} is negative.
-     *
-     * @since 12
-     */
-    public Stream<String> lines(int maxLeading, int maxTrailing) {
-        if (maxLeading < 0) {
-            throw new IllegalArgumentException("maxLeading is negative: " + maxLeading);
-        }
-        if (maxTrailing < 0) {
-            throw new IllegalArgumentException("maxTrailing is negative: " + maxTrailing);
-        }
+    private Stream<String> lines(int maxLeading, int maxTrailing) {
         Stream<String> stream = isLatin1() ? StringLatin1.lines(value, maxLeading, maxTrailing)
                                            : StringUTF16.lines(value, maxLeading, maxTrailing);
         return stream;
@@ -2838,48 +2789,10 @@
         return lines(0, 0);
     }
 
-    /**
-     * When applied to a string, modifies the indentation
-     * of each line based on parameter {@code n}.
-     * <p>
-     * If {@code n > 0} then {@code n} spaces {@code u+0020}
-     * are inserted at the beginning of each line.
-     * {@link String#isBlank() blank lines} are unaffected.
-     * <p>
-     * If {@code n < 0} then {@code n}
-     * {@link Character#isWhitespace(int) white space characters}
-     * are removed from the beginning of each line. If a given line
-     * does not contain sufficient white space then all leading
-     * {@link Character#isWhitespace(int) white space characters}
-     * are removed.
-     * <p>
-     * If {@code n == 0} then indentation remains unchanged, but other
-     * transformations, such as line termination, still take effect.
-     * <p>
-     * @apinote All
-     *          {@link Character#isWhitespace(int) white space characters},
-     *          including tab, are treated as a single space.
-     * <p>
-     * @apiNote The all line terminators in the result will be
-     *          replaced with line feed {@code "\n"} ({@code U+000A}).
-     *
-     * @param n  number of leading white space characters
-     *           to adjust
-     *
-     * @return string with indentation modified.
-     *
-     * @see Character#isWhitespace(int)
-     * @see String#lines()
-     *
-     * @since 12
-     */
-    public String indent(int n) {
-        return isEmpty() ? "" :  indent(n, false);
-    }
-
-    private String indent(int n, boolean skipBlanks) {
+    private String indent(int n, boolean removeBlanks) {
         if (isMultiline()) {
-            Stream<String> stream = skipBlanks ? lines(1, 1) : 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 -> s.isBlank() ? s : spaces + s);
@@ -2903,6 +2816,44 @@
         }
     }
 
+    /**
+     * Modify the indentation of each line based on parameter
+     * {@code n}.
+     * <p>
+     * If {@code n > 0} then {@code n} spaces {@code u+0020}
+     * are inserted at the beginning of each line.
+     * {@link String#isBlank() Blank lines} are unaffected.
+     * <p>
+     * If {@code n < 0} then {@code n}
+     * {@link Character#isWhitespace(int) white space characters}
+     * are removed from the beginning of each line. If a given line
+     * does not contain sufficient white space then all leading
+     * {@link Character#isWhitespace(int) white space characters}
+     * are removed.
+     * <p>
+     * If {@code n == 0} then indentation remains unchanged, but other
+     * transformations, such as line termination, still take effect.
+     * <p>
+     * @apinote All
+     *          {@link Character#isWhitespace(int) white space characters},
+     *          including tab, are treated as a single space.
+     * <p>
+     * @apiNote The all line terminators in the result will be
+     *          replaced with line feed {@code "\n"} ({@code U+000A}).
+     *
+     * @param n  number of leading white space characters
+     *           to adjust
+     *
+     * @return string with indentation modified.
+     *
+     * @see Character#isWhitespace(int)
+     *
+     * @since 12
+     */
+    public String indent(int n) {
+        return isEmpty() ? "" :  indent(n, true);
+    }
+
     private boolean isMultiline() {
         return isLatin1() ? StringLatin1.isMultiline(value)
                           : StringUTF16.isMultiline(value);
@@ -2919,19 +2870,39 @@
     }
 
     /**
-     * When applied to a string, left justifies
-     * lines without loss of relative indentation. This is
-     * accomplished by removing an equal number of
+     * After removing all leading and trailing blank lines,
+     * left justifies each line {@code n} spaces
+     * without loss of relative indentation.
+     * <p>
+     * This is accomplished by using
+     * {@link java.lang.String#indent(int)} to
+     * remove (negative argument) an equal number of
      * {@link Character#isWhitespace(int) white space} characters
      * from each line so that at least one line has a non-white
      * space character in the left-most position.
-     * The result is then realigned by indenting {@code n}
-     * {@link Character#isWhitespace(int) white space}
-     * characters.
-     * First and last blank lines introduced to allow
-     * bracketing  delimiters to appear on separate source lines
-     * are also removed.
      * <p>
+     * The integer value {@code n} is added to the
+     * value passed to {@link java.lang.String#indent(int)}
+     * to adjust the resulting indentation. Example:
+     * <blockquote><pre>
+     *     `
+     *             abc
+     *                def
+     *     `.align(0);
+     *
+     * returns
+     * abc
+     *    def
+     *
+     *
+     *     `
+     *             abc
+     *                def
+     *     `.align(4);
+     * returns
+     *     abc
+     *        def
+     * </pre></blockquote>
      * @apinote All
      *          {@link Character#isWhitespace(int) white space characters},
      *          including tab, are treated as a single space.
@@ -2944,10 +2915,7 @@
      *
      * @return string aligned to left margin
      *
-     * @see Character#isWhitespace(int)
-     * @see String#indent(int)
-     * @see String#lines()
-     * @see String#lines(int, int)
+     * @see java.lang.String#indent(int)
      *
      * @since 12
      */
@@ -2964,29 +2932,17 @@
     }
 
     /**
-     * When applied to a string, left justifies
-     * lines without loss of relative indentation. This is
-     * accomplished by removing an equal number of
-     * {@link Character#isWhitespace(int) white space} characters
-     * from each line so that at least one line has a non-white
-     * space character in the left-most position.
-     * First and last blank lines introduced to allow
-     * bracketing  delimiters to appear on separate source lines
-     * are also removed.
-     * <p>
-     * @apinote All
-     *          {@link Character#isWhitespace(int) white space characters},
-     *          including tab, are treated as a single space.
-     * <p>
-     * @apiNote The all line terminators in the result will be
-     *          replaced with line feed {@code "\n"} ({@code U+000A}).
+     * After removing all leading and trailing blank lines,
+     * left justifies each line without loss of relative
+     * indentation.
+     * Invoking this method is equivalent to:
+     * <blockquote>
+     *  {@code this.align(0)}
+     * </blockquote>
      *
      * @return string left justified
      *
-     * @see Character#isWhitespace(int)
-     * @see String#indent(int)
-     * @see String#lines()
-     * @see String#lines(int, int)
+     * @see String#align(int)
      *
      * @since 12
      */