RFR - JDK-8223775 String::stripIndent (Preview)
alex.buckley at oracle.com
Wed May 22 17:49:29 UTC 2019
On 5/21/2019 4:19 PM, Alex Buckley wrote:
> On 5/21/2019 2:10 PM, Jim Laskey wrote:
>> Updated version http://cr.openjdk.java.net/~jlaskey/8223775/webrev-02
> API spec looks good, but it was a surprise to learn that stripIndent
> performs normalization of line terminators:
> "@return string with margins removed and line terminators normalized"
> The processing steps in the JEP (and the JLS) are clear that
> normalization happens before incidental white space removal. I realize
> that stripIndent performs separation and joining in such a way as to
> produce a string that looks like it was normalized prior to stripIndent,
> so the @return isn't wrong, but it's still confusing to make a big deal
> of normalization-first only for stripIndent to suggest normalization-last.
Stepping back, normalization is a nice thing for the multi-line-aware
methods to do, but it's fundamentally just a "finishing touch". By
mentioning it in the class-level spec as a general policy, we can dial
back its appearance in stripIndent and indent.
The rest of this mail will appear disjointed, but put it all together in
the javadoc (and imagine the class-level spec explains the goals of
normalization) and it'll look nice. There are some tone changes below to
make the method descriptions stop talking about what's "returned" and
instead flow into the @return.
For stripIndent, bearing in mind that "margins" is no longer in the
@return a string with no incidental white space and with line
First, the individual lines of this string are extracted as if by using
lines(). [If we're going to lean on lines(), then take its concept of
extraction, rather than "conceptually separating" things. In the JLS I
would say "as if by the execution of lines()" but the informal "using"
phrase is fine for popular javadoc.]
Finally, the lines are joined into a new string, using the LF character
(U+000A) to separate lines. [The last clause is carefully chosen. We
don't want to speak of a "line separator" because we already have "line
terminator". We don't want to say "using the LF character to terminate
lines" because joining embodies separation, not termination; see the
@param of `join`.]
For indent, greater readability and consistency:
public String indent(int n)
Adjusts the indentation of each line of this string based on the value of n.
The individual lines of this string are extracted as if by using
lines(). Each line is adjusted as described below, then all the adjusted
lines are joined into a new string, using the LF character (U+000A) to
If n > 0 ...
If n < 0 ...
If n == 0 ...
a string with indentation adjusted and line terminators normalized
Finally, looking at lines: "Returns a stream of lines extracted from
this string, separated by line terminators." makes it sound like the
stream includes a line terminator element after every line element. The
separation happened during the extraction, not the streaming. Recommend:
"Returns a stream of lines extracted from this string, split at line
More information about the core-libs-dev