Add compareByIndex helper function to Enum.

Fixes https://github.com/dart-lang/language/issues/1836

Bug: https://github.com/dart-lang/language/issues/1836
Change-Id: I43ef26403a379c795a0bdcdeb470b4818ffb721e
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/212573
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>
Reviewed-by: Nate Bosch <nbosch@google.com>

CHANGELOG.md

@@ -78,6 +78,10 @@
 - The experimental `waitFor` functionality, and the library containing only that
   function, are now deprecated.
 
+### `dart:core`
+
+- Add `Enum.compareByIndex` helper function for comparing enum values by index.
+
 ### Tools
 
 #### Dart command line

sdk/lib/core/enum.dart

@@ -20,4 +20,14 @@ abstract class Enum {
   /// This is also the index of the value in the
   /// enumerated type's static `values` list.
   int get index;
+
+  /// Compares two enum values by their [index].
+  ///
+  /// A generic [Comparator] function for enum types which
+  /// orders enum values by their [index] value, which corresponds
+  /// to the source order of the enum element declarations in
+  /// the `enum` declaration.
+  @Since("2.15")
+  static int compareByIndex<T extends Enum>(T value1, T value2) =>
+      value1.index - value2.index;
 }

tests/language/enum/enum_test.dart

@@ -93,6 +93,21 @@ main() {
   Expect.type<Enum>(Enum1._);
   Enum enumValue = Enum1._;
   Expect.equals(0, enumValue.index);
+
+  // Enum.compareByIndex orders enums correctly.
+  var enumValues = [Enum5.G, Enum5.H, Enum5.F];
+  for (var i = 0; i < 10; i++) {
+    enumValues.sort(Enum.compareByIndex);
+    enumValues.fold<int>(-1, (previousValue, element) {
+      Expect.isTrue(previousValue < element.index, "$enumValues");
+      return element.index;
+    });
+    enumValues.shuffle();
+  }
+  // Can be used at the type `Enum` to compare different enums.
+  Expect.isTrue(Enum.compareByIndex<Enum>(Enum4.D, Enum5.H) < 0);
+  Expect.isTrue(Enum.compareByIndex<Enum>(Enum4.E, Enum5.F) > 0);
+  Expect.isTrue(Enum.compareByIndex<Enum>(Enum4.D, Enum5.F) == 0);
 }
 
 test1(Enum1 e) {

tests/language_2/enum/enum_test.dart

@@ -95,6 +95,21 @@ main() {
   Expect.type<Enum>(Enum1._);
   Enum enumValue = Enum1._;
   Expect.equals(0, enumValue.index);
+
+  // Enum.compareByIndex orders enums correctly.
+  var enumValues = [Enum5.G, Enum5.H, Enum5.F];
+  for (var i = 0; i < 10; i++) {
+    enumValues.sort(Enum.compareByIndex);
+    enumValues.fold<int>(-1, (previousValue, element) {
+      Expect.isTrue(previousValue < element.index, "$enumValues");
+      return element.index;
+    });
+    enumValues.shuffle();
+  }
+  // Can be used at the type `Enum` to compare different enums.
+  Expect.isTrue(Enum.compareByIndex<Enum>(Enum4.D, Enum5.H) < 0);
+  Expect.isTrue(Enum.compareByIndex<Enum>(Enum4.E, Enum5.F) > 0);
+  Expect.isTrue(Enum.compareByIndex<Enum>(Enum4.D, Enum5.F) == 0);
 }
 
 test1(Enum1 e) {