Add SafeClamp(), which accepts args of different types

webrtc/base/safe_minmax.h

Index: webrtc/base/safe_minmax.h
diff --git a/webrtc/base/safe_minmax.h b/webrtc/base/safe_minmax.h
index 16638efc617feb6a38bdd8ae704a9ca153e725ce..f55bb96e6d6e12c648bc3d222f1b01cd176e4f22 100644
--- a/webrtc/base/safe_minmax.h
+++ b/webrtc/base/safe_minmax.h
@@ -25,10 +25,39 @@
 // because the floating-point type will have greater range, but may not have
 // sufficient precision to represent the integer value exactly.)
 //
+// Clamp (a.k.a. constrain to a given interval)
+// ============================================
+//
+//   rtc::SafeClamp(a, b, x)

[nisse-webrtc, 2017/06/02 13:00:54]

Do you have a good reason for this argument order? I'd put x first, and read it
"clamp x to the [a,b] interval".

[kwiberg-webrtc, 2017/06/02 13:12:37]

Yes---at least in my mind, the a and b arguments are "less variable", so it
feels right to put them closer to the function name.

In a language like Haskell, currying makes this point clear:

  SafeClamp a b x  -- clamp x to [a, b]
  SafeClamp a b    -- function that clamps its argument to [a, b]

In C++, there's no technical reason for this (or any other) argument order, but
it still feels right to order the arguments this way. In other words, I don't
think of SafeClamp(a, b, x) as "clamp x to [a, b]", I think of it as "apply
'clamp to [a, b]' to x".

[ossu, 2017/06/02 13:22:33]

I've got to agree with nisse here, in my mind having the value to be clamped
first makes the most sense. Fortunately, we don't have to rely completely on my
mind here. Looking at C++17's std::clamp, it's
std::clamp(v, lo, hi), (see: http://en.cppreference.com/w/cpp/algorithm/clamp).

I think it makes sense to follow that order, since SafeClamp will generally be a
stand-in for std::clamp, with some extra guarantees.

[kwiberg-webrtc, 2017/06/04 01:27:54]

OK, fine. You all have terrible taste, but there are lots more of you than of
me. ;-)

New patch set uploaded that changes the argument order, and makes some minor
changes to the comments in this file.

+//
+// Accepts three arguments of any mix of integral and floating-point types, and
+// returns the value in the closed interval [a, b] that is closest to x (that
+// is, if x < a it returns a; if x > b it returns b; and if a <= x <= b it
+// returns x). As for SafeMin() and SafeMax(), there is no truncation or
+// wrap-around. The result type
+//
+//   1. is statically guaranteed to be able to represent the result;
+//
+//   2. is no larger than the largest of the three argument types; and
+//
+//   3. has the same signedness as the type of the third argument, if this is
+//      possible without violating the First or Second Law.
+//
+// There is always at least one type that meets criteria 1 and 2. If more than
+// one type meets these criteria equally well, the result type is one of the
+// types that is smallest. Note that unlike SafeMin() and SafeMax(),
+// SafeClamp() will sometimes pick a return type that isn't the type of any of
+// its arguments.
+//
+// (In this context, a type A is smaller than a type B if it has a smaller
+// range; that is, if A::max() - A::min() < B::max() - B::min(). For example,
+// int8_t < int16_t == uint16_t < int32_t, and all integral types are smaller
+// than all floating-point types.)
+//
 // Requesting a specific return type
 // =================================
 //
-// Both functions allow callers to explicitly specify the return type as a
+// All three functions allow callers to explicitly specify the return type as a
 // template parameter, overriding the default return type. E.g.
 //
 //   rtc::SafeMin<int>(x, y)  // returns an int
@@ -187,6 +216,115 @@ constexpr R2 SafeMax(T1 a, T2 b) {
   return safe_cmp::Gt(a, b) ? static_cast<R2>(a) : static_cast<R2>(b);
 }
 
+namespace safe_minmax_impl {
+
+// Given three types L, H, and T, let ::type be a suitable return value for
+// SafeClamp(L, H, T). See the docs at the top of this file for details.
+template <typename L,
+          typename H,
+          typename T,
+          bool int1 = IsIntlike<L>::value,
+          bool int2 = IsIntlike<H>::value,
+          bool int3 = IsIntlike<T>::value>
+struct ClampType {
+  static_assert(int1 == int2 && int1 == int3,
+                "You may not mix integral and floating-point arguments");
+};
+
+// Specialization for when all three types are floating-point.
+template <typename L, typename H, typename T>
+struct ClampType<L, H, T, false, false, false> {
+  using type = typename std::common_type<L, H, T>::type;
+};
+
+// Specialization for when all three types are integral.
+template <typename L, typename H, typename T>
+struct ClampType<L, H, T, true, true, true> {
+ private:
+  // Range of the return value. The return type must be able to represent this
+  // full range.
+  static constexpr auto r_min =
+      SafeMax(Limits<L>::lowest, SafeMin(Limits<H>::lowest, Limits<T>::lowest));
+  static constexpr auto r_max =
+      SafeMin(Limits<H>::max, SafeMax(Limits<L>::max, Limits<T>::max));
+
+  // Is the given type an acceptable return type? (That is, can it represent
+  // all possible return values, and is it no larger than the largest of the
+  // input types?)
+  template <typename A>
+  struct AcceptableType {
+   private:
+    static constexpr bool not_too_large = sizeof(A) <= sizeof(L) ||
+                                          sizeof(A) <= sizeof(H) ||
+                                          sizeof(A) <= sizeof(T);
+    static constexpr bool range_contained =
+        safe_cmp::Le(Limits<A>::lowest, r_min) &&
+        safe_cmp::Le(r_max, Limits<A>::max);
+
+   public:
+    static constexpr bool value = not_too_large && range_contained;
+  };
+
+  using best_signed_type = typename std::conditional<
+      AcceptableType<int8_t>::value,
+      int8_t,
+      typename std::conditional<
+          AcceptableType<int16_t>::value,
+          int16_t,
+          typename std::conditional<AcceptableType<int32_t>::value,
+                                    int32_t,
+                                    int64_t>::type>::type>::type;
+
+  using best_unsigned_type = typename std::conditional<
+      AcceptableType<uint8_t>::value,
+      uint8_t,
+      typename std::conditional<
+          AcceptableType<uint16_t>::value,
+          uint16_t,
+          typename std::conditional<AcceptableType<uint32_t>::value,
+                                    uint32_t,
+                                    uint64_t>::type>::type>::type;
+
+ public:
+  // Pick the best type, preferring the same signedness at T but falling back
+  // to the other one if necessary.
+  using type = typename std::conditional<
+      std::is_signed<T>::value,
+      typename std::conditional<AcceptableType<best_signed_type>::value,
+                                best_signed_type,
+                                best_unsigned_type>::type,
+      typename std::conditional<AcceptableType<best_unsigned_type>::value,
+                                best_unsigned_type,
+                                best_signed_type>::type>::type;
+  static_assert(AcceptableType<type>::value, "");
+};
+
+}  // namespace safe_minmax_impl
+
+template <
+    typename R = safe_minmax_impl::DefaultType,
+    typename L = safe_minmax_impl::DefaultType,
+    typename H = safe_minmax_impl::DefaultType,
+    typename T = safe_minmax_impl::DefaultType,
+    typename R2 = typename safe_minmax_impl::TypeOr<
+        R,
+        typename safe_minmax_impl::ClampType<
+            typename safe_minmax_impl::UnderlyingType<L>::type,
+            typename safe_minmax_impl::UnderlyingType<H>::type,
+            typename safe_minmax_impl::UnderlyingType<T>::type>::type>::type>
+R2 SafeClamp(L min, H max, T x) {
+  static_assert(IsIntlike<L>::value || std::is_floating_point<L>::value,
+                "The first argument must be integral or floating-point");
+  static_assert(IsIntlike<H>::value || std::is_floating_point<H>::value,
+                "The second argument must be integral or floating-point");
+  static_assert(IsIntlike<T>::value || std::is_floating_point<T>::value,
+                "The third argument must be integral or floating-point");
+  RTC_DCHECK_LE(min, max);
+  return safe_cmp::Le(x, min)
+             ? static_cast<R2>(min)
+             : safe_cmp::Ge(x, max) ? static_cast<R2>(max) : static_cast<R2>(x);
+}
+
 }  // namespace rtc
 
 #endif  // WEBRTC_BASE_SAFE_MINMAX_H_