Editorial: Make better use of clamping

[gibson042]

• Reduce single-use aliases.
• Introduce ToClampedIndex for relative-to-start-or-end index values.

[ljharb]

Nice, this looks a lot cleaner to me

[jmdyck]

This has a conflict with main in String.prototype.lastIndexOf.

[gibson042]

@jmdyck Thanks, fixed all three issues.

[jmdyck]

As far as I can tell, this PR is semantics-preserving (or, in one case, semantics-clarifying), and could be merged without calamity.

My comments are stylistic points that you and/or the editors might want to consider.

[jmdyck]

If the search-string is longer than the subject-string (i.e., _len_ - _searchLen_ < 0), the status quo calls for the result of clamping _pos_ between 0 and a negative number, which violates clamping's requirement that lower <= upper.

This PR fixes that spec bug, which I think deserves pointing out.

[jmdyck]

In

• String.prototype.at
• Array.prototype.at
• %TypedArray%.prototype.at

it's odd to use ToClampedIndex, because the given clamping is superfluous -- the subsequent code works whether the quantity has been clamped or not. Instead, what's important is that negative-indexing-from-end has been applied.

We could conceivably introduce an AO that performed only that transformation.
(see HandleNegativeIndex above). Other functions that could maybe use it:

• Array.prototype.includes
• Array.prototype.indexOf
• %TypedArray%.prototype.includes
• %TypedArray%.prototype.indexOf

[gibson042]

I tried to find a name that conveyed enough information to justify use in both …indexOf and at operations, and ultimately decided that including "clamp" was important to understand the arguments ("To" implies conversion, "Clamped" implies relevance of bounds, and "Index" loosely suggests handling of negative values, especially as "ClampedIndex").

ToClampedRelativeIndex was a possibility, but it's a bit long and also seemed a little weird to refer to nonnegative indices as "relative". Likewise ToClampedAbsoluteIndex, which seems like just a longer name for ToClampedIndex.

[jmdyck]

Suggested change

	1. If _fromIndex_ is not present, let _k_ be _len_ - 1; else let _k_ be ? ToClampedIndex(_fromIndex_, _len_, -1, _len_ - 1).
	1. If _fromIndex_ is not present, then
	1. Let _k_ be _len_ - 1.
	1. Else,
	1. Let _k_ be ? ToClampedIndex(_fromIndex_, _len_, -1, _len_ - 1).

just for readability. And similarly for other long If/else steps.

[michaelficarra]

Any reason not to make this a positive test?

Suggested change

	1. If _fromIndex_ is not present, let _k_ be _len_ - 1.
	1. Else, let _k_ be min(? ToAbsoluteIndex(_fromIndex_, _len_), _len_ - 1).
	1. If _fromIndex_ is present, let _k_ be min(? ToAbsoluteIndex(_fromIndex_, _len_), _len_ - 1).
	1. Else, let _k_ be _len_ - 1.

[gibson042]

Not particularly, but "If <input> is <negative condition>, let <position> be <maximum>… else let <position> be <treat input numerically>" is the overwhelmingly dominant pattern in such steps of the algorithms affected by this PR (although {Array,%TypedArray%}.prototype.lastIndexOf are unique in their condition distinguishing absence from undefined¹).

How strongly do you feel about this suggestion?

Footnotes

1. …and String.prototype.lastIndexOf is unique in conflating non-numeric end-position input with absent/undefined, as opposed to e.g. slice and endsWith and subarray 🙃 ↩