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

[Brian Burkhalter]

Hi Roger,

So do you think that this form for example:

(common prefix)
     * @throws  IndexOutOfBoundsException
     *          If {@code off} is negative, or {@code len} is negative,
     *          or {@code off + len} is negative or greater than the length

(array suffix)
     *          of the given array
(string suffix)
     *          of the given string
could be applied to both the array- and String-based write() variants?

Thanks,

Brian

On May 9, 2016, at 2:04 PM, Roger Riggs <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