Is there a "canonical" name for a function combining min() and max()?

Question

I find that I frequently end up writing a function that I always call "clamp()", that is kind of a combination of min() and max(). Is there a standard, "canonical" name for this function?

It always looks something like this:

function clamp($val, $lower, $upper)
{
  if ($val < $lower)
    return $lower;
  else if ($val > $upper)
    return $upper;
  else
    return $val;
}

Or simply using built-in min() and max() functions:

function clamp($val, $lower, $upper)
{
  return max($lower, min($upper, $val));
}

Variations exist: You can also check for invalid input, where lower > upper, and either throw an exception or reverse the inputs. Or you can ignore order of the inputs and call it a median-of-three function, but that can be confusing.

I'd avoid giving your parameters the same names as the functions used, particularly as they're not used in matching pairs (i.e. $min is used with max() and vice-versa). Perhaps $lower and $upper, instead. — Ben Blank, Feb 05 '09 at 16:39
I use the name InRange() but my comment is not about the name, it is about the ordering of the parameters. I find it easier to read: InRange(min,value,max) than (value,min,max) — Manuel Gonzalez, Oct 24 '12 at 18:39

score 37 · Accepted Answer · answered Feb 05 '09 at 16:00

37

clamp is a good name.

Let us make it the standard.

answered Feb 05 '09 at 16:00

Niyaz

53,943
55
151
182

2

Seems to be standard (at least in graphics) already: http://en.wikipedia.org/wiki/Clamping_%28graphics%29 – Zach Scrivena Feb 05 '09 at 16:05
Kind of a great name after I understood what it was. Plus one to the standard. – Rodrigo Feb 05 '09 at 16:10
1

I think "clip" is more commonly used. – John D. Cook Feb 05 '09 at 16:29
Numbers may be clamped, while images may be clipped. – yfeldblum Jul 09 '09 at 16:44
2

C++17 has `std::clamp`. – Knu Jun 28 '16 at 02:46

score 5 · Answer 2 · answered Feb 05 '09 at 16:06

5

In some languages you have the function limit

num = limit(val, min, max)

answered Feb 05 '09 at 16:06

Jim C

4,981
21
25

score 3 · Answer 3 · answered Feb 05 '09 at 16:26

3

clip(val, lo, hi)

answered Feb 05 '09 at 16:26

jfs

399,953
195
994
1,670

score 1 · Answer 4 · answered Feb 05 '09 at 16:43

1

We use pin here. Actually, we use pin for simple ranges and clamp for other stuff.

answered Feb 05 '09 at 16:43

MSN

53,214
7
75
105

Knu · Answer 5 · 2012-10-24T02:43:30.660

0

What about bound?

bound(min, val, max)

Or constrain?

constrain(val, min, max)

edited Oct 24 '12 at 02:43

answered Oct 17 '12 at 19:14

Knu

14,806
5
56
89

gbr · Answer 6 · 2014-04-30T14:57:40.790

What do you think of things like InRangeClosestTo(Number, RangeLowerBound, RangeUpperBound), or ClosestInRange(Number, LowerBoundOfRange, UpperBoundOfRange)? They mean 'Get me the element of the range closest to the number', as I hope is obvious.

The concept is more precise than a Clamp that yeah has two sides but not much more, or a Limit or Bound that might not want to return anything if the number is not within the range,

To me they are clearer then the rest I saw; although it can take a couple of seconds to understand them, you only need to reason about the name, and at most have a brief look at the comment for confirmation; and it's nice when you see how precise it is (it is precise, right?).

You might only have doubts on whether the range is inclusive or not, but I think most people would correctly assume it's inclusive. Alternatively you might use InInclRangeClosestTo and InExclRangeClosestTo, althought I don't see a lot of uses for exclusive ranges.

Of course you should have an auto-completing IDE if you wanted to use them.

score 0 · Answer 7 · answered Feb 05 '09 at 15:59

0

I'd just go for a function name "rangeCheck"

answered Feb 05 '09 at 15:59

tehvan

10,189
5
27
31

1

not good, rangeCheck sounds like it CHECKS. But what it does is CHANGING values to be in a range. – Thorsten79 Feb 05 '09 at 16:03

score -1 · Answer 8 · answered Feb 05 '09 at 16:41

-1

median

Because it generalizes to more values.

answered Feb 05 '09 at 16:41

Craig Gidney

17,763
5
68
136

1

This isn't about finding statistical information about a sample set. It's about forcing a number to be in a particular range. – MSN Feb 05 '09 at 16:44
2

@MSN: technically median(val, min, max) will do the same thing as clamp(val, min, max). plus, the order of the parameters to median() wouldn't matter. but that's not immediately obvious (at least, it wasn't to me). – Kip Feb 05 '09 at 17:46
Median has the advantage of being self descriptive. You get the median element back. For example, will "clamp" throw an exception if my min is less than my max? In that case, which argument is the min? First or second? These details might change from place to place. – Craig Gidney Feb 06 '09 at 01:25
I must disagree with median being self descriptive, since we don't want the median of a given set of values, but clamp a given value to some boundaries. While that may be the same operation internally (well not exactly, but close enough), the purpose of that median call wouldn't be as clear as for example clamp, so it gets harder for other people to read the code. – Grizzly Dec 31 '09 at 13:12

Is there a "canonical" name for a function combining min() and max()?

8 Answers8

Linked