Skip to content

Fix Finder.index() Javadoc to reflect IllegalArgumentException contract for negative indices #225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Splatcrafter merged 2 commits into from
Mar 21, 2026
Merged

Fix Finder.index() Javadoc to reflect IllegalArgumentException contract for negative indices #225

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
89883f0
Initial plan
Copilot Mar 21, 2026
7bf14ca
Fix Finder.index() Javadoc: negative index throws IAE at construction…
Copilot Mar 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 11 additions & 5 deletions aether-datafixers-api/src/main/java/de/splatgames/aether/datafixers/api/optic/Finder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,8 +179,10 @@ public Dynamic<?> set(@NotNull final Dynamic<?> root,
* Creates a finder that navigates to an element by index in a list/array structure.
*
* <p>The returned finder extracts and modifies the element at the specified
* index position. If the index is out of bounds (negative or beyond the list size), {@link #get} returns
* {@code null} and {@link #set} returns the root unchanged.</p>
* index position. A negative {@code index} is rejected immediately by throwing
* {@link IllegalArgumentException} at construction time. If the index is non-negative
* but beyond the list size, {@link #get} returns {@code null} and {@link #set} returns
* the root unchanged.</p>
*
* <h4>Example</h4>
* <pre>{@code
Expand All @@ -195,12 +197,16 @@ public Dynamic<?> set(@NotNull final Dynamic<?> root,
* Dynamic<?> updated = firstScoreFinder.set(data, data.createInt(100));
* // updated: {"scores": [100, 92, 78]}
*
* // Out of bounds access
* // Out-of-range (positive) index — get returns null, set returns root unchanged
* Finder<?> outOfBounds = scoresFinder.then(Finder.index(10));
* Dynamic<?> missing = outOfBounds.get(data); // null
*
* // Negative index — throws IllegalArgumentException immediately
* Finder.index(-1); // throws IllegalArgumentException
* }</pre>
*
* @param index the zero-based index of the element to focus on
* @param index the zero-based index of the element to focus on; must not be negative
* @throws IllegalArgumentException if {@code index} is negative
* @return a finder that navigates to the element at the specified index, never {@code null}
*/
@NotNull
Expand Down Expand Up @@ -233,7 +239,7 @@ public String id() {
return root;
}
final var list = listResult.result().orElseThrow().toList();
if (index < 0 || index >= list.size()) {
if (index >= list.size()) {
return root;
}
final List<Dynamic<Object>> newList = new ArrayList<>();
Expand Down