Request for Enhancement: Objects.checkPositionIndex(int, int)

[Glavo]

Hi Kevin,

I’m surprised you even noticed the methods.


I develop and maintain a collection library, in which I copied
checkPositionIndex because it is really commonly used by me.
I searched my library and found that checkPositionIndex has more than a
hundred use cases in my library.

And basically, the adoption counts for those methods always remained very
> low. And I remember seeing a number of misuses, too.


I was surprised by this information, I thought there should be many places
using it.
Perhaps because it is often needed by other libraries that do not want to
add dependencies on Guava.

This method should be very useful at least for implementing core libraries.
There are many copies of it in the Java standard library, and I found these
just by searching casually:

   - java.lang.String::checkOffset(int, int)
   - java.util.AbstractList.SubList::rangeCheckForAdd(int)
   - java.util.ArrayList::rangeCheckForAdd(int)
   - java.util.ArrayList.SubList::rangeCheckForAdd(int)
   - java.util.LinkedList::checkPositionIndex(int)
   - java.util.ImmutableCollections.SubList::rangeCheck(int)
   - java.util.ReverseOrderListView::checkClosedRange(int, int)
   -
   java.util.concurrent.CopyOnWriteArrayList.COWSubList::rangeCheckForAdd(int)

There are also some methods that use if...throw directly to check these
indexes:

   - java.lang.AbstractStringBuilder::offsetByCodePoints(int, int)
   - java.lang.Character::offsetByCodePoints(CharSequence, int, int)
   - java.lang.invoke.MethodType::insertParameterTypes(int, Class<?>...)
   - java.util.ImmutableCollections.AbstractImmutableList::listIterator(int)
   - java.util.concurrent.CopyOnWriteArrayList::add(int, E)
   - java.util.regex.Matcher::find(int)


Glavo

On Tue, Jan 14, 2025 at 4:19 AM Kevin Bourrillion <
kevin.bourrillion at oracle.com> wrote:

> Oh hey, I named those Guava methods. :-) This was my attempt to promote
> the terms “position indexes vs. element indexes” and hope that the idea
> caught on... which I’d say it still never has. I’m surprised you even
> noticed the methods.
>
> The notion is that “element indexes” are the buckets and “position
> indexes” are the possible insertion points *between* buckets. I
> personally find it simpler to think of a method like `subList` as simply
> accepting two position indexes, rather than thinking about half-open ranges.
>
> To me this was clarifying, but for people who never have this explained to
> them it’s probably not that clear.
>
> And basically, the adoption counts for those methods always remained very
> low. And I remember seeing a number of misuses, too.
>
> Not sure what to make of all this; just adding some context.
>
>
>
> On Jan 13, 2025, at 11:36 AM, Glavo <zjx001202 at gmail.com> wrote:
>
> Currently the java.util.Objects provide the method `checkIndex(int, int)`
> for checking indexes.
> It is convenient, but cannot be used to implement methods such as
> List::add(int, E) because these methods accept an index pointing to the end
> of the collection.
> So is it possible to add a new method to Objects to check this kind of
> index?
> This is useful for implementing collections.
> (The checkPositionIndex in the title is its name in guava. I don't like
> the name, but I don't have a better idea.)
>
> Glavo
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20250114/3a3066a7/attachment-0001.htm>