clip

clip(x: array, /, min: int | float | array | None = None, max: int | float | array | None = None) → array

Clamps each element x_i of the input array x to the range [min, max].

Parameters:

  • x (array) – input array. Should have a real-valued data type.

  • min (Optional[Union[int, float, array]]) – lower-bound of the range to which to clamp. If None, no lower bound must be applied. Must be compatible with x and max (see Broadcasting). Should have the same data type as x. Default: None.

  • max (Optional[Union[int, float, array]]) – upper-bound of the range to which to clamp. If None, no upper bound must be applied. Must be compatible with x and min (see Broadcasting). Should have the same data type as x. Default: None.

Returns:

out (array) – an array containing element-wise results. The returned array should have the same data type as x.

Notes

  • This function is conceptually equivalent to maximum(minimum(x, max), min) when x, min, and max have the same data type.

  • If both min and max are None, the elements of the returned array must equal the respective elements in x.

  • If a broadcasted element in min is greater than a corresponding broadcasted element in max, behavior is unspecified and thus implementation-dependent.

  • 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.

  • If x has an integral data type and a broadcasted element in min or max is outside the bounds of the data type of x, behavior is unspecified and thus implementation-dependent.

  • If either min or max is an array having a different data type than x, behavior is unspecified and thus implementation-dependent.

Special cases

  • If x_i is NaN, the result is NaN.

  • If min_i is NaN, the result is NaN.

  • If max_i is NaN, the result is NaN.

New in version 2023.12.

Changed in version 2024.12: Added special case behavior when one of the operands is NaN.

Changed in version 2024.12: Clarified that behavior is only defined when x, min, and max resolve to arrays having the same data type.

Changed in version 2024.12: Clarified that behavior is only defined when elements of min and max are inside the bounds of the input array data type.