feat: add fromIndex support to blas/ext/base/ndarray/gfind-last-index

[headlessNode]

Resolves stdlib-js/metr-issue-tracker#1183.

Description

What is the purpose of this pull request?

This pull request:

• add fromIndex support to blas/ext/base/ndarray/gfind-last-index

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

• Resolves [RFC]: add fromIndex parameter support to blas/ext/base/ndarray/gfind-last-index metr-issue-tracker#1183.

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

Primarily written by Claude Code.

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
blas/ext/base/ndarray/gfind-last-index	$\\color{green}151/151$ $\\color{green}+100.00\\%$	$\\color{green}5/5$ $\\color{green}+100.00\\%$	$\\color{green}2/2$ $\\color{green}+100.00\\%$	$\\color{green}151/151$ $\\color{green}+100.00\\%$

The above coverage report was generated for the changes in this PR.

[headlessNode]

The test failure is from top-level blas/ext/find-last-index. It would be updated after this PR is merged.

[kgryte]

Do we want fromIndex support in *find*? The Array.prototype.findLastIndex does not support a fromIndex: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex

[kgryte]

...that said, it is not clear why the standard bodies did not include fromIndex support.

[kgryte]

Update: did a bit of digging. find and findIndex were added to ES2015, so their reasoning is not easily publicly available, but the gist, as best I can infer, is that, for callback-based APIs, they saw imposing a fromIndex constraint as a matter of composition, given that the element index is passed as an argument to the provided callback.

function predicate( v, i ) {
	if ( i < fromIndex ) {
		return false;
	}
	// ...
}

This also made it consistent with the other callback-based APIs (e.g., there is no fromIndex argument in map).

I do, however, think there is an argument that we should add support for a fromIndex argument if we consider that find et al really belong to a family of "search" APIs and thus want to prioritize consistency within those APIs. I am sympathetic to that argument, especially as it means users can avoid needless iteration over regions of an ndarray dimension.

Furthermore, if we support a fromIndex, it can be broadcasted and users can supply different from indices to apply to different rows or columns, which would be much more complicated if users had to use callbacks alone.

TL;DR: I am on board with adding fromIndex support.

[kgryte]

This doesn't seem correct. If I provide -7 for a six element array, I have exceeded the beginning of the array. But here, you are clamping to 0, resulting in a valid return value; however, we should be returning -1.

This ensures parity with gfind-index. There, if a positive fromIndex exceeds the array bounds, we always return -1. We should behave similarly here.

This is likely going to apply to all the "last" packages you have recently refactored and will need further correction.

Accordingly, this brings me back to ndarray/base/clip-upper-index, where the lower bound is not clamped. Your logic in the wrapper would then need to change such that if the returned value is less than zero, you return -1.

[kgryte]

Why is this check necessary? Instead, for L75, you should use N-1. Then, you don't need to explicitly set to N-1. This is going to apply to your other "last" refactorings and should be addressed in a follow-up PR for those packages.

[kgryte]

Left initial comments.