effect 3.8.3 → 3.8.5

package/src/Number.ts

@@ -44,7 +44,35 @@ export const isNumber: (input: unknown) => input is number = predicate.isNumber
  * @since 2.0.0
  */
 export const sum: {
+  /**
+   * Provides an addition operation on `number`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { sum } from "effect/Number"
+   *
+   * assert.deepStrictEqual(sum(2, 3), 5)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: number): (self: number) => number
+  /**
+   * Provides an addition operation on `number`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { sum } from "effect/Number"
+   *
+   * assert.deepStrictEqual(sum(2, 3), 5)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: number, that: number): number
 } = dual(2, (self: number, that: number): number => self + that)
 
@@ -63,7 +91,35 @@ export const sum: {
  * @since 2.0.0
  */
 export const multiply: {
+  /**
+   * Provides a multiplication operation on `number`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { multiply } from "effect/Number"
+   *
+   * assert.deepStrictEqual(multiply(2, 3), 6)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: number): (self: number) => number
+  /**
+   * Provides a multiplication operation on `number`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { multiply } from "effect/Number"
+   *
+   * assert.deepStrictEqual(multiply(2, 3), 6)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: number, that: number): number
 } = dual(2, (self: number, that: number): number => self * that)
 
@@ -82,7 +138,35 @@ export const multiply: {
  * @since 2.0.0
  */
 export const subtract: {
+  /**
+   * Provides a subtraction operation on `number`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { subtract } from "effect/Number"
+   *
+   * assert.deepStrictEqual(subtract(2, 3), -1)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: number): (self: number) => number
+  /**
+   * Provides a subtraction operation on `number`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { subtract } from "effect/Number"
+   *
+   * assert.deepStrictEqual(subtract(2, 3), -1)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: number, that: number): number
 } = dual(2, (self: number, that: number): number => self - that)
 
@@ -102,7 +186,37 @@ export const subtract: {
  * @since 2.0.0
  */
 export const divide: {
+  /**
+   * Provides a division operation on `number`s.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { Number, Option } from "effect"
+   *
+   * assert.deepStrictEqual(Number.divide(6, 3), Option.some(2))
+   * assert.deepStrictEqual(Number.divide(6, 0), Option.none())
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: number): (self: number) => Option<number>
+  /**
+   * Provides a division operation on `number`s.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { Number, Option } from "effect"
+   *
+   * assert.deepStrictEqual(Number.divide(6, 3), Option.some(2))
+   * assert.deepStrictEqual(Number.divide(6, 0), Option.none())
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: number, that: number): Option<number>
 } = dual(
   2,
@@ -126,7 +240,39 @@ export const divide: {
  * @since 2.0.0
  */
 export const unsafeDivide: {
+  /**
+   * Provides a division operation on `number`s.
+   *
+   * Throws a `RangeError` if the divisor is `0`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { unsafeDivide } from "effect/Number"
+   *
+   * assert.deepStrictEqual(unsafeDivide(6, 3), 2)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: number): (self: number) => number
+  /**
+   * Provides a division operation on `number`s.
+   *
+   * Throws a `RangeError` if the divisor is `0`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { unsafeDivide } from "effect/Number"
+   *
+   * assert.deepStrictEqual(unsafeDivide(6, 3), 2)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: number, that: number): number
 } = dual(2, (self: number, that: number): number => self / that)
 
@@ -189,7 +335,39 @@ export const Order: order.Order<number> = order.number
  * @since 2.0.0
  */
 export const lessThan: {
+  /**
+   * Returns `true` if the first argument is less than the second, otherwise `false`.
+   *
+   * @param self - The first argument.
+   * @param that - The second argument.
+   *
+   * @example
+   * import { lessThan } from "effect/Number"
+   *
+   * assert.deepStrictEqual(lessThan(2, 3), true)
+   * assert.deepStrictEqual(lessThan(3, 3), false)
+   * assert.deepStrictEqual(lessThan(4, 3), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (that: number): (self: number) => boolean
+  /**
+   * Returns `true` if the first argument is less than the second, otherwise `false`.
+   *
+   * @param self - The first argument.
+   * @param that - The second argument.
+   *
+   * @example
+   * import { lessThan } from "effect/Number"
+   *
+   * assert.deepStrictEqual(lessThan(2, 3), true)
+   * assert.deepStrictEqual(lessThan(3, 3), false)
+   * assert.deepStrictEqual(lessThan(4, 3), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (self: number, that: number): boolean
 } = order.lessThan(Order)
 
@@ -210,7 +388,39 @@ export const lessThan: {
  * @since 2.0.0
  */
 export const lessThanOrEqualTo: {
+  /**
+   * Returns a function that checks if a given `number` is less than or equal to the provided one.
+   *
+   * @param self - The first `number` to compare with.
+   * @param that - The second `number` to compare with.
+   *
+   * @example
+   * import { lessThanOrEqualTo } from "effect/Number"
+   *
+   * assert.deepStrictEqual(lessThanOrEqualTo(2, 3), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(3, 3), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(4, 3), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (that: number): (self: number) => boolean
+  /**
+   * Returns a function that checks if a given `number` is less than or equal to the provided one.
+   *
+   * @param self - The first `number` to compare with.
+   * @param that - The second `number` to compare with.
+   *
+   * @example
+   * import { lessThanOrEqualTo } from "effect/Number"
+   *
+   * assert.deepStrictEqual(lessThanOrEqualTo(2, 3), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(3, 3), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(4, 3), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (self: number, that: number): boolean
 } = order.lessThanOrEqualTo(Order)
 
@@ -231,7 +441,39 @@ export const lessThanOrEqualTo: {
  * @since 2.0.0
  */
 export const greaterThan: {
+  /**
+   * Returns `true` if the first argument is greater than the second, otherwise `false`.
+   *
+   * @param self - The first argument.
+   * @param that - The second argument.
+   *
+   * @example
+   * import { greaterThan } from "effect/Number"
+   *
+   * assert.deepStrictEqual(greaterThan(2, 3), false)
+   * assert.deepStrictEqual(greaterThan(3, 3), false)
+   * assert.deepStrictEqual(greaterThan(4, 3), true)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (that: number): (self: number) => boolean
+  /**
+   * Returns `true` if the first argument is greater than the second, otherwise `false`.
+   *
+   * @param self - The first argument.
+   * @param that - The second argument.
+   *
+   * @example
+   * import { greaterThan } from "effect/Number"
+   *
+   * assert.deepStrictEqual(greaterThan(2, 3), false)
+   * assert.deepStrictEqual(greaterThan(3, 3), false)
+   * assert.deepStrictEqual(greaterThan(4, 3), true)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (self: number, that: number): boolean
 } = order.greaterThan(Order)
 
@@ -252,7 +494,39 @@ export const greaterThan: {
  * @since 2.0.0
  */
 export const greaterThanOrEqualTo: {
+  /**
+   * Returns a function that checks if a given `number` is greater than or equal to the provided one.
+   *
+   * @param self - The first `number` to compare with.
+   * @param that - The second `number` to compare with.
+   *
+   * @example
+   * import { greaterThanOrEqualTo } from "effect/Number"
+   *
+   * assert.deepStrictEqual(greaterThanOrEqualTo(2, 3), false)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(3, 3), true)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(4, 3), true)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (that: number): (self: number) => boolean
+  /**
+   * Returns a function that checks if a given `number` is greater than or equal to the provided one.
+   *
+   * @param self - The first `number` to compare with.
+   * @param that - The second `number` to compare with.
+   *
+   * @example
+   * import { greaterThanOrEqualTo } from "effect/Number"
+   *
+   * assert.deepStrictEqual(greaterThanOrEqualTo(2, 3), false)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(3, 3), true)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(4, 3), true)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (self: number, that: number): boolean
 } = order.greaterThanOrEqualTo(Order)
 
@@ -276,14 +550,57 @@ export const greaterThanOrEqualTo: {
  * @since 2.0.0
  */
 export const between: {
-  (options: {
-    minimum: number
-    maximum: number
-  }): (self: number) => boolean
-  (self: number, options: {
-    minimum: number
-    maximum: number
-  }): boolean
+  /**
+   * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
+   *
+   * @param self - The `number` to check.
+   * @param minimum - The `minimum` value to check.
+   * @param maximum - The `maximum` value to check.
+   *
+   * @example
+   * import { Number } from "effect"
+   *
+   * const between = Number.between({ minimum: 0, maximum: 5 })
+   *
+   * assert.deepStrictEqual(between(3), true)
+   * assert.deepStrictEqual(between(-1), false)
+   * assert.deepStrictEqual(between(6), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
+  (
+    options: {
+      minimum: number
+      maximum: number
+    }
+  ): (self: number) => boolean
+  /**
+   * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
+   *
+   * @param self - The `number` to check.
+   * @param minimum - The `minimum` value to check.
+   * @param maximum - The `maximum` value to check.
+   *
+   * @example
+   * import { Number } from "effect"
+   *
+   * const between = Number.between({ minimum: 0, maximum: 5 })
+   *
+   * assert.deepStrictEqual(between(3), true)
+   * assert.deepStrictEqual(between(-1), false)
+   * assert.deepStrictEqual(between(6), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
+  (
+    self: number,
+    options: {
+      minimum: number
+      maximum: number
+    }
+  ): boolean
 } = order.between(Order)
 
 /**
@@ -309,14 +626,63 @@ export const between: {
  * @since 2.0.0
  */
 export const clamp: {
-  (options: {
-    minimum: number
-    maximum: number
-  }): (self: number) => number
-  (self: number, options: {
-    minimum: number
-    maximum: number
-  }): number
+  /**
+   * Restricts the given `number` to be within the range specified by the `minimum` and `maximum` values.
+   *
+   * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
+   * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
+   * - Otherwise, it returns the original `number`.
+   *
+   * @param self - The `number` to be clamped.
+   * @param minimum - The lower end of the range.
+   * @param maximum - The upper end of the range.
+   *
+   * @example
+   * import { Number } from "effect"
+   *
+   * const clamp = Number.clamp({ minimum: 1, maximum: 5 })
+   *
+   * assert.equal(clamp(3), 3)
+   * assert.equal(clamp(0), 1)
+   * assert.equal(clamp(6), 5)
+   *
+   * @since 2.0.0
+   */
+  (
+    options: {
+      minimum: number
+      maximum: number
+    }
+  ): (self: number) => number
+  /**
+   * Restricts the given `number` to be within the range specified by the `minimum` and `maximum` values.
+   *
+   * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
+   * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
+   * - Otherwise, it returns the original `number`.
+   *
+   * @param self - The `number` to be clamped.
+   * @param minimum - The lower end of the range.
+   * @param maximum - The upper end of the range.
+   *
+   * @example
+   * import { Number } from "effect"
+   *
+   * const clamp = Number.clamp({ minimum: 1, maximum: 5 })
+   *
+   * assert.equal(clamp(3), 3)
+   * assert.equal(clamp(0), 1)
+   * assert.equal(clamp(6), 5)
+   *
+   * @since 2.0.0
+   */
+  (
+    self: number,
+    options: {
+      minimum: number
+      maximum: number
+    }
+  ): number
 } = order.clamp(Order)
 
 /**
@@ -333,7 +699,33 @@ export const clamp: {
  * @since 2.0.0
  */
 export const min: {
+  /**
+   * Returns the minimum between two `number`s.
+   *
+   * @param self - The first `number`.
+   * @param that - The second `number`.
+   *
+   * @example
+   * import { min } from "effect/Number"
+   *
+   * assert.deepStrictEqual(min(2, 3), 2)
+   *
+   * @since 2.0.0
+   */
   (that: number): (self: number) => number
+  /**
+   * Returns the minimum between two `number`s.
+   *
+   * @param self - The first `number`.
+   * @param that - The second `number`.
+   *
+   * @example
+   * import { min } from "effect/Number"
+   *
+   * assert.deepStrictEqual(min(2, 3), 2)
+   *
+   * @since 2.0.0
+   */
   (self: number, that: number): number
 } = order.min(Order)
 
@@ -351,7 +743,33 @@ export const min: {
  * @since 2.0.0
  */
 export const max: {
+  /**
+   * Returns the maximum between two `number`s.
+   *
+   * @param self - The first `number`.
+   * @param that - The second `number`.
+   *
+   * @example
+   * import { max } from "effect/Number"
+   *
+   * assert.deepStrictEqual(max(2, 3), 3)
+   *
+   * @since 2.0.0
+   */
   (that: number): (self: number) => number
+  /**
+   * Returns the maximum between two `number`s.
+   *
+   * @param self - The first `number`.
+   * @param that - The second `number`.
+   *
+   * @example
+   * import { max } from "effect/Number"
+   *
+   * assert.deepStrictEqual(max(2, 3), 3)
+   *
+   * @since 2.0.0
+   */
   (self: number, that: number): number
 } = order.max(Order)
 
@@ -436,7 +854,43 @@ export const multiplyAll = (collection: Iterable<number>): number => {
  * @since 2.0.0
  */
 export const remainder: {
+  /**
+   * Returns the remainder left over when one operand is divided by a second operand.
+   *
+   * It always takes the sign of the dividend.
+   *
+   * @param self - The dividend.
+   * @param divisor - The divisor.
+   *
+   * @example
+   * import { remainder } from "effect/Number"
+   *
+   * assert.deepStrictEqual(remainder(2, 2), 0)
+   * assert.deepStrictEqual(remainder(3, 2), 1)
+   * assert.deepStrictEqual(remainder(-4, 2), -0)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (divisor: number): (self: number) => number
+  /**
+   * Returns the remainder left over when one operand is divided by a second operand.
+   *
+   * It always takes the sign of the dividend.
+   *
+   * @param self - The dividend.
+   * @param divisor - The divisor.
+   *
+   * @example
+   * import { remainder } from "effect/Number"
+   *
+   * assert.deepStrictEqual(remainder(2, 2), 0)
+   * assert.deepStrictEqual(remainder(3, 2), 1)
+   * assert.deepStrictEqual(remainder(-4, 2), -0)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: number, divisor: number): number
 } = dual(2, (self: number, divisor: number): number => {
   // https://stackoverflow.com/questions/3966484/why-does-modulus-operator-return-fractional-number-in-javascript/31711034#31711034
@@ -509,7 +963,37 @@ export const parse = (s: string): Option<number> => {
  * @since 3.8.0
  */
 export const round: {
+  /**
+   * Returns the number rounded with the given precision.
+   *
+   * @param self - The number to round
+   * @param precision - The precision
+   *
+   * @example
+   * import { round } from "effect/Number"
+   *
+   * assert.deepStrictEqual(round(1.1234, 2), 1.12)
+   * assert.deepStrictEqual(round(1.567, 2), 1.57)
+   *
+   * @category math
+   * @since 3.8.0
+   */
   (precision: number): (self: number) => number
+  /**
+   * Returns the number rounded with the given precision.
+   *
+   * @param self - The number to round
+   * @param precision - The precision
+   *
+   * @example
+   * import { round } from "effect/Number"
+   *
+   * assert.deepStrictEqual(round(1.1234, 2), 1.12)
+   * assert.deepStrictEqual(round(1.567, 2), 1.57)
+   *
+   * @category math
+   * @since 3.8.0
+   */
   (self: number, precision: number): number
 } = dual(2, (self: number, precision: number): number => {
   const factor = Math.pow(10, precision)