@grain/stdlib 0.5.2 → 0.5.3

package/runtime/numbers.gr

@@ -20,6 +20,7 @@ primitive (||): (Bool, Bool) -> Bool = "@or"
 primitive throw: Exception -> a = "@throw"
 
 exception UnknownNumberTag
+exception InvariantViolation
 
 import {
   newRational,
@@ -84,6 +85,28 @@ export let isFloat = x => {
   }
 }
 
+@unsafe
+export let isInteger = x => {
+  if (isBoxedNumber(x)) {
+    let tag = WasmI32.load(x, 4n)
+    WasmI32.eq(tag, Tags._GRAIN_INT32_BOXED_NUM_TAG) ||
+    WasmI32.eq(tag, Tags._GRAIN_INT64_BOXED_NUM_TAG) ||
+    WasmI32.eq(tag, Tags._GRAIN_BIGINT_BOXED_NUM_TAG)
+  } else {
+    true
+  }
+}
+
+@unsafe
+export let isRational = x => {
+  if (isBoxedNumber(x)) {
+    let tag = WasmI32.load(x, 4n)
+    WasmI32.eq(tag, Tags._GRAIN_RATIONAL_BOXED_NUM_TAG)
+  } else {
+    false
+  }
+}
+
 @unsafe
 let isBigInt = x => {
   if (isBoxedNumber(x)) {
@@ -635,7 +658,7 @@ let numberEqualRationalHelp = (xptr, y) => {
           BI.toFloat32(xNumerator),
           BI.toFloat32(xDenominator)
         )
-        // TODO: (#303) maybe we should have some sort of tolerance?
+        // TODO(#303): maybe we should have some sort of tolerance?
         WasmF32.eq(xAsFloat, yBoxedVal)
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
@@ -644,7 +667,7 @@ let numberEqualRationalHelp = (xptr, y) => {
           BI.toFloat64(xNumerator),
           BI.toFloat64(xDenominator)
         )
-        // TODO: (#303) maybe we should have some sort of tolerance?
+        // TODO(#303): maybe we should have some sort of tolerance?
         WasmF64.eq(xAsFloat, yBoxedVal)
       },
       _ => {
@@ -686,12 +709,12 @@ let numberEqualFloat64Help = (x, y) => {
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
         let yBoxedVal = boxedFloat32Number(y)
-        // TODO: (#303) maybe we should have some sort of tolerance?
+        // TODO(#303): maybe we should have some sort of tolerance?
         WasmF64.eq(x, WasmF64.promoteF32(yBoxedVal))
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
         let yBoxedVal = boxedFloat64Number(y)
-        // TODO: (#303) maybe we should have some sort of tolerance?
+        // TODO(#303): maybe we should have some sort of tolerance?
         WasmF64.eq(x, yBoxedVal)
       },
       _ => {
@@ -873,7 +896,6 @@ let numberAddSubSimpleHelp = (x, y, isSub) => {
         let xval = WasmF32.convertI32S(xval)
         let result = if (isSub) WasmF32.sub(xval, yBoxedVal)
           else WasmF32.add(xval, yBoxedVal)
-        // TODO: (#304) is this safe?
         newFloat32(result)
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
@@ -971,7 +993,6 @@ let numberAddSubInt64Help = (xval, y, isSub) => {
         let yBoxedVal = boxedFloat32Number(y)
         let result = if (isSub) WasmF32.sub(xval, yBoxedVal)
           else WasmF32.add(xval, yBoxedVal)
-        // TODO(#304): this isn't safe enough
         newFloat32(result)
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
@@ -1083,7 +1104,6 @@ let numberAddSubBigIntHelp = (x, y, isSub) => {
         let yBoxedVal = boxedFloat32Number(y)
         let result = if (isSub) WasmF32.sub(xval, yBoxedVal)
           else WasmF32.add(xval, yBoxedVal)
-        // TODO: (#304) this isn't safe enough
         newFloat32(result)
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
@@ -1326,7 +1346,6 @@ let numberTimesDivideInt64Help = (xval, y, isDivide) => {
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
         let xval = WasmF32.convertI64S(xval)
         let yBoxedVal = boxedFloat32Number(y)
-        // TODO: (#304) is this safe?
         if (isDivide) {
           newFloat32(WasmF32.div(xval, yBoxedVal))
         } else {
@@ -1407,7 +1426,6 @@ let numberTimesDivideBigIntHelp = (x, y, isDivide) => {
         // we can only fit rather small bigints (<4 limbs) into an F32
         let xval = BI.toFloat64(x)
         let yBoxedVal = WasmF64.promoteF32(boxedFloat32Number(y))
-        // TODO: (#304) is this safe?
         if (isDivide) {
           newFloat64(WasmF64.div(xval, yBoxedVal))
         } else {
@@ -1530,7 +1548,6 @@ let numberTimesDivideRationalHelp = (x, y, isDivide) => {
         let yDenominator = boxedRationalDenominator(y)
         // (a / b) * (c / d) == (a * c) / (b * d)
         // (a / b) / (c / d) == (a * d) / (b * c)
-        // TODO: (#304) this could maybe be written in a more overflow-proof way
         let numerator = if (isDivide) BI.mul(xNumerator, yDenominator)
           else BI.mul(xNumerator, yNumerator)
         let denominator = if (isDivide) BI.mul(xDenominator, yNumerator)
@@ -1681,9 +1698,18 @@ let numberMod = (x, y) => {
 }
 
 /*
- * ===== LESS THAN / GREATER THAN / LESS EQUAL / GREATER EQUAL =====
- * Coerce to float64 and then do comparisons
- * TODO: (#305) Could probably be made more efficient
+ * ===== COMPARISONS =====
+ * Int/int and float/float comparisons are always accurate.
+ * Rational/rational comparisons are approximations with the exception of
+ * equality, which is always accurate.
+ * 
+ * Values compared to floats or rationals are first converted to floats.
+ * 
+ * All comparison operators consider NaN not equal to, less than, or greater
+ * than NaN, with the exception of `compare`, which considers NaN equal to
+ * itself and otherwise smaller than any other float value. This provides a
+ * total order (https://en.wikipedia.org/wiki/Total_order) over all numerical
+ * values, making `compare` suitable for sorting or ordering.
  */
 
 @unsafe
@@ -1721,81 +1747,286 @@ let cmpBigInt = (x: WasmI32, y: WasmI32) => {
   }
 }
 
-// TODO: (#305) is this safe? I think it's safe?
 @unsafe
-export let (<) = (x: Number, y: Number) => {
-  let xw32 = WasmI32.fromGrain(x)
-  let yw32 = WasmI32.fromGrain(y)
-  if (isBigInt(xw32)) {
-    WasmI32.ltS(cmpBigInt(xw32, yw32), 0n)
-  } else if (isBigInt(yw32)) {
-    WasmI32.geS(cmpBigInt(yw32, xw32), 0n)
+let cmpFloat = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
+  let xf = if (is64) {
+    boxedFloat64Number(x)
   } else {
-    let xval = coerceNumberToWasmF64(x)
-    let yval = coerceNumberToWasmF64(y)
-    WasmF64.lt(xval, yval)
+    WasmF64.promoteF32(boxedFloat32Number(x))
+  }
+  if (isSimpleNumber(y)) {
+    let yf = WasmF64.convertI32S(untagSimple(y))
+    // special NaN cases
+    if (totalOrdering && WasmF64.ne(xf, xf)) {
+      if (WasmF64.ne(yf, yf)) {
+        0n
+      } else {
+        -1n
+      }
+    } else if (totalOrdering && WasmF64.ne(yf, yf)) {
+      if (WasmF64.ne(xf, xf)) {
+        0n
+      } else {
+        1n
+      }
+    } else {
+      if (WasmF64.lt(xf, yf)) -1n else if (WasmF64.gt(xf, yf)) 1n else 0n
+    }
+  } else {
+    let yBoxedNumberTag = boxedNumberTag(y)
+    if (yBoxedNumberTag == Tags._GRAIN_BIGINT_BOXED_NUM_TAG) {
+      WasmI32.sub(0n, cmpBigInt(y, x))
+    } else {
+      let yf = match (yBoxedNumberTag) {
+        t when WasmI32.eq(t, Tags._GRAIN_INT32_BOXED_NUM_TAG) => {
+          WasmF64.convertI32S(boxedInt32Number(y))
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_INT64_BOXED_NUM_TAG) => {
+          WasmF64.convertI64S(boxedInt64Number(y))
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_BIGINT_BOXED_NUM_TAG) => {
+          throw InvariantViolation
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_RATIONAL_BOXED_NUM_TAG) => {
+          WasmF64.div(
+            BI.toFloat64(boxedRationalNumerator(y)),
+            BI.toFloat64(boxedRationalDenominator(y))
+          )
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
+          WasmF64.promoteF32(boxedFloat32Number(y))
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
+          boxedFloat64Number(y)
+        },
+        _ => {
+          throw UnknownNumberTag
+        },
+      }
+      // special NaN cases
+      if (totalOrdering && WasmF64.ne(xf, xf)) {
+        if (WasmF64.ne(yf, yf)) {
+          0n
+        } else {
+          -1n
+        }
+      } else if (totalOrdering && WasmF64.ne(yf, yf)) {
+        if (WasmF64.ne(xf, xf)) {
+          0n
+        } else {
+          1n
+        }
+      } else {
+        if (WasmF64.lt(xf, yf)) -1n else if (WasmF64.gt(xf, yf)) 1n else 0n
+      }
+    }
   }
 }
 
 @unsafe
-export let (>) = (x: Number, y: Number) => {
-  let xw32 = WasmI32.fromGrain(x)
-  let yw32 = WasmI32.fromGrain(y)
-  if (isBigInt(xw32)) {
-    WasmI32.gtS(cmpBigInt(xw32, yw32), 0n)
-  } else if (isBigInt(yw32)) {
-    WasmI32.leS(cmpBigInt(yw32, xw32), 0n)
+let cmpSmallInt = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
+  let xi = if (is64) {
+    boxedInt64Number(x)
   } else {
-    let xval = coerceNumberToWasmF64(x)
-    let yval = coerceNumberToWasmF64(y)
-    WasmF64.gt(xval, yval)
+    WasmI64.extendI32S(boxedInt32Number(x))
+  }
+  if (isSimpleNumber(y)) {
+    let yi = WasmI64.extendI32S(untagSimple(y))
+    if (WasmI64.ltS(xi, yi)) -1n else if (WasmI64.gtS(xi, yi)) 1n else 0n
+  } else {
+    let yBoxedNumberTag = boxedNumberTag(y)
+    match (yBoxedNumberTag) {
+      t when WasmI32.eq(t, Tags._GRAIN_INT32_BOXED_NUM_TAG) => {
+        let yi = WasmI64.extendI32S(boxedInt32Number(y))
+        if (WasmI64.ltS(xi, yi)) -1n else if (WasmI64.gtS(xi, yi)) 1n else 0n
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_INT64_BOXED_NUM_TAG) => {
+        let yi = boxedInt64Number(y)
+        if (WasmI64.ltS(xi, yi)) -1n else if (WasmI64.gtS(xi, yi)) 1n else 0n
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_BIGINT_BOXED_NUM_TAG) => {
+        WasmI32.sub(0n, cmpBigInt(y, x))
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_RATIONAL_BOXED_NUM_TAG) => {
+        // Rationals and ints are never considered equal
+        if (
+          WasmF64.lt(
+            WasmF64.convertI64S(xi),
+            WasmF64.div(
+              BI.toFloat64(boxedRationalNumerator(y)),
+              BI.toFloat64(boxedRationalDenominator(y))
+            )
+          )
+        ) -1n else 1n
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
+        WasmI32.sub(0n, cmpFloat(y, x, false, totalOrdering))
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
+        WasmI32.sub(0n, cmpFloat(y, x, true, totalOrdering))
+      },
+      _ => {
+        throw UnknownNumberTag
+      },
+    }
   }
 }
 
 @unsafe
-export let (<=) = (x: Number, y: Number) => {
-  let xw32 = WasmI32.fromGrain(x)
-  let yw32 = WasmI32.fromGrain(y)
-  if (isBigInt(xw32)) {
-    WasmI32.leS(cmpBigInt(xw32, yw32), 0n)
-  } else if (isBigInt(yw32)) {
-    WasmI32.geS(cmpBigInt(yw32, xw32), 0n)
+let cmpRational = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
+  if (isSimpleNumber(y)) {
+    let xf = WasmF64.div(
+      BI.toFloat64(boxedRationalNumerator(x)),
+      BI.toFloat64(boxedRationalDenominator(x))
+    )
+    // Rationals and ints are never considered equal
+    if (WasmF64.lt(xf, WasmF64.convertI32S(untagSimple(y)))) -1n else 1n
   } else {
-    // Equality is finicky, so delegate
-    let xval = coerceNumberToWasmF64(x)
-    let yval = coerceNumberToWasmF64(y)
-    if (WasmF64.lt(xval, yval)) {
-      true
-    } else {
-      let x = WasmI32.fromGrain(x)
-      let y = WasmI32.fromGrain(y)
-      numberEqual(x, y)
+    let yBoxedNumberTag = boxedNumberTag(y)
+    match (yBoxedNumberTag) {
+      t when WasmI32.eq(t, Tags._GRAIN_INT32_BOXED_NUM_TAG) => {
+        WasmI32.sub(0n, cmpSmallInt(y, x, false, totalOrdering))
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_INT64_BOXED_NUM_TAG) => {
+        WasmI32.sub(0n, cmpSmallInt(y, x, true, totalOrdering))
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_BIGINT_BOXED_NUM_TAG) => {
+        WasmI32.sub(0n, cmpBigInt(y, x))
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_RATIONAL_BOXED_NUM_TAG) => {
+        // Comparing rationals efficiently is an open problem
+        // Producing a definitive answer is quite expensive, so if the two
+        // values are not strictly equal we approximate an answer
+
+        let xNumerator = boxedRationalNumerator(x)
+        let xDenominator = boxedRationalDenominator(x)
+        let yNumerator = boxedRationalNumerator(y)
+        let yDenominator = boxedRationalDenominator(y)
+
+        if (
+          BI.cmp(xNumerator, yNumerator) == 0n &&
+          BI.cmp(xDenominator, yDenominator) == 0n
+        ) {
+          0n
+        } else {
+          let xf = WasmF64.div(
+            BI.toFloat64(xNumerator),
+            BI.toFloat64(xDenominator)
+          )
+          let yf = WasmF64.div(
+            BI.toFloat64(yNumerator),
+            BI.toFloat64(yDenominator)
+          )
+          if (WasmF64.lt(xf, yf)) -1n else 1n
+        }
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
+        WasmI32.sub(0n, cmpFloat(y, x, false, totalOrdering))
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
+        WasmI32.sub(0n, cmpFloat(y, x, true, totalOrdering))
+      },
+      _ => {
+        throw UnknownNumberTag
+      },
     }
   }
 }
 
 @unsafe
-export let (>=) = (x: Number, y: Number) => {
-  let xw32 = WasmI32.fromGrain(x)
-  let yw32 = WasmI32.fromGrain(y)
-  if (isBigInt(xw32)) {
-    WasmI32.leS(cmpBigInt(xw32, yw32), 0n)
-  } else if (isBigInt(yw32)) {
-    WasmI32.geS(cmpBigInt(yw32, xw32), 0n)
-  } else {
-    // Equality is finicky, so delegate
-    let xval = coerceNumberToWasmF64(x)
-    let yval = coerceNumberToWasmF64(y)
-    if (WasmF64.gt(xval, yval)) {
-      true
+export let cmp = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
+  if (isSimpleNumber(x)) {
+    if (isSimpleNumber(y)) {
+      if (WasmI32.ltS(x, y)) -1n else if (WasmI32.gtS(x, y)) 1n else 0n
     } else {
-      let x = WasmI32.fromGrain(x)
-      let y = WasmI32.fromGrain(y)
-      numberEqual(x, y)
+      let yBoxedNumberTag = boxedNumberTag(y)
+      match (yBoxedNumberTag) {
+        t when WasmI32.eq(t, Tags._GRAIN_INT32_BOXED_NUM_TAG) => {
+          WasmI32.sub(0n, cmpSmallInt(y, x, false, totalOrdering))
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_INT64_BOXED_NUM_TAG) => {
+          WasmI32.sub(0n, cmpSmallInt(y, x, true, totalOrdering))
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_BIGINT_BOXED_NUM_TAG) => {
+          WasmI32.sub(0n, cmpBigInt(y, x))
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_RATIONAL_BOXED_NUM_TAG) => {
+          WasmI32.sub(0n, cmpRational(y, x, totalOrdering))
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
+          WasmI32.sub(0n, cmpFloat(y, x, false, totalOrdering))
+        },
+        t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
+          WasmI32.sub(0n, cmpFloat(y, x, true, totalOrdering))
+        },
+        _ => {
+          throw UnknownNumberTag
+        },
+      }
+    }
+  } else {
+    let xBoxedNumberTag = boxedNumberTag(x)
+    match (xBoxedNumberTag) {
+      t when WasmI32.eq(t, Tags._GRAIN_INT32_BOXED_NUM_TAG) => {
+        cmpSmallInt(x, y, false, totalOrdering)
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_INT64_BOXED_NUM_TAG) => {
+        cmpSmallInt(x, y, true, totalOrdering)
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_BIGINT_BOXED_NUM_TAG) => {
+        cmpBigInt(x, y)
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_RATIONAL_BOXED_NUM_TAG) => {
+        cmpRational(x, y, totalOrdering)
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
+        cmpFloat(x, y, false, totalOrdering)
+      },
+      t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
+        cmpFloat(x, y, true, totalOrdering)
+      },
+      _ => {
+        throw UnknownNumberTag
+      },
     }
   }
 }
 
+@unsafe
+export let (<) = (x: Number, y: Number) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.ltS(cmp(x, y, false), 0n)
+}
+
+@unsafe
+export let (>) = (x: Number, y: Number) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.gtS(cmp(x, y, false), 0n)
+}
+
+@unsafe
+export let (<=) = (x: Number, y: Number) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.leS(cmp(x, y, false), 0n)
+}
+
+@unsafe
+export let (>=) = (x: Number, y: Number) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.geS(cmp(x, y, false), 0n)
+}
+
+@unsafe
+export let compare = (x: Number, y: Number) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.toGrain(tagSimple(cmp(x, y, true))): Number
+}
+
 /*
  * ===== EQUAL =====
  */
@@ -1811,7 +2042,7 @@ export let numberEq = (x: Number, y: Number) => {
  * ===== LOGICAL OPERATIONS =====
  * Only valid for int-like numbers. Coerce to i64/bigInt and do operations
  */
-// TODO: (#306) Semantics around when things should stay i32/i64
+// TODO(#306): Semantics around when things should stay i32/i64
 
 @unsafe
 export let lnot = (x: Number) => {
@@ -1833,7 +2064,15 @@ export let (<<) = (x: Number, y: Number) => {
   } else {
     let xval = coerceNumberToWasmI64(x)
     let yval = coerceNumberToWasmI64(y)
-    WasmI32.toGrain(reducedInteger(WasmI64.shl(xval, yval))): Number
+    // if the number will be shifted beyond the end of the i64 range, promote to BigInt
+    // (note that we subtract one leading zero, since the leading bit is the sign bit)
+    if (WasmI64.leU(WasmI64.sub(WasmI64.clz(i64abs(xval)), 1N), yval)) {
+      let xbi = coerceNumberToBigInt(x)
+      let yval = coerceNumberToWasmI32(y)
+      WasmI32.toGrain(reducedBigInteger(BI.shl(xbi, yval))): Number
+    } else {
+      WasmI32.toGrain(reducedInteger(WasmI64.shl(xval, yval))): Number
+    }
   }
 }
 

package/runtime/numbers.md

@@ -10,6 +10,18 @@ isBoxedNumber : WasmI32 -> Bool
 isFloat : WasmI32 -> Bool
 ```
 
+### Numbers.**isInteger**
+
+```grain
+isInteger : WasmI32 -> Bool
+```
+
+### Numbers.**isRational**
+
+```grain
+isRational : WasmI32 -> Bool
+```
+
 ### Numbers.**isNumber**
 
 ```grain
@@ -94,6 +106,12 @@ coerceNumberToWasmI32 : Number -> WasmI32
 numberEqual : (WasmI32, WasmI32) -> Bool
 ```
 
+### Numbers.**cmp**
+
+```grain
+cmp : (WasmI32, WasmI32, Bool) -> WasmI32
+```
+
 ### Numbers.**(<)**
 
 ```grain
@@ -118,6 +136,12 @@ numberEqual : (WasmI32, WasmI32) -> Bool
 (>=) : (Number, Number) -> Bool
 ```
 
+### Numbers.**compare**
+
+```grain
+compare : (Number, Number) -> Number
+```
+
 ### Numbers.**numberEq**
 
 ```grain

package/set.gr

@@ -454,8 +454,7 @@ export let intersect = (set1, set2) => {
   set
 }
 
-// TODO: Should return a Record type instead of a Tuple
-// Waiting on https://github.com/grain-lang/grain/issues/190
+// TODO(#190): Should return a Record type instead of a Tuple
 /**
  * Provides data representing the internal state state of the set.
  *