extended Bounded type

src/Bounded.ts

@@ -7,7 +7,10 @@
  *
  * @since 2.0.0
  */
-import { Ord, ordNumber } from './Ord'
+import * as Ord from './Ord'
+import { Option, fromPredicate } from './Option'
+import * as n from './number'
+import { pipe } from './function'
 
 // -------------------------------------------------------------------------------------
 // model
@@ -17,11 +20,126 @@ import { Ord, ordNumber } from './Ord'
  * @category type classes
  * @since 2.0.0
  */
-export interface Bounded<A> extends Ord<A> {
+export interface Bounded<A> extends Ord.Ord<A> {
   readonly top: A
   readonly bottom: A
 }
 
+// -------------------------------------------------------------------------------------
+// deconstructors
+// -------------------------------------------------------------------------------------
+
+/**
+ * @category deconstructors
+ * @since 2.12.0
+ */
+export const top = <T>(B: Bounded<T>) => B.top
+
+/**
+ * @category deconstructors
+ * @since 2.12.0
+ */
+export const bottom = <T>(B: Bounded<T>) => B.bottom
+
+/**
+ * Returns the tuple [bottom, top].
+ *
+ * @category deconstructors
+ * @since 2.12.0
+ */
+export const toTuple = <T>(B: Bounded<T>): [T, T] =>
+    [B.bottom, B.top]
+
+// -------------------------------------------------------------------------------------
+// guards
+// -------------------------------------------------------------------------------------
+
+/**
+ * Test that top >= bottom
+ *
+ * @category guards
+ * @since 2.12.0
+ */
+export const isValid = <T>(B: Bounded<T>) =>
+    Ord.leq(B)(B.bottom, B.top)
+
+// -------------------------------------------------------------------------------------
+// constructors
+// -------------------------------------------------------------------------------------
+
+/**
+ * Returns an instance of Bounded from a range of values.
+ * Returns none if bottom > top and some if top >= bottom.
+ *
+ * @category constructors
+ * @since 2.12.0
+ */
+export const fromRange = <T>(O: Ord.Ord<T>) => (b: T) => (t: T): Option<Bounded<T>> =>
+  pipe({ ...O, top: t, bottom: b }, fromPredicate(isValid))
+
+/**
+ * Creates an instance of Bounded from the tuple [bottom, top].
+ * Returns none if fst > snd and some if snd >= fst.
+ *
+ * @category constructors
+ * @since 2.12.0
+ */
+export const fromTuple = <T>(O: Ord.Ord<T>) => ([b, t]: [T, T]) =>
+  fromRange(O)(b)(t)
+
+/**
+ * Returns a valid instance of Bounded given two values where top is the greater of
+ * the two values and bottom is set to the smaller of the values.
+ *
+ * @category constructors
+ * @since 2.12.0
+ */
+export const coerceBound = <T>(O: Ord.Ord<T>) => (b: T) => (t: T): Bounded<T> =>
+  Ord.leq(O)(b, t) ? ({ ...O, bottom: b, top: t }) : ({ ...O, bottom: t, top: b })
+
+// -------------------------------------------------------------------------------------
+// utils
+// -------------------------------------------------------------------------------------
+
+/**
+ * Clamp a value between bottom and top values.
+ *
+ * @category utils
+ * @since 2.12.0
+ */
+export const clamp = <T>(B: Bounded<T>) =>
+    Ord.clamp(B)(B.bottom, B.top)
+
+/**
+ * Tests whether a value lies between the top and bottom values of bound.
+ *
+ * @category utils
+ * @since 2.12.0
+ */
+export const isWithin = <T>(B: Bounded<T>) =>
+    Ord.between(B)(B.bottom, B.top)
+
+/**
+ * Reverses the Ord of a bound and swaps top and bottom values.
+ *
+ * @category utils
+ * @since 2.12.0
+ */
+export const reverse = <T>(B: Bounded<T>): Bounded<T> => ({
+    ...Ord.reverse(B),
+    top: B.bottom,
+    bottom: B.top
+})
+
+/**
+ * Tests whether the bounded range only contains a single value.
+ * I.e. if top == bottom under the bounds instance of equality.
+ *
+ * @category utils
+ * @since 2.12.0
+ */
+export const isSingular = <T>(B: Bounded<T>) => B.equals(B.bottom, B.top)
+
 // -------------------------------------------------------------------------------------
 // deprecated
 // -------------------------------------------------------------------------------------
@@ -36,8 +154,8 @@ export interface Bounded<A> extends Ord<A> {
  * @deprecated
  */
 export const boundedNumber: Bounded<number> = {
-  equals: ordNumber.equals,
-  compare: ordNumber.compare,
+  equals: n.Ord.equals,
+  compare: n.Ord.compare,
   top: Infinity,
   bottom: -Infinity
 }

test/Bounded.ts

@@ -0,0 +1,115 @@
+import { reverse, isSingular, coerceBound, fromRange, fromTuple, clamp, top, bottom, isWithin, toTuple, isValid } from '../src/Bounded'
+import { BooleanAlgebra as b } from '../src/boolean'
+import * as U from './util'
+import * as n from '../src/number'
+import { pipe } from '../src/function'
+import fc from 'fast-check'
+import * as Eq from '../src/Eq'
+
+describe('Bounded', () => {
+
+  it('top', () => {
+    fc.assert(fc.property(fc.integer(), fc.integer(), (b, t) =>
+      pipe({ ...n.Ord, bottom: b, top: t }, top, val => n.Eq.equals(t, val))
+    ))
+  })
+
+  it('bottom', () => {
+    fc.assert(fc.property(fc.integer(), fc.integer(), (b, t) =>
+      pipe({ ...n.Ord, bottom: b, top: t }, bottom, val => n.Eq.equals(b, val))))
+  })
+
+  it('isValid', () => {
+    fc.assert(fc.property(fc.integer(), fc.integer(), (bottom, top) =>
+      b.implies(
+        bottom <= top,
+        isValid({ ...n.Ord, bottom, top })
+      )))
+  })
+
+  it('isSingular', () => {
+    fc.assert(fc.property(fc.integer(), fc.integer(), (bottom, top) =>
+      b.implies(bottom === top, isSingular({ ...n.Ord, bottom, top }) &&
+        b.implies(bottom !== top, !isSingular({ ...n.Ord, bottom, top })
+        )))
+    )
+  })
+
+  it('reverse', () => {
+    fc.assert(fc.property(fc.integer(), fc.integer(), (x, y) => {
+      const bound = { ...n.Ord, bottom: x, top: y }
+      const reverseBound = reverse(bound)
+
+      return top(bound) === bottom(reverseBound) && bottom(bound) === top(reverseBound) &&
+        bound.compare(x, y) === reverseBound.compare(y, x) &&
+        b.implies(isValid(bound), isValid(reverseBound))
+
+    }))
+  })
+
+  it('coerceBound', () => {
+    fc.assert(fc.property(fc.integer(), fc.integer(), (x, y) => {
+      const bound = coerceBound(n.Ord)(x)(y)
+
+      return isValid(bound) &&
+        b.implies(x <= y, top(bound) === y && bottom(bound) === x) &&
+        b.implies(y <= x, top(bound) === x && bottom(bound) === y)
+
+    }))
+  })
+
+  it('toTuple', () => {
+    fc.assert(fc.property(fc.integer(), (bottom) => {
+      const top = bottom + 100
+
+      return pipe(
+        { ...n.Ord, bottom, top },
+        toTuple,
+        val => Eq.tuple(n.Eq, n.Eq).equals([bottom, top], val))
+    }))
+  })
+
+  it('isWithin', () => {
+    const inRange = isWithin({ ...n.Ord, bottom: 0, top: 10 })
+
+    U.deepStrictEqual(inRange(2), true)
+    U.deepStrictEqual(inRange(10), true)
+    U.deepStrictEqual(inRange(0), true)
+    U.deepStrictEqual(inRange(20), false)
+    U.deepStrictEqual(inRange(-10), false)
+  })
+
+  it('fromRange', () => {
+    const numRange = fromRange(n.Ord)
+
+    U.deepStrictEqual(numRange(0)(10)._tag, 'Some')
+    U.deepStrictEqual(numRange(0)(0)._tag, 'Some')
+    U.deepStrictEqual(numRange(-1)(0)._tag, 'Some')
+    U.deepStrictEqual(numRange(-1)(-2)._tag, 'None')
+    U.deepStrictEqual(numRange(1)(0)._tag, 'None')
+  })
+
+  it('fromTuple', () => {
+    const numRange = fromTuple(n.Ord)
+
+    U.deepStrictEqual(numRange([0, 10])._tag, 'Some')
+    U.deepStrictEqual(numRange([0,0])._tag, 'Some')
+    U.deepStrictEqual(numRange([-1, 0])._tag, 'Some')
+    U.deepStrictEqual(numRange([-1, -2])._tag, 'None')
+    U.deepStrictEqual(numRange([1, 0])._tag, 'None')
+  })
+
+  it('clamp', () => {
+    fc.assert(fc.property(fc.integer(), fc.integer(), (bottom, val) => {
+      const top = bottom + 100
+      const bound = { ...n.Ord, bottom, top }
+
+      const clampedValue = clamp(bound)(val)
+
+      return b.implies(isWithin(bound)(val), clampedValue === val) &&
+        b.implies(val < bottom, clampedValue === bottom) &&
+        b.implies(val > top, clampedValue === top)
+    }))
+  })
+
+})