min, max, and clamp apply to all Comparables

[DartBot]

This issue was originally filed by @seaneagan

---

dart:math (formerly the Math class) has min and max methods which accept and return nums, issue #44 additionally requests a related "clamp" method. These methods should be generalized to accept and return any Comparables.

For such methods to be type safe, they should be generic (issue #254 - Milestone-Later, which would cause type warnings (checked mode errors)
if these methods were made generic after the fact), and Comparable should have a type parameter(issue #1492). They would look something like:

T min<T extends Comparable<T>>(T x, T y);
T max<T extends Comparable<T>>(T x, T y);
T clamp<T extends Comparable<T>>(T x, T min, T max);

Generic method support would not be required though if they were instead instance methods in Comparable (which would also avoid the type argument on calls).

They could also potentially be static methods on Comparable if statics were supported in interfaces (http://dartbug.com/2975 except without restriction to go through a
default class).

[kasperl]

Added Area-Library, Triaged labels.

[lrhn]

Generic Comparable versions of clamp, min and max would be fine, but they would not give the same results as dart:math's num versions (even if the only difference is on NaN).

[lrhn]

Removed Type-Defect label.
Added Type-Enhancement label.

[DartBot]

This comment was originally written by @seaneagan

---

min, max, and clamp (and many others) are available as top-level functions in the contrast package:

https://pub.dartlang.org/packages/contrast
https://github.com/seaneagan/contrast

Of course if they were instance methods then they would propogate type info better. I think the difference with NaN is actually a good reason to make them instance methods (polymorphism), would just need to be documented.

[matanlurey]

I imagine the cost of adding these to Comparable without either default functions or new language features that allow incrementally adding APIs (extension methods) is not feasible without lots of effort.

[cbatson]

It's unclear why this was closed. Can it be re-opened? (Especially given the advent of extensions.)

[rakudrama]

@cbaston I think a reason (mentioned in 2013) is that min written purely in terms of compareTo gives the wrong result for double.nan.

[lrhn]

The min and max from dart:math preserve NaN, but num.clamp is actually written to be compatible with num.compareTo, treating NaN as the largest value.
It's also the one which is an instance method, so we can't just generalize it to other types.

We could add static min, max and extension clamp methods to Comparable, like:

class Comparable<T> { 
  // ...
  static T min<T extends Comparable<T>>(T v1, T v2) => v1.compareTo(v2) <= 0 ? v1 : v2;
  static T max<T extends Comparable<T>>(T v1, T v2) => v1.compareTo(v2) >= 0 ? v1 : v2;
}
extension ClampComparable<T extends Comparable<T>> on T {
  T clamp(T min, T max) => compareTo(min) < 0 ? min : compareTo(max) > 0 ? max : this;
}

The clamp would not apply to num, since it already has a clamp method.
(It also wouldn't match int or double, since they don't implement Comparable<int> or Comparable<double> respectively, they implement Comparable<num>, and type inference won't guess that num is the solution it needs here.)