✨ Support excluded min/max in double (#4100)

dubzzz · web-flow · commit 19d9cbc866ab · 2023-07-24T20:14:26.000Z
* ✨ Support excluded min/max in `double` Up-to-now, it was not possible to ask for double between min and max with either min or max or both not in the range. Following the request #4046, we thought about it and started to offer ways to do so. * versions * Update website/docs/core-blocks/arbitraries/primitives/number.md * without excluded * safer check * better check boundaries * better check
diff --git a/.yarn/versions/de5677c4.yml b/.yarn/versions/de5677c4.yml
@@ -0,0 +1,8 @@
+releases:
+  fast-check: minor
+
+declined:
+  - "@fast-check/ava"
+  - "@fast-check/jest"
+  - "@fast-check/vitest"
+  - "@fast-check/worker"
diff --git a/packages/fast-check/src/arbitrary/double.ts b/packages/fast-check/src/arbitrary/double.ts
@@ -25,17 +25,31 @@ const safeNaN = Number.NaN;
  */
 export interface DoubleConstraints {
   /**
-   * Lower bound for the generated 64-bit floats (included)
+   * Lower bound for the generated 64-bit floats (included, see minExcluded to exclude it)
    * @defaultValue Number.NEGATIVE_INFINITY, -1.7976931348623157e+308 when noDefaultInfinity is true
    * @remarks Since 2.8.0
    */
   min?: number;
   /**
-   * Upper bound for the generated 64-bit floats (included)
+   * Should the lower bound (aka min) be excluded?
+   * Note: Excluding min=Number.NEGATIVE_INFINITY would result into having min set to -Number.MAX_VALUE.
+   * @defaultValue false
+   * @remarks Since 3.12.0
+   */
+  minExcluded?: boolean;
+  /**
+   * Upper bound for the generated 64-bit floats (included, see maxExcluded to exclude it)
    * @defaultValue Number.POSITIVE_INFINITY, 1.7976931348623157e+308 when noDefaultInfinity is true
    * @remarks Since 2.8.0
    */
   max?: number;
+  /**
+   * Should the upper bound (aka max) be excluded?
+   * Note: Excluding max=Number.POSITIVE_INFINITY would result into having max set to Number.MAX_VALUE.
+   * @defaultValue false
+   * @remarks Since 3.12.0
+   */
+  maxExcluded?: boolean;
   /**
    * By default, lower and upper bounds are -infinity and +infinity.
    * By setting noDefaultInfinity to true, you move those defaults to minimal and maximal finite values.
@@ -85,11 +99,15 @@ export function double(constraints: DoubleConstraints = {}): Arbitrary<number> {
   const {
     noDefaultInfinity = false,
     noNaN = false,
+    minExcluded = false,
+    maxExcluded = false,
     min = noDefaultInfinity ? -safeMaxValue : safeNegativeInfinity,
     max = noDefaultInfinity ? safeMaxValue : safePositiveInfinity,
   } = constraints;
-  const minIndex = safeDoubleToIndex(min, 'min');
-  const maxIndex = safeDoubleToIndex(max, 'max');
+  const minIndexRaw = safeDoubleToIndex(min, 'min');
+  const minIndex = minExcluded ? add64(minIndexRaw, Unit64) : minIndexRaw;
+  const maxIndexRaw = safeDoubleToIndex(max, 'max');
+  const maxIndex = maxExcluded ? substract64(maxIndexRaw, Unit64) : maxIndexRaw;
   if (isStrictlySmaller64(maxIndex, minIndex)) {
     // In other words: minIndex > maxIndex
     // Comparing min and max might be problematic in case min=+0 and max=-0
diff --git a/packages/fast-check/test/unit/arbitrary/__test-helpers__/FloatingPointHelpers.ts b/packages/fast-check/test/unit/arbitrary/__test-helpers__/FloatingPointHelpers.ts
@@ -1,6 +1,9 @@
 import * as fc from 'fast-check';
 import { DoubleConstraints } from '../../../../src/arbitrary/double';
 import { FloatConstraints } from '../../../../src/arbitrary/float';
+import { MAX_VALUE_32, floatToIndex } from '../../../../src/arbitrary/_internals/helpers/FloatHelpers';
+import { doubleToIndex } from '../../../../src/arbitrary/_internals/helpers/DoubleHelpers';
+import { substract64 } from '../../../../src/arbitrary/_internals/helpers/ArrayInt64';
 
 export function float32raw(): fc.Arbitrary<number> {
   return fc.integer().map((n32) => new Float32Array(new Int32Array([n32]).buffer)[0]);
@@ -17,48 +20,90 @@ export const defaultFloatRecordConstraints = {
   max: float32raw(),
   noDefaultInfinity: fc.boolean(),
   noNaN: fc.boolean(),
+  minExcluded: fc.boolean(),
+  maxExcluded: fc.boolean(),
 };
 
 export const defaultDoubleRecordConstraints = {
   min: float64raw(),
   max: float64raw(),
   noDefaultInfinity: fc.boolean(),
   noNaN: fc.boolean(),
+  minExcluded: fc.boolean(),
+  maxExcluded: fc.boolean(),
 };
 
 type ConstraintsInternalOut = FloatConstraints & DoubleConstraints;
 type ConstraintsInternal = {
   [K in keyof ConstraintsInternalOut]?: fc.Arbitrary<ConstraintsInternalOut[K]>;
 };
-function constraintsInternal(recordConstraints: ConstraintsInternal): fc.Arbitrary<ConstraintsInternalOut> {
+function constraintsInternal(
+  recordConstraints: ConstraintsInternal,
+  is32Bits: boolean
+): fc.Arbitrary<ConstraintsInternalOut> {
   return fc
     .record(recordConstraints, { withDeletedKeys: true })
-    .filter((ct) => (ct.min === undefined || !Number.isNaN(ct.min)) && (ct.max === undefined || !Number.isNaN(ct.max)))
     .filter((ct) => {
-      if (!ct.noDefaultInfinity) return true;
-      if (ct.min === Number.POSITIVE_INFINITY && ct.max === undefined) return false;
-      if (ct.min === undefined && ct.max === Number.NEGATIVE_INFINITY) return false;
-      return true;
+      // Forbid min and max to be NaN
+      return (ct.min === undefined || !Number.isNaN(ct.min)) && (ct.max === undefined || !Number.isNaN(ct.max));
     })
     .map((ct) => {
+      // Already valid ct, no min or no max: we just return it as-is
       if (ct.min === undefined || ct.max === undefined) return ct;
       const { min, max } = ct;
+      // Already valid ct, min < max: we just return it as-is
       if (min < max) return ct;
+      // Already valid ct, min <= max with -0 and 0 correctly ordered: we just return it as-is
       if (min === max && (min !== 0 || 1 / min <= 1 / max)) return ct;
+      // We have to exchange min and  max to get an ordered range
       return { ...ct, min: max, max: min };
+    })
+    .filter((ct) => {
+      // No issue when automatically defaulting to +/-inf
+      if (!ct.noDefaultInfinity) return true;
+      // Invalid range, cannot have min==inf if max has to default to +max_value
+      if (ct.min === Number.POSITIVE_INFINITY && ct.max === undefined) return false;
+      // Invalid range, cannot have max=-inf if min has to default to -max_value
+      if (ct.min === undefined && ct.max === Number.NEGATIVE_INFINITY) return false;
+      return true;
+    })
+    .filter((ct) => {
+      const defaultMax = ct.noDefaultInfinity ? (is32Bits ? MAX_VALUE_32 : Number.MAX_VALUE) : Number.POSITIVE_INFINITY;
+      const min = ct.min !== undefined ? ct.min : -defaultMax;
+      const max = ct.max !== undefined ? ct.max : defaultMax;
+      // Illegal range, values cannot be "min < value <= min" or "min <= value < min" or "min < value < min"
+      if ((ct.minExcluded || ct.maxExcluded) && min === max) return false;
+      // Always valid range given min !== max if min=-inf or max=+inf
+      if (ct.max === Number.POSITIVE_INFINITY || ct.min === Number.NEGATIVE_INFINITY) return true;
+      if (ct.minExcluded && ct.maxExcluded) {
+        if (is32Bits) {
+          const minIndex = floatToIndex(min);
+          const maxIndex = floatToIndex(max);
+          const distance = maxIndex - minIndex;
+          // Illegal range, no value in range if min and max are too close from each others and both excluded
+          if (distance === 1) return false;
+        } else {
+          const minIndex = doubleToIndex(min);
+          const maxIndex = doubleToIndex(max);
+          const distance = substract64(maxIndex, minIndex);
+          // Illegal range, no value in range if min and max are too close from each others and both excluded
+          if (distance.data[0] === 0 && distance.data[1] === 1) return false;
+        }
+      }
+      return true;
     });
 }
 
 export function floatConstraints(
   recordConstraints: Partial<typeof defaultFloatRecordConstraints> = defaultFloatRecordConstraints
 ): fc.Arbitrary<FloatConstraints> {
-  return constraintsInternal(recordConstraints);
+  return constraintsInternal(recordConstraints, true);
 }
 
 export function doubleConstraints(
   recordConstraints: Partial<typeof defaultDoubleRecordConstraints> = defaultDoubleRecordConstraints
 ): fc.Arbitrary<DoubleConstraints> {
-  return constraintsInternal(recordConstraints);
+  return constraintsInternal(recordConstraints, false);
 }
 
 export function isStrictlySmaller(fa: number, fb: number): boolean {
diff --git a/packages/fast-check/test/unit/arbitrary/double.spec.ts b/packages/fast-check/test/unit/arbitrary/double.spec.ts
@@ -55,7 +55,7 @@ describe('double', () => {
     );
   });
 
-  it('should accept any constraits defining min (not-NaN) equal to max', () => {
+  it('should accept any constraints defining min (not-NaN) equal to max', () => {
     fc.assert(
       fc.property(
         float64raw(),
@@ -75,6 +75,32 @@ describe('double', () => {
     );
   });
 
+  it('should reject any constraints defining min (not-NaN) equal to max if one is exclusive', () => {
+    fc.assert(
+      fc.property(
+        float64raw(),
+        fc.record({ noDefaultInfinity: fc.boolean(), noNaN: fc.boolean() }, { withDeletedKeys: true }),
+        fc.constantFrom('min', 'max', 'both'),
+        (f, otherCt, exclusiveMode) => {
+          // Arrange
+          fc.pre(!Number.isNaN(f));
+          spyArrayInt64();
+
+          // Act / Assert
+          expect(() =>
+            double({
+              ...otherCt,
+              min: f,
+              max: f,
+              minExcluded: exclusiveMode === 'min' || exclusiveMode === 'both',
+              maxExcluded: exclusiveMode === 'max' || exclusiveMode === 'both',
+            })
+          ).toThrowError();
+        }
+      )
+    );
+  });
+
   it('should reject NaN if specified for min', () => {
     // Arrange
     const arrayInt64 = spyArrayInt64();
@@ -123,9 +149,15 @@ describe('double', () => {
 
   if (typeof BigInt !== 'undefined') {
     it('should properly convert integer value for index between min and max into its associated float value', () => {
+      const withoutExcludedConstraints = {
+        ...defaultDoubleRecordConstraints,
+        minExcluded: fc.constant(false),
+        maxExcluded: fc.constant(false),
+      };
+
       fc.assert(
         fc.property(
-          fc.option(doubleConstraints(), { nil: undefined }),
+          fc.option(doubleConstraints(withoutExcludedConstraints), { nil: undefined }),
           fc.bigUintN(64),
           fc.option(fc.integer({ min: 2 }), { nil: undefined }),
           (ct, mod, biasFactor) => {
@@ -227,13 +259,15 @@ describe('double', () => {
           const { min, max } = minMaxForConstraints(ct);
           const minIndex = doubleToIndex(min);
           const maxIndex = doubleToIndex(max);
+          const expectedMinIndex = ct.minExcluded ? add64(minIndex, Unit64) : minIndex;
+          const expectedMaxIndex = ct.maxExcluded ? substract64(maxIndex, Unit64) : maxIndex;
 
           // Act
           double(ct);
 
           // Assert
           expect(arrayInt64).toHaveBeenCalledTimes(1);
-          expect(arrayInt64).toHaveBeenCalledWith(minIndex, maxIndex);
+          expect(arrayInt64).toHaveBeenCalledWith(expectedMinIndex, expectedMaxIndex);
         })
       );
     });
@@ -254,17 +288,31 @@ describe('double (integration)', () => {
       expect(v).not.toBe(Number.NaN); // should not produce NaN if explicitely asked not too
     }
     if (extra.min !== undefined && !Number.isNaN(v)) {
-      expect(v).toBeGreaterThanOrEqual(extra.min); // should always be greater than min when specified
+      if (extra.minExcluded) {
+        expect(v).toBeGreaterThan(extra.min); // should always be strictly greater than min when specified
+      } else {
+        expect(v).toBeGreaterThanOrEqual(extra.min); // should always be greater than min when specified
+      }
     }
     if (extra.max !== undefined && !Number.isNaN(v)) {
-      expect(v).toBeLessThanOrEqual(extra.max); // should always be smaller than max when specified
+      if (extra.maxExcluded) {
+        expect(v).toBeLessThan(extra.max); // should always be strictly smaller than max when specified
+      } else {
+        expect(v).toBeLessThanOrEqual(extra.max); // should always be smaller than max when specified
+      }
     }
     if (extra.noDefaultInfinity) {
       if (extra.min === undefined) {
         expect(v).not.toBe(Number.NEGATIVE_INFINITY); // should not produce -infinity when noInfinity and min unset
+        if (extra.minExcluded) {
+          expect(v).not.toBe(-Number.MAX_VALUE); // nor -max_value
+        }
       }
       if (extra.max === undefined) {
         expect(v).not.toBe(Number.POSITIVE_INFINITY); // should not produce +infinity when noInfinity and max unset
+        if (extra.minExcluded) {
+          expect(v).not.toBe(Number.MAX_VALUE); // nor max_value
+        }
       }
     }
   };
diff --git a/website/docs/core-blocks/arbitraries/primitives/number.md b/website/docs/core-blocks/arbitraries/primitives/number.md
@@ -187,6 +187,8 @@ The lower and upper bounds are included into the range of possible values.
 
 - `min?` — default: `-∞` and `-Number.MAX_VALUE` when `noDefaultInfinity:true` — _lower bound for the generated 32-bit floats (included)_
 - `max?` — default: `+∞` and `Number.MAX_VALUE` when `noDefaultInfinity:true` — _upper bound for the generated 32-bit floats (included)_
+- `minExcluded?` — default: `false` — _do not include `min` in the set of possible values_
+- `maxExcluded?` — default: `false` — _do not include `max` in the set of possible values_
 - `noDefaultInfinity?` — default: `false` — _use finite values for `min` and `max` by default_
 - `noNaN?` — default: `false` — _do not generate `Number.NaN`_
 
@@ -210,6 +212,10 @@ fc.double({ noDefaultInfinity: true, min: Number.NEGATIVE_INTEGER, max: Number.P
 // should not be set to -∞ and +∞. It does not forbid the user to explicitely set them to -∞ and +∞.
 // Examples of generated values: 7.593633990222606e-236, -5.74664305820822e+216, -1.243100551492039e-161, 1.797693134862313e+308, -1.7976931348623077e+308…
 
+fc.double({ min: 0, max: 1, maxExcluded: true });
+// Note: All possible floating point values between 0 (included) and 1 (excluded)
+// Examples of generated values: 4.8016271592767985e-73, 4.8825963576686075e-55, 0.9999999999999967, 0.9999999999999959, 2.5e-322…
+
 fc.tuple(fc.integer({ min: 0, max: (1 << 26) - 1 }), fc.integer({ min: 0, max: (1 << 27) - 1 }))
   .map((v) => (v[0] * Math.pow(2, 27) + v[1]) * Math.pow(2, -53))
   .noBias();
