I would like to clamp a value x to a range [a, b]:
x = (x < a) ? a : ((x > b) ? b : x);
This is quite basic. But I do not see a function "clamp" in the class library - at least not in System.Math.
(For the unaware to "clamp" a value is to make sure that it lies between some maximum and minimum values. If it’s greater than the max value, then it’s replaced by the max, etc.)
You could write an extension method:
public static T Clamp<T>(this T val, T min, T max) where T : IComparable<T>
{
if (val.CompareTo(min) < 0) return min;
else if(val.CompareTo(max) > 0) return max;
else return val;
}
Extension methods go in static classes - since this is quite a low-level function, it should probably go in some core namespace in your project. You can then use the method in any code file that contains a using directive for the namespace e.g.
using Core.ExtensionMethods
int i = 4.Clamp(1, 3);
Starting with .NET Core 2.0 System.Math now has a Clamp method that can be used instead:
using System;
int i = Math.Clamp(4, 1, 3);
IComparable is that no boxing occurs. This ought to run very fast. Remember that with double and float, the CompareTo method corresponds to a total order where NaN is less than all other values, including NegativeInfinity. So it is not equivalent to the < operator. If you used < with a floating-point type, you would have to consider how to treat NaN also. This is not relevant for other numeric types. –
Supervisor NaN in either case. The version with < and > would output NaN and using NaN for min or max would effectively make a one-sided clamp. With CompareTo it would always return NaN if max is NaN. –
Macro int c = Clamp(a, b, c) if you want. However I don't see how this implementation suggests the type is being changed. If you mean it implies the this parameter is being mutated, then I disagree since it returns a value. –
Moyra foo itself is never clamped. Would the extension have a more verbose name like CalcClampedVal this would be obvious. But now that I think about it more, my issue could be considered minor. –
Raven T is a reference type and val is null, we get a NullReferenceException. Note that Comparer<T>.Default.Compare(val, min) will consider null less than non-null, so you could use that if you wanted. Or check for null. Or constrain with where T : struct. (2) If some idiot one day passes a min and max that are in the wrong relative order, then it (unintensionally) becomes important that you check with min first. (Since val could satisfy both conditions.) We should throw an exception instead in that case. –
Supervisor Just use Math.Min and Math.Max:
x = Math.Min(Math.Max(x, a), b);
int a0 = x > a ? x : a; return a0 < b ? a0 : b which (although gives correct results) isn't exactly ideal. –
Mcgrew Math.Min(Math.Max(x, min), max) results in one more comparison than necessary if x < min. –
Laundes Try:
public static int Clamp(int value, int min, int max)
{
return (value < min) ? min : (value > max) ? max : value;
}
There isn't one, but it's not too hard to make one. I found one here: clamp
It is:
public static T Clamp<T>(T value, T max, T min)
where T : System.IComparable<T> {
T result = value;
if (value.CompareTo(max) > 0)
result = max;
if (value.CompareTo(min) < 0)
result = min;
return result;
}
And it can be used like:
int i = Clamp(12, 10, 0); -> i == 10
double d = Clamp(4.5, 10.0, 0.0); -> d == 4.5
Clamp(T value, T min, T max) –
Herald There isn't one in the System.Math namespace.
There is a MathHelper Class where it is available for the XNA game studio if that happens to be what you are doing:
Math.Clamp –
Rarotonga System.Math.Clamp is the method you want if you are on .NET 5+, .NET Core 3.x, or .NET Core 2.x.
var a = Math.Clamp(5, 1, 10); // = 5
var b = Math.Clamp(-99, 1, 10); // = 1
var c = Math.Clamp(99, 1, 10); // = 10
Just sharing Lee's solution with the comments' issues and concerns addressed, where possible:
public static T Clamped<T>(this T value, T min, T max) where T : IComparable<T> {
if (value == null) throw new ArgumentNullException(nameof(value), "is null.");
if (min == null) throw new ArgumentNullException(nameof(min), "is null.");
if (max == null) throw new ArgumentNullException(nameof(max), "is null.");
//If min <= max, clamp
if (min.CompareTo(max) <= 0) return value.CompareTo(min) < 0 ? min : value.CompareTo(max) > 0 ? max : value;
//If min > max, clamp on swapped min and max
return value.CompareTo(max) < 0 ? max : value.CompareTo(min) > 0 ? min : value;
}
Differences:
ed) to (further) indicate that the value is not clamped in-place, and that, instead, a new value is returned (See @JimBalter's comment).null check on all inputs (See @JeppeStigNielsen's comment).min and max if min > max (See @JeppeStigNielsen's comment).Limitations:
No one-sided clamps. If max is NaN, always returns NaN (See Herman's comment).
nameof does not work for C# 5 or below. –
Section Using the previous answers, I condensed it down to the below code for my needs. This will also allow you to clamp a number only by its min or max.
public static class IComparableExtensions
{
public static T Clamped<T>(this T value, T min, T max)
where T : IComparable<T>
{
return value.CompareTo(min) < 0 ? min : value.ClampedMaximum(max);
}
public static T ClampedMinimum<T>(this T value, T min)
where T : IComparable<T>
{
return value.CompareTo(min) < 0 ? min : value;
}
public static T ClampedMaximum<T>(this T value, T max)
where T : IComparable<T>
{
return value.CompareTo(max) > 0 ? max : value;
}
}
return value.ClampedMinimum(min).ClampedMaximum(max);? –
Zizith The below code supports specifying bounds in any order (i.e. bound1 <= bound2, or bound2 <= bound1). I've found this useful for clamping values calculated from linear equations (y=mx+b) where the slope of the line can be increasing or decreasing.
I know: The code consists of five super-ugly conditional expression operators. The thing is, it works, and the tests below prove it. Feel free to add strictly unnecessary parentheses if you so desire.
You can easily create other overloads for other numeric types and basically copy/paste the tests.
Warning: Comparing floating point numbers is not simple. This code does not implement double comparisons robustly. Use a floating point comparison library to replace the uses of comparison operators.
public static class MathExtensions
{
public static double Clamp(this double value, double bound1, double bound2)
{
return bound1 <= bound2 ? value <= bound1 ? bound1 : value >= bound2 ? bound2 : value : value <= bound2 ? bound2 : value >= bound1 ? bound1 : value;
}
}
xUnit/FluentAssertions tests:
public class MathExtensionsTests
{
[Theory]
[InlineData(0, 0, 0, 0)]
[InlineData(0, 0, 2, 0)]
[InlineData(-1, 0, 2, 0)]
[InlineData(1, 0, 2, 1)]
[InlineData(2, 0, 2, 2)]
[InlineData(3, 0, 2, 2)]
[InlineData(0, 2, 0, 0)]
[InlineData(-1, 2, 0, 0)]
[InlineData(1, 2, 0, 1)]
[InlineData(2, 2, 0, 2)]
[InlineData(3, 2, 0, 2)]
public void MustClamp(double value, double bound1, double bound2, double expectedValue)
{
value.Clamp(bound1, bound2).Should().Be(expectedValue);
}
}
If I want to validate the range of an argument in [min, max], the I use the following handy class:
public class RangeLimit<T> where T : IComparable<T>
{
public T Min { get; }
public T Max { get; }
public RangeLimit(T min, T max)
{
if (min.CompareTo(max) > 0)
throw new InvalidOperationException("invalid range");
Min = min;
Max = max;
}
public void Validate(T param)
{
if (param.CompareTo(Min) < 0 || param.CompareTo(Max) > 0)
throw new InvalidOperationException("invalid argument");
}
public T Clamp(T param) => param.CompareTo(Min) < 0 ? Min : param.CompareTo(Max) > 0 ? Max : param;
}
The class works for all object which are IComparable. I create an instance with a certain range:
RangeLimit<int> range = new RangeLimit<int>(0, 100);
I an either validate an argument
range.Validate(value);
or clamp the argument to the range:
var v = range.Validate(value);
Based on the @JeremyB answer, with suggested corrections.
namespace App
{
/// <summary>
/// Miscellaneous utilities.
/// </summary>
public static class Util
{
/// <summary>
/// Clamp a value to the inclusive range [min, max].
/// </summary>
/// <remarks>
/// In newer versions of the .NET Framework, there is a System.Math.Clamp() method.
/// </remarks>
/// <typeparam name="T">The type of value.</typeparam>
/// <param name="value">The value to clamp.</param>
/// <param name="min">The minimum value.</param>
/// <param name="max">The maximum value.</param>
/// <returns>The clamped value.</returns>
public static T clamp<T>( T value, T min, T max ) where T : System.IComparable<T>
{
if ( value.CompareTo( max ) > 0 )
{
return max;
}
if ( value.CompareTo( min ) < 0 )
{
return min;
}
return value;
}
}
}
© 2022 - 2024 — McMap. All rights reserved.