Add a `clamp` function to the `math` module

[SFM61319]

BPO	41408
Nosy	@rhettinger, @mdickinson, @tirkarthi, @SFM61319
Superseder	bpo-36788: Add clamp() function to builtins

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-07-27.16:23:46.367>
created_at = <Date 2020-07-27.12:28:33.417>
labels = ['type-feature', 'library', '3.10']
title = 'Add a `clamp` function to the `math` module'
updated_at = <Date 2020-07-28.07:32:49.941>
user = 'https://github.com/SFM61319'

bugs.python.org fields:

activity = <Date 2020-07-28.07:32:49.941>
actor = 'mark.dickinson'
assignee = 'none'
closed = True
closed_date = <Date 2020-07-27.16:23:46.367>
closer = 'SFM61319'
components = ['Library (Lib)']
creation = <Date 2020-07-27.12:28:33.417>
creator = 'SFM61319'
dependencies = []
files = []
hgrepos = []
issue_num = 41408
keywords = []
message_count = 6.0
messages = ['374373', '374376', '374388', '374391', '374393', '374396']
nosy_count = 5.0
nosy_names = ['rhettinger', 'mark.dickinson', 'stutzbach', 'xtreak', 'SFM61319']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '36788'
type = 'enhancement'
url = 'https://bugs.python.org/issue41408'
versions = ['Python 3.10']

[SFM61319]

Add a clamp function to the math module which does something like this:

def clamp(value=0.5, minimum=0, maximum=1):
    """Clamps the *value* between the *minimum* and *maximum* and returns it..

<And some extra explanatory documentation with examples>
"""

    return max(minimum, min(value, maximum))

Because even C++ has built-in clamp function (std::clamp) (which can be used using #include <math.h>)

[tirkarthi]

This seems to be a duplicate of https://bugs.python.org/issue36788

[SFM61319]

Oh, I didn't know that. But I was thinking of adding it to the math module and not as a built-in method. I mean, it is definitely more useful than copysign, right?

[tirkarthi]

I will leave it to math module experts to keep it open or close it. There wasn't strong consensus on adding it math module either without a discussion in python-ideas https://bugs.python.org/msg358789.

[SFM61319]

So should I delete/reject this now? Because I think it would be more useful than functions like copysign (I mean copysign can be written easily without confusion, but clamp is confusing sometimes as the max function takes minimum and the min of value and the maximum, and yet we have a copysign function but not a clamp built-in or a math module function).

(I'll delete/reject if you guys want me to, np)

[SFM61319]

Okay, I'm rejecting this issue. But please let me know/contribute if anyone is going to add a clamp function as a built-in method or a math module function.

[samtygier-stfc]

In case this is ever reconsidered: Numpy has a clip method, so that might be a good name for consistency.

I think clamp/clip is something I'd expect to find in math library. It exists in c++, rust, julia ...