Description
clip states:
- min [...] Should have the same data type as x. Default: None.
- max [...] Should have the same data type as x. Default: None.
- For scalar min and/or max, the scalar values should follow type promotion rules for operations involving arrays and scalar operands (see Type Promotion Rules). Hence, if x and either min or max have different data type kinds (e.g., integer versus floating-point), behavior is unspecified and thus implementation-dependent.
The third point could use rewording in my opinion.
I believe that the intended meaning was that clip(Array[int64], 1.0)
has unspecified behaviour, as per type promotion rules.
However, the wording as it is could be interpreted that clip(Array[float64], 1)
also has unspecified behaviour, which doesn't make sense to me.
Proposal
Change
Hence, if
x
and eithermin
ormax
have different data type kinds (e.g., integer versus floating-point), behavior is unspecified and thus implementation-dependent.
To
Hence, if the scalar type of either
min
ormax
is incompatible with the data type ofx
(x
has integer data type and eithermin
ormax
are scalar floats), behavior is unspecified and thus implementation-dependent.
Backporting
As I believe this is only a clarification, it should be backported to previous versions. Note that, unlike most binops, this function has always accepted scalars for min/max and wording was the same in 2023.12.
Activity
min
andmax
have the same dtype asx
data-apis/array-api-tests#360ev-br commentedon Apr 11, 2025
Several other things that'd be great to clarify:
if
x
is integer array, andmin
ormax
is a python int and is outside of bounds forx.dtype
, is the behavior unspecified or aremin/max
implicitly combined with the dtype bounds?xp.clip(xp.arange(3, dtype=xp.uint8), -1, 256)
if
x
is a float array, andmin
ormax
is a python int, what is the behavior if, say,max
exceedsxp.finfo(x.dtype).max
?crusaderky commentedon Apr 11, 2025
It does say this one though:
kgryte commentedon Apr 11, 2025
I believe we'd just need to remove the sentence:
The type promotion rules governing mixing scalars and arrays already covers the case of scalar
int
and a floating-point array. And already covers a scalarfloat
and an integer array.clip()
with scalar min/max clarifications #926