Skip to content

clip: ambiguous wording for scalar min/max #925

Open
@crusaderky

Description

@crusaderky

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 either min or max 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 or max is incompatible with the data type of x (x has integer data type and either min or max 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.

XREFs

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions