Standardize "pinned" dtype promotions

[crusaderky]

These functions:

• __setitem__
• __iadd__ and other in-place operators
• clip
• nextafter

Have in common that the output dtype must match the dtype of the first parameter. This is unlike most other binary or ternary functions, where all parameters are free to be be promoted against each other.

Q: Are there other such functions?

Beyond this, however, these functions differ substantially in the details:

First parameter is a Python scalar

• in __setitem__, __iadd__, and clip, the first parameter must be an array. This is an obvious necessity for __setitem__ and __iadd__, because it's a method, but not for clip.
• in nextafter, the first parameter can be a Python scalar int | float. The spec is not clear on what must happen in this case; I interpret it as "the output dtype must be the dtype of x if x is an array, otherwise follow the normal dtype promotion rules and return float32 or float64 depending on the dtype of y." It could use an explicit clarification.

Second parameter is an array of different dtype

• In __setitem__ and __iadd__, if the second parameter (value) is an array it can be automatically promoted to the dtype of the first parameter (self).
• In clip, behaviour is undefined. Which to me is weird, because the result would be unambiguous in all cases where minimum and maximum are defined and have an output dtype matching the first parameter - for example, clip(int16, min=int8, max=int8).
• In nextafter, behaviour is also undefined, which again to me is weird because it is unambiguous in all cases where __lt__, __gt__, and __eq__ are defined; in other words nextafter(float64, float32) is unambiguous.

Proposed changes

• Allow clip to have the first parameter as a Python scalar, like it already happens in nextafter
• Allow min and max parameters in clip and the y parameter in nextafter to be arrays of a dtype promotable to x.dtype, like it already happens in __setitem__
• Add a section to the dtype promotion page for "pinned" or "bound" dtype promotion, defining a general rule
• Have __setitem__, clip, and nextafter point to this general rule

[ev-br]

• ISTM that clip is most similar to where.
• nextafter with mixed dtypes, agreed it's similar to less and greater
• __setitem__ should probably behave similar to inplace __iadd__ and its ilk.

[crusaderky]

• ISTM that clip is most similar to where.

In the sense that, alternatively to what I proposed above, it could be more simply stipulated to return result_type(x, min, max)? Agree.

• __setitem__ should probably behave similar to inplace __iadd__ and its ilk.

Agreed. Adding to opening post.

[kgryte]

clip is different, as we, IIRC, don't allow kwargs to affect the output dtype. Do you have use cases and code samples where you'd want/need to have min and/or max be a different data type than x? It would be good to see real-world examples.

And TBC, the spec circumscribes guaranteed portable behavior and may not enumerate all potentially unambiguous semantics. Were we to change guidance, personally, I'd want to see demonstrated need.

nextafter is somewhat of an unfortunate casualty of recent v2024 changes. It was clearer expected behavior when x1 was required to be an array. Providing an int for x1 muddies the water a bit in that not clear user intent providing an int when nextafter is an operation specifically targeting floating-point numbers.