std.mem.compare: breaking API changes

* `std.mem.Compare` is now `std.math.Order` and the enum tags
   renamed to follow new style convention.
 * `std.mem.compare` is renamed to `std.mem.order`.
 * new function `std.math.order`

lib/std/math.zig

@@ -926,9 +926,6 @@ test "minInt and maxInt" {
 }
 
 test "max value type" {
-    // If the type of maxInt(i32) was i32 then this implicit cast to
-    // u32 would not work. But since the value is a number literal,
-    // it works fine.
     const x: u32 = maxInt(i32);
     testing.expect(x == 2147483647);
 }
@@ -944,7 +941,32 @@ test "math.mulWide" {
     testing.expect(mulWide(u8, 100, 100) == 10000);
 }
 
-/// Not to be confused with `std.mem.Compare`.
+/// See also `CompareOperator`.
+pub const Order = enum {
+    /// Less than (`<`)
+    lt,
+
+    /// Equal (`==`)
+    eq,
+
+    /// Greater than (`>`)
+    gt,
+};
+
+/// Given two numbers, this function returns the order they are with respect to each other.
+pub fn order(a: var, b: var) Order {
+    if (a == b) {
+        return .eq;
+    } else if (a < b) {
+        return .lt;
+    } else if (a > b) {
+        return .gt;
+    } else {
+        unreachable;
+    }
+}
+
+/// See also `Order`.
 pub const CompareOperator = enum {
     /// Less than (`<`)
     lt,
@@ -979,7 +1001,7 @@ pub fn compare(a: var, op: CompareOperator, b: var) bool {
     };
 }
 
-test "math.lt, et al < <= > >= between signed and unsigned" {
+test "compare between signed and unsigned" {
     testing.expect(compare(@as(i8, -1), .lt, @as(u8, 255)));
     testing.expect(compare(@as(i8, 2), .gt, @as(u8, 1)));
     testing.expect(!compare(@as(i8, -1), .gte, @as(u8, 255)));