RFR [8014066] Mistake in documentation of ArrayList#removeRange

[Ivan Gerasimov]

On 14.03.2014 18:18, Peter Levart wrote:
> On 03/14/2014 01:14 PM, Ivan Gerasimov wrote:
>>
>> On 14.03.2014 16:02, David Holmes wrote:
>>> Ivan,
>>>
>>> On 14/03/2014 9:19 PM, Ivan Gerasimov wrote:
>>>> Thanks Peter for the comments.
>>>>
>>>> On 14.03.2014 14:53, Peter Levart wrote:
>>>>> On 03/14/2014 08:05 AM, Ivan Gerasimov wrote:
>>>>>> One thing I noticed is that some methods I mentioned above
>>>>>> (List.subList(), Arrays.sort(), etc) throw IllegalArgumentException
>>>>>> when fromIndex > toIndex, not IndexOutOfBoundException.
>>>>>> Wouldn't it be more correct to adopt this into removeRange() too?
>>>>>
>>>>> The question is, what exception should be thrown for removeRange(0,
>>>>> -1) then... The order of checks matters and should be specified if 
>>>>> two
>>>>> kinds of exceptions are thrown...
>>>>>
>>>>
>>>> In my opinion, the order of the checks should match the order of the
>>>> listed exceptions in the spec.
>>>
>>> That's a nice proposal but unfortunately there has never been a rule 
>>> that you have to document exceptions in the order you expect them to 
>>> be checked; nor do you have to implement exception checks in the 
>>> order they are documented. So it is too late to try and enforce this 
>>> now.
>>>
>> Sigh.
>> The order can still be stated explicitly in the doc, if it's decided 
>> to throw IllegalArgumentException.
>
> Or the checks could be documented in a way that they have disjunctive 
> conditions so that the order doesn't matter:
>
> @throws IndexOutOfBoundException if either index is negative or either 
> index is greater than size()
> @throws IllegalArgumentException if (fromIndex > toIndex) and neither 
> index is negative nor greater than size()
>
Yes, this is the most clear way!

Sincerely yours,
Ivan

> Regards, Peter
>
>> And, of course, there's no such problem if IndexOutOfBoundException 
>> is the only exception thrown.
>>
>> Sincerely yours,
>> Ivan
>>
>>
>>> David
>>> -----
>>>
>>>> If the order is:
>>>> @throws IndexOutOfBoundException if either index is negative or either
>>>> index is greater than size()
>>>> @throws IllegalArgumentException if (fromIndex > toIndex)
>>>>
>>>> then removeRange(0, -1) should throw IndexOutOfBoundException.
>>>>
>>>> Sincerely yours,
>>>> Ivan
>>>>
>>>
>>>
>>
>
>
>