JDK 9 RFR of 8130679: Writer/StringWriter.write methods do not specify index out bounds

[Roger Riggs]

Hi Brian,

On 5/9/2016 4:11 PM, Brian Burkhalter wrote:
> Hi Roger,
>
> Thanks for taking a close look at this.
>
> On May 9, 2016, at 12:42 PM, Roger Riggs <Roger.Riggs at Oracle.com 
> <mailto:Roger.Riggs at Oracle.com>> wrote:
>
>> In the @throws IndexOutOfBounds I think it is easier to understand to say
>>
>> * or {@code off + len} is greater than {@code cbuf.length}
>>
>> It matches the code more closely.
>
> The reason for the verbiage is that it matches (module removal of a 
> redundant “or” in the throws verbiage) Reader.read(char[],int,int) 
> with which I thought it would good to be consistent in an 
> operation-symmetric sense:
>
> http://download.java.net/java/jdk9/docs/api/java/io/Reader.html#read-char:A-int-int-

It better to propagate the best practices, not something that can be 
improved.
Since you are updating the writing classes, I think it ok to put a lower 
priority on the Reader classes.

>
>> - Is not clear why the form of the added @throws is different between 
>> the methods (other than len = string.size()
>
> Writer.write(String,int,int) already had a throws exception for IOOBEs 
> so I was trying to be consistent with that:
>
> http://download.java.net/java/jdk9/docs/api/java/io/Writer.html#write-java.lang.String-int-int-

I just think that {@code cbuf.length - off}, is not an intuitive way to 
talk about the out of range condition.

The write(string, off, len) uses a better form and I think its more 
important that the methods in a
class use the similar form.  It is much more noticeable comparing two 
methods in a class
than methods in different classes. (Fixing up Reader would be a 
different request).

>
>> line 214: add a spaces in "off+len"
>>
>> Most/All files have the same pattern.  It would be nice to be consistent.
>
> Again, this is the same as in the extent Writer.write(String,int,int).
This uses the form I think is more readable:

  178      *          or {@code off + len} is negative or greater than the length

Thanks, Roger

>
> Thanks,
>
> Brian