effect 3.10.18 → 3.11.0

package/src/Number.ts

@@ -19,10 +19,12 @@ import * as predicate from "./Predicate.js"
  * @param input - The value to test.
  *
  * @example
+ * ```ts
  * import { isNumber } from "effect/Number"
  *
  * assert.deepStrictEqual(isNumber(2), true)
  * assert.deepStrictEqual(isNumber("2"), false)
+ * ```
  *
  * @category guards
  * @since 2.0.0
@@ -36,9 +38,11 @@ export const isNumber: (input: unknown) => input is number = predicate.isNumber
  * @param that - The second operand.
  *
  * @example
+ * ```ts
  * import { sum } from "effect/Number"
  *
  * assert.deepStrictEqual(sum(2, 3), 5)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -51,9 +55,11 @@ export const sum: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { sum } from "effect/Number"
    *
    * assert.deepStrictEqual(sum(2, 3), 5)
+   * ```
    *
    * @category math
    * @since 2.0.0
@@ -66,9 +72,11 @@ export const sum: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { sum } from "effect/Number"
    *
    * assert.deepStrictEqual(sum(2, 3), 5)
+   * ```
    *
    * @category math
    * @since 2.0.0
@@ -83,9 +91,11 @@ export const sum: {
  * @param that - The second operand.
  *
  * @example
+ * ```ts
  * import { multiply } from "effect/Number"
  *
  * assert.deepStrictEqual(multiply(2, 3), 6)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -98,9 +108,11 @@ export const multiply: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { multiply } from "effect/Number"
    *
    * assert.deepStrictEqual(multiply(2, 3), 6)
+   * ```
    *
    * @category math
    * @since 2.0.0
@@ -113,9 +125,11 @@ export const multiply: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { multiply } from "effect/Number"
    *
    * assert.deepStrictEqual(multiply(2, 3), 6)
+   * ```
    *
    * @category math
    * @since 2.0.0
@@ -130,9 +144,11 @@ export const multiply: {
  * @param that - The second operand.
  *
  * @example
+ * ```ts
  * import { subtract } from "effect/Number"
  *
  * assert.deepStrictEqual(subtract(2, 3), -1)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -145,9 +161,11 @@ export const subtract: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { subtract } from "effect/Number"
    *
    * assert.deepStrictEqual(subtract(2, 3), -1)
+   * ```
    *
    * @category math
    * @since 2.0.0
@@ -160,9 +178,11 @@ export const subtract: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { subtract } from "effect/Number"
    *
    * assert.deepStrictEqual(subtract(2, 3), -1)
+   * ```
    *
    * @category math
    * @since 2.0.0
@@ -177,10 +197,12 @@ export const subtract: {
  * @param that - The divisor operand.
  *
  * @example
+ * ```ts
  * 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
@@ -193,10 +215,12 @@ export const divide: {
    * @param that - The divisor operand.
    *
    * @example
+   * ```ts
    * 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
@@ -209,10 +233,12 @@ export const divide: {
    * @param that - The divisor operand.
    *
    * @example
+   * ```ts
    * 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
@@ -232,9 +258,11 @@ export const divide: {
  * @param that - The divisor operand.
  *
  * @example
+ * ```ts
  * import { unsafeDivide } from "effect/Number"
  *
  * assert.deepStrictEqual(unsafeDivide(6, 3), 2)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -249,9 +277,11 @@ export const unsafeDivide: {
    * @param that - The divisor operand.
    *
    * @example
+   * ```ts
    * import { unsafeDivide } from "effect/Number"
    *
    * assert.deepStrictEqual(unsafeDivide(6, 3), 2)
+   * ```
    *
    * @category math
    * @since 2.0.0
@@ -266,9 +296,11 @@ export const unsafeDivide: {
    * @param that - The divisor operand.
    *
    * @example
+   * ```ts
    * import { unsafeDivide } from "effect/Number"
    *
    * assert.deepStrictEqual(unsafeDivide(6, 3), 2)
+   * ```
    *
    * @category math
    * @since 2.0.0
@@ -282,9 +314,11 @@ export const unsafeDivide: {
  * @param n - A `number` to be incremented.
  *
  * @example
+ * ```ts
  * import { increment } from "effect/Number"
  *
  * assert.deepStrictEqual(increment(2), 3)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -297,9 +331,11 @@ export const increment = (n: number): number => n + 1
  * @param n - A `number` to be decremented.
  *
  * @example
+ * ```ts
  * import { decrement } from "effect/Number"
  *
  * assert.deepStrictEqual(decrement(3), 2)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -325,11 +361,13 @@ export const Order: order.Order<number> = order.number
  * @param that - The second argument.
  *
  * @example
+ * ```ts
  * 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
@@ -342,11 +380,13 @@ export const lessThan: {
    * @param that - The second argument.
    *
    * @example
+   * ```ts
    * 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
@@ -359,11 +399,13 @@ export const lessThan: {
    * @param that - The second argument.
    *
    * @example
+   * ```ts
    * 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
@@ -378,11 +420,13 @@ export const lessThan: {
  * @param that - The second `number` to compare with.
  *
  * @example
+ * ```ts
  * 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
@@ -395,11 +439,13 @@ export const lessThanOrEqualTo: {
    * @param that - The second `number` to compare with.
    *
    * @example
+   * ```ts
    * 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
@@ -412,11 +458,13 @@ export const lessThanOrEqualTo: {
    * @param that - The second `number` to compare with.
    *
    * @example
+   * ```ts
    * 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
@@ -431,11 +479,13 @@ export const lessThanOrEqualTo: {
  * @param that - The second argument.
  *
  * @example
+ * ```ts
  * 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
@@ -448,11 +498,13 @@ export const greaterThan: {
    * @param that - The second argument.
    *
    * @example
+   * ```ts
    * 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
@@ -465,11 +517,13 @@ export const greaterThan: {
    * @param that - The second argument.
    *
    * @example
+   * ```ts
    * 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
@@ -484,11 +538,13 @@ export const greaterThan: {
  * @param that - The second `number` to compare with.
  *
  * @example
+ * ```ts
  * 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
@@ -501,11 +557,13 @@ export const greaterThanOrEqualTo: {
    * @param that - The second `number` to compare with.
    *
    * @example
+   * ```ts
    * 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
@@ -518,11 +576,13 @@ export const greaterThanOrEqualTo: {
    * @param that - The second `number` to compare with.
    *
    * @example
+   * ```ts
    * 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
@@ -538,6 +598,7 @@ export const greaterThanOrEqualTo: {
  * @param maximum - The `maximum` value to check.
  *
  * @example
+ * ```ts
  * import { Number } from "effect"
  *
  * const between = Number.between({ minimum: 0, maximum: 5 })
@@ -545,6 +606,7 @@ export const greaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(3), true)
  * assert.deepStrictEqual(between(-1), false)
  * assert.deepStrictEqual(between(6), false)
+ * ```
  *
  * @category predicates
  * @since 2.0.0
@@ -558,6 +620,7 @@ export const between: {
    * @param maximum - The `maximum` value to check.
    *
    * @example
+   * ```ts
    * import { Number } from "effect"
    *
    * const between = Number.between({ minimum: 0, maximum: 5 })
@@ -565,6 +628,7 @@ export const between: {
    * assert.deepStrictEqual(between(3), true)
    * assert.deepStrictEqual(between(-1), false)
    * assert.deepStrictEqual(between(6), false)
+   * ```
    *
    * @category predicates
    * @since 2.0.0
@@ -583,6 +647,7 @@ export const between: {
    * @param maximum - The `maximum` value to check.
    *
    * @example
+   * ```ts
    * import { Number } from "effect"
    *
    * const between = Number.between({ minimum: 0, maximum: 5 })
@@ -590,6 +655,7 @@ export const between: {
    * assert.deepStrictEqual(between(3), true)
    * assert.deepStrictEqual(between(-1), false)
    * assert.deepStrictEqual(between(6), false)
+   * ```
    *
    * @category predicates
    * @since 2.0.0
@@ -615,6 +681,7 @@ export const between: {
  * @param maximum - The upper end of the range.
  *
  * @example
+ * ```ts
  * import { Number } from "effect"
  *
  * const clamp = Number.clamp({ minimum: 1, maximum: 5 })
@@ -622,6 +689,7 @@ export const between: {
  * assert.equal(clamp(3), 3)
  * assert.equal(clamp(0), 1)
  * assert.equal(clamp(6), 5)
+ * ```
  *
  * @since 2.0.0
  */
@@ -638,6 +706,7 @@ export const clamp: {
    * @param maximum - The upper end of the range.
    *
    * @example
+   * ```ts
    * import { Number } from "effect"
    *
    * const clamp = Number.clamp({ minimum: 1, maximum: 5 })
@@ -645,6 +714,7 @@ export const clamp: {
    * assert.equal(clamp(3), 3)
    * assert.equal(clamp(0), 1)
    * assert.equal(clamp(6), 5)
+   * ```
    *
    * @since 2.0.0
    */
@@ -666,6 +736,7 @@ export const clamp: {
    * @param maximum - The upper end of the range.
    *
    * @example
+   * ```ts
    * import { Number } from "effect"
    *
    * const clamp = Number.clamp({ minimum: 1, maximum: 5 })
@@ -673,6 +744,7 @@ export const clamp: {
    * assert.equal(clamp(3), 3)
    * assert.equal(clamp(0), 1)
    * assert.equal(clamp(6), 5)
+   * ```
    *
    * @since 2.0.0
    */
@@ -692,9 +764,11 @@ export const clamp: {
  * @param that - The second `number`.
  *
  * @example
+ * ```ts
  * import { min } from "effect/Number"
  *
  * assert.deepStrictEqual(min(2, 3), 2)
+ * ```
  *
  * @since 2.0.0
  */
@@ -706,9 +780,11 @@ export const min: {
    * @param that - The second `number`.
    *
    * @example
+   * ```ts
    * import { min } from "effect/Number"
    *
    * assert.deepStrictEqual(min(2, 3), 2)
+   * ```
    *
    * @since 2.0.0
    */
@@ -720,9 +796,11 @@ export const min: {
    * @param that - The second `number`.
    *
    * @example
+   * ```ts
    * import { min } from "effect/Number"
    *
    * assert.deepStrictEqual(min(2, 3), 2)
+   * ```
    *
    * @since 2.0.0
    */
@@ -736,9 +814,11 @@ export const min: {
  * @param that - The second `number`.
  *
  * @example
+ * ```ts
  * import { max } from "effect/Number"
  *
  * assert.deepStrictEqual(max(2, 3), 3)
+ * ```
  *
  * @since 2.0.0
  */
@@ -750,9 +830,11 @@ export const max: {
    * @param that - The second `number`.
    *
    * @example
+   * ```ts
    * import { max } from "effect/Number"
    *
    * assert.deepStrictEqual(max(2, 3), 3)
+   * ```
    *
    * @since 2.0.0
    */
@@ -764,9 +846,11 @@ export const max: {
    * @param that - The second `number`.
    *
    * @example
+   * ```ts
    * import { max } from "effect/Number"
    *
    * assert.deepStrictEqual(max(2, 3), 3)
+   * ```
    *
    * @since 2.0.0
    */
@@ -779,11 +863,13 @@ export const max: {
  * @param n - The `number` to determine the sign of.
  *
  * @example
+ * ```ts
  * import { sign } from "effect/Number"
  *
  * assert.deepStrictEqual(sign(-5), -1)
  * assert.deepStrictEqual(sign(0), 0)
  * assert.deepStrictEqual(sign(5), 1)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -796,9 +882,11 @@ export const sign = (n: number): Ordering => Order(n, 0)
  * @param collection - The collection of `number`s to sum.
  *
  * @example
+ * ```ts
  * import { sumAll } from "effect/Number"
  *
  * assert.deepStrictEqual(sumAll([2, 3, 4]), 9)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -817,9 +905,11 @@ export const sumAll = (collection: Iterable<number>): number => {
  * @param collection - The collection of `number`s to multiply.
  *
  * @example
+ * ```ts
  * import { multiplyAll } from "effect/Number"
  *
  * assert.deepStrictEqual(multiplyAll([2, 3, 4]), 24)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -844,11 +934,13 @@ export const multiplyAll = (collection: Iterable<number>): number => {
  * @param divisor - The divisor.
  *
  * @example
+ * ```ts
  * 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
@@ -863,11 +955,13 @@ export const remainder: {
    * @param divisor - The divisor.
    *
    * @example
+   * ```ts
    * 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
@@ -882,11 +976,13 @@ export const remainder: {
    * @param divisor - The divisor.
    *
    * @example
+   * ```ts
    * 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
@@ -908,10 +1004,12 @@ export const remainder: {
  * @param self - The number to find the next power of 2 from.
  *
  * @example
+ * ```ts
  * import { nextPow2 } from "effect/Number"
  *
  * assert.deepStrictEqual(nextPow2(5), 8)
  * assert.deepStrictEqual(nextPow2(17), 32)
+ * ```
  *
  * @category math
  * @since 2.0.0
@@ -954,10 +1052,12 @@ export const parse = (s: string): Option<number> => {
  * @param precision - The precision
  *
  * @example
+ * ```ts
  * 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
@@ -970,10 +1070,12 @@ export const round: {
    * @param precision - The precision
    *
    * @example
+   * ```ts
    * 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
@@ -986,10 +1088,12 @@ export const round: {
    * @param precision - The precision
    *
    * @example
+   * ```ts
    * 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