RFR: 8305486: Add split() variants that keep the delimiters to String and j.u.r.Pattern

[Roger Riggs]

On Mon, 3 Apr 2023 17:43:55 GMT, Raffaello Giulietti <rgiulietti at openjdk.org> wrote:

> Add `split()` overloads to `String` and `java.util.regex.Pattern` that, in addition to the substrings returned by current `split()` variants, also return the delimiters matching the regular expression.

src/java.base/share/classes/java/lang/String.java line 3129:

> 3127:      * <a href="../util/regex/Pattern.html#sum">regular expression</a>.
> 3128:      *
> 3129:      * <p> This method works as if by invoking the three-argument {@link

The descriptions should be mostly self contained, repeating/duplicating the test as necessary so it easier to read. In this case, there is no reason to change the existing method javadoc except perhaps to note the relationship to the new method. It will be obvious that the spec and behavior are not changing.

src/java.base/share/classes/java/lang/String.java line 3155:

> 3153:     /**
> 3154:      * Splits this string around matches of the given
> 3155:      * <a href="../util/regex/Pattern.html#sum">regular expression</a>.

When this sentence appears in the summary table of the class javadoc, it would be useful if there were a few words that set it apart from the adjacent split methods.

src/java.base/share/classes/java/lang/String.java line 3157:

> 3155:      * <a href="../util/regex/Pattern.html#sum">regular expression</a>.
> 3156:      *
> 3157:      * <p> When {@code withDelimiter} is {@code false},

I'd look for an brief but intuitive description of the difference between the two cases before diving into the details.
It might even be better to not expose the implementation with the true/false argument but have a separate `splitWithDelimiters` (name tbd) method that can avoid having to describe both cases.

I understand this something like:
   Splits this string around matches of the given regular expression and returns both the strings and the matching delimiters.

src/java.base/share/classes/java/lang/String.java line 3365:

> 3363:      * href="../util/regex/Pattern.html#sum">regular expression</a>.
> 3364:      *
> 3365:      * <p> This method works as if by invoking the three-argument {@link

Same here, keep the original javadoc.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/13305#discussion_r1160271658
PR Review Comment: https://git.openjdk.org/jdk/pull/13305#discussion_r1160275907
PR Review Comment: https://git.openjdk.org/jdk/pull/13305#discussion_r1160286341
PR Review Comment: https://git.openjdk.org/jdk/pull/13305#discussion_r1160272599