RFR JDK-8200172,String.split non-positive term incorrect use

[joe darcy]

Hello,

I think some larger re-wording is in order. Here is one of the proposed 
new paragraphs:

2181      * <p> The {@code limit} parameter controls the number of times the
2182      * pattern is applied and therefore affects the length of the 
resulting
2183      * array.  If the limit <i>n</i> is greater than zero then the 
pattern
2184      * will be applied at most <i>n</i> - 1 times, the 
array's
2185      * length will be no greater than <i>n</i>, and the array's 
last entry
2186      * will contain all input beyond the last matched delimiter.  
If <i>n</i>
2187      * is negative then the pattern will be applied as many times as
2188      * possible and the array can have any length.  If <i>n</i> is 
zero then
2189      * the pattern will be applied as many times as possible, the 
array can
2190      * have any length, and trailing empty strings will be discarded.

In a mathematical signed-ness sense there are three values, positive, 
zero, and negative, hence library methods like Integer.signum which 
return -1, 0, or 1. The term non-negative covers zero and positive 
values; conversely non-positive covers zero and negative.

In terms of how the above paragraph could be structured, I'd recommend

"If the limit n is positive...
  If the limit n is zero...
  if the limit n is negative..."

possibly using an unordered list.

No CSR would be required for this kind of change as the semantics of the 
specification is not being altered.

HTH,

-Joe


On 5/22/2018 4:13 PM, Lance Andersen wrote:
> Hi Sherman
>
> The change from non-positive to negative makes sense.
>
> I would agree that a CSR should not be required (hopefully Joe D does also ;-) )
>
> Best
> Lance
>> On May 22, 2018, at 7:07 PM, Xueming Shen <xueming.shen at oracle.com> wrote:
>>
>> Hi,
>>
>> Please help review a api doc clarification for String.split()/Pattern.split().
>>
>> issue: https://bugs.openjdk.java.net/browse/JDK-8200172
>> webrev: http://cr.openjdk.java.net/~sherman/8200172/webrev
>>
>> As suggested, it appears to be clear, straightforward and less confusion to simply
>> categorize the clauses as "if positive", "if negative" and "if zero".
>>
>> It's simply a rewording to clear things up, I would assume csr is not necessary here.
>>
>> thanks,
>> Sherman
>>
>   <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>   <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>   <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
> Oracle Java Engineering
> 1 Network Drive
> Burlington, MA 01803
> Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>
>
>
>