From dd66fb9a2b2476f3d4e4d5c3b504a9ceb76a5cee Mon Sep 17 00:00:00 2001
From: Oliver Booth <me@olivr.me>
Date: Sun, 17 Jan 2021 13:31:59 +0000
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Add=20IComparable<T>.Clamp?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements #24
---
 .../ComparableExtensions.cs                   | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/X10D/src/ComparableExtensions/ComparableExtensions.cs b/X10D/src/ComparableExtensions/ComparableExtensions.cs
index 7948775..4861484 100644
--- a/X10D/src/ComparableExtensions/ComparableExtensions.cs
+++ b/X10D/src/ComparableExtensions/ComparableExtensions.cs
@@ -50,6 +50,43 @@ namespace X10D.ComparableExtensions
         {
             return actual.CompareTo(lower) > 0 && actual.CompareTo(upper) < 0;
         }
+        
+        /// <summary>
+        ///     Returns the current value clamped to the inclusive range of <paramref name="lower" /> and <paramref name="upper" />.
+        /// </summary>
+        /// <param name="value">The value to be clamped.</param>
+        /// <param name="lower">The lower bound of the result.</param>
+        /// <param name="upper">The upper bound of the result.</param>
+        /// <typeparam name="T">An <see cref="IComparable" /> type.</typeparam>
+        /// <returns>
+        ///     <paramref name="value" /> if <paramref name="lower" /> ≤ <paramref name="value" /> ≤ <paramref name="upper" />.
+        ///     -or-
+        ///     <paramref name="lower" /> if <paramref name="value" /> &lt; <paramref name="lower" />.
+        ///     -or-
+        ///     <paramref name="upper" /> if <paramref name="upper" /> &lt; <paramref name="value" />.
+        /// </returns>
+        /// <exception cref="ArgumentException"><paramref name="lower" /> is greater than <paramref name="upper" />.</exception>
+        /// <example>
+        /// <code lang="csharp">
+        /// int value = 42;
+        /// int lower = 0;
+        /// int upper = 20;
+        ///
+        /// int clamped = value.Clamp(lower, upper);
+        /// // clamped will be 20
+        /// </code>
+        /// </example>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static T Clamp<T>(this T value, T lower, T upper)
+            where T : IComparable<T>
+        {
+            if (lower.GreaterThan(upper))
+            {
+                throw new ArgumentException($@"{lower} cannot be greater than {upper}", nameof(lower));
+            }
+
+            return value.Max(lower).Min(upper);
+        }
 
         /// <summary>
         ///     Determines if the current value is greater than another value.