effect 3.8.4 → 3.9.0

package/src/BigInt.ts

@@ -48,7 +48,35 @@ export const isBigInt: (u: unknown) => u is bigint = predicate.isBigInt
  * @since 2.0.0
  */
 export const sum: {
+  /**
+   * Provides an addition operation on `bigint`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { sum } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(sum(2n, 3n), 5n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => bigint
+  /**
+   * Provides an addition operation on `bigint`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { sum } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(sum(2n, 3n), 5n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): bigint
 } = dual(2, (self: bigint, that: bigint): bigint => self + that)
 
@@ -67,7 +95,35 @@ export const sum: {
  * @since 2.0.0
  */
 export const multiply: {
+  /**
+   * Provides a multiplication operation on `bigint`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { multiply } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(multiply(2n, 3n), 6n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => bigint
+  /**
+   * Provides a multiplication operation on `bigint`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { multiply } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(multiply(2n, 3n), 6n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): bigint
 } = dual(2, (self: bigint, that: bigint): bigint => self * that)
 
@@ -86,7 +142,35 @@ export const multiply: {
  * @since 2.0.0
  */
 export const subtract: {
+  /**
+   * Provides a subtraction operation on `bigint`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { subtract } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(subtract(2n, 3n), -1n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => bigint
+  /**
+   * Provides a subtraction operation on `bigint`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { subtract } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(subtract(2n, 3n), -1n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): bigint
 } = dual(2, (self: bigint, that: bigint): bigint => self - that)
 
@@ -111,7 +195,47 @@ export const subtract: {
  * @since 2.0.0
  */
 export const divide: {
+  /**
+   * Provides a division operation on `bigint`s.
+   *
+   * If the dividend is not a multiple of the divisor the result will be a `bigint` value
+   * which represents the integer division rounded down to the nearest integer.
+   *
+   * Returns `None` if the divisor is `0n`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { BigInt, Option } from "effect"
+   *
+   * assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
+   * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => Option.Option<bigint>
+  /**
+   * Provides a division operation on `bigint`s.
+   *
+   * If the dividend is not a multiple of the divisor the result will be a `bigint` value
+   * which represents the integer division rounded down to the nearest integer.
+   *
+   * Returns `None` if the divisor is `0n`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { BigInt, Option } from "effect"
+   *
+   * assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
+   * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): Option.Option<bigint>
 } = dual(
   2,
@@ -139,7 +263,47 @@ export const divide: {
  * @since 2.0.0
  */
 export const unsafeDivide: {
+  /**
+   * Provides a division operation on `bigint`s.
+   *
+   * If the dividend is not a multiple of the divisor the result will be a `bigint` value
+   * which represents the integer division rounded down to the nearest integer.
+   *
+   * Throws a `RangeError` if the divisor is `0n`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { unsafeDivide } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(unsafeDivide(6n, 3n), 2n)
+   * assert.deepStrictEqual(unsafeDivide(6n, 4n), 1n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => bigint
+  /**
+   * Provides a division operation on `bigint`s.
+   *
+   * If the dividend is not a multiple of the divisor the result will be a `bigint` value
+   * which represents the integer division rounded down to the nearest integer.
+   *
+   * Throws a `RangeError` if the divisor is `0n`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { unsafeDivide } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(unsafeDivide(6n, 3n), 2n)
+   * assert.deepStrictEqual(unsafeDivide(6n, 4n), 1n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): bigint
 } = dual(2, (self: bigint, that: bigint): bigint => self / that)
 
@@ -202,7 +366,39 @@ export const Order: order.Order<bigint> = order.bigint
  * @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/BigInt"
+   *
+   * assert.deepStrictEqual(lessThan(2n, 3n), true)
+   * assert.deepStrictEqual(lessThan(3n, 3n), false)
+   * assert.deepStrictEqual(lessThan(4n, 3n), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => 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/BigInt"
+   *
+   * assert.deepStrictEqual(lessThan(2n, 3n), true)
+   * assert.deepStrictEqual(lessThan(3n, 3n), false)
+   * assert.deepStrictEqual(lessThan(4n, 3n), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): boolean
 } = order.lessThan(Order)
 
@@ -223,7 +419,39 @@ export const lessThan: {
  * @since 2.0.0
  */
 export const lessThanOrEqualTo: {
+  /**
+   * Returns a function that checks if a given `bigint` is less than or equal to the provided one.
+   *
+   * @param self - The first `bigint` to compare with.
+   * @param that - The second `bigint` to compare with.
+   *
+   * @example
+   * import { lessThanOrEqualTo } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(lessThanOrEqualTo(2n, 3n), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(3n, 3n), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(4n, 3n), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => boolean
+  /**
+   * Returns a function that checks if a given `bigint` is less than or equal to the provided one.
+   *
+   * @param self - The first `bigint` to compare with.
+   * @param that - The second `bigint` to compare with.
+   *
+   * @example
+   * import { lessThanOrEqualTo } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(lessThanOrEqualTo(2n, 3n), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(3n, 3n), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(4n, 3n), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): boolean
 } = order.lessThanOrEqualTo(Order)
 
@@ -244,7 +472,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/BigInt"
+   *
+   * assert.deepStrictEqual(greaterThan(2n, 3n), false)
+   * assert.deepStrictEqual(greaterThan(3n, 3n), false)
+   * assert.deepStrictEqual(greaterThan(4n, 3n), true)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => 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/BigInt"
+   *
+   * assert.deepStrictEqual(greaterThan(2n, 3n), false)
+   * assert.deepStrictEqual(greaterThan(3n, 3n), false)
+   * assert.deepStrictEqual(greaterThan(4n, 3n), true)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): boolean
 } = order.greaterThan(Order)
 
@@ -265,7 +525,39 @@ export const greaterThan: {
  * @since 2.0.0
  */
 export const greaterThanOrEqualTo: {
+  /**
+   * Returns a function that checks if a given `bigint` is greater than or equal to the provided one.
+   *
+   * @param self - The first `bigint` to compare with.
+   * @param that - The second `bigint` to compare with.
+   *
+   * @example
+   * import { greaterThanOrEqualTo } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(greaterThanOrEqualTo(2n, 3n), false)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(3n, 3n), true)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(4n, 3n), true)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => boolean
+  /**
+   * Returns a function that checks if a given `bigint` is greater than or equal to the provided one.
+   *
+   * @param self - The first `bigint` to compare with.
+   * @param that - The second `bigint` to compare with.
+   *
+   * @example
+   * import { greaterThanOrEqualTo } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(greaterThanOrEqualTo(2n, 3n), false)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(3n, 3n), true)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(4n, 3n), true)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): boolean
 } = order.greaterThanOrEqualTo(Order)
 
@@ -289,14 +581,57 @@ export const greaterThanOrEqualTo: {
  * @since 2.0.0
  */
 export const between: {
-  (options: {
-    minimum: bigint
-    maximum: bigint
-  }): (self: bigint) => boolean
-  (self: bigint, options: {
-    minimum: bigint
-    maximum: bigint
-  }): boolean
+  /**
+   * Checks if a `bigint` 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 { BigInt } from "effect"
+   *
+   * const between = BigInt.between({ minimum: 0n, maximum: 5n })
+   *
+   * assert.deepStrictEqual(between(3n), true)
+   * assert.deepStrictEqual(between(-1n), false)
+   * assert.deepStrictEqual(between(6n), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
+  (
+    options: {
+      minimum: bigint
+      maximum: bigint
+    }
+  ): (self: bigint) => boolean
+  /**
+   * Checks if a `bigint` 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 { BigInt } from "effect"
+   *
+   * const between = BigInt.between({ minimum: 0n, maximum: 5n })
+   *
+   * assert.deepStrictEqual(between(3n), true)
+   * assert.deepStrictEqual(between(-1n), false)
+   * assert.deepStrictEqual(between(6n), false)
+   *
+   * @category predicates
+   * @since 2.0.0
+   */
+  (
+    self: bigint,
+    options: {
+      minimum: bigint
+      maximum: bigint
+    }
+  ): boolean
 } = order.between(Order)
 
 /**
@@ -322,14 +657,63 @@ export const between: {
  * @since 2.0.0
  */
 export const clamp: {
-  (options: {
-    minimum: bigint
-    maximum: bigint
-  }): (self: bigint) => bigint
-  (self: bigint, options: {
-    minimum: bigint
-    maximum: bigint
-  }): bigint
+  /**
+   * Restricts the given `bigint` to be within the range specified by the `minimum` and `maximum` values.
+   *
+   * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
+   * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
+   * - Otherwise, it returns the original `bigint`.
+   *
+   * @param self - The `bigint` to be clamped.
+   * @param minimum - The lower end of the range.
+   * @param maximum - The upper end of the range.
+   *
+   * @example
+   * import { BigInt } from "effect"
+   *
+   * const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
+   *
+   * assert.equal(clamp(3n), 3n)
+   * assert.equal(clamp(0n), 1n)
+   * assert.equal(clamp(6n), 5n)
+   *
+   * @since 2.0.0
+   */
+  (
+    options: {
+      minimum: bigint
+      maximum: bigint
+    }
+  ): (self: bigint) => bigint
+  /**
+   * Restricts the given `bigint` to be within the range specified by the `minimum` and `maximum` values.
+   *
+   * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
+   * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
+   * - Otherwise, it returns the original `bigint`.
+   *
+   * @param self - The `bigint` to be clamped.
+   * @param minimum - The lower end of the range.
+   * @param maximum - The upper end of the range.
+   *
+   * @example
+   * import { BigInt } from "effect"
+   *
+   * const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
+   *
+   * assert.equal(clamp(3n), 3n)
+   * assert.equal(clamp(0n), 1n)
+   * assert.equal(clamp(6n), 5n)
+   *
+   * @since 2.0.0
+   */
+  (
+    self: bigint,
+    options: {
+      minimum: bigint
+      maximum: bigint
+    }
+  ): bigint
 } = order.clamp(Order)
 
 /**
@@ -346,7 +730,33 @@ export const clamp: {
  * @since 2.0.0
  */
 export const min: {
+  /**
+   * Returns the minimum between two `bigint`s.
+   *
+   * @param self - The first `bigint`.
+   * @param that - The second `bigint`.
+   *
+   * @example
+   * import { min } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(min(2n, 3n), 2n)
+   *
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => bigint
+  /**
+   * Returns the minimum between two `bigint`s.
+   *
+   * @param self - The first `bigint`.
+   * @param that - The second `bigint`.
+   *
+   * @example
+   * import { min } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(min(2n, 3n), 2n)
+   *
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): bigint
 } = order.min(Order)
 
@@ -364,7 +774,33 @@ export const min: {
  * @since 2.0.0
  */
 export const max: {
+  /**
+   * Returns the maximum between two `bigint`s.
+   *
+   * @param self - The first `bigint`.
+   * @param that - The second `bigint`.
+   *
+   * @example
+   * import { max } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(max(2n, 3n), 3n)
+   *
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => bigint
+  /**
+   * Returns the maximum between two `bigint`s.
+   *
+   * @param self - The first `bigint`.
+   * @param that - The second `bigint`.
+   *
+   * @example
+   * import { max } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(max(2n, 3n), 3n)
+   *
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): bigint
 } = order.max(Order)
 
@@ -419,7 +855,39 @@ export const abs = (n: bigint): bigint => (n < bigint0 ? -n : n)
  * @since 2.0.0
  */
 export const gcd: {
+  /**
+   * Determines the greatest common divisor of two `bigint`s.
+   *
+   * @param a - The first `bigint`.
+   * @param b - The second `bigint`.
+   *
+   * @example
+   * import { gcd } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(gcd(2n, 3n), 1n)
+   * assert.deepStrictEqual(gcd(2n, 4n), 2n)
+   * assert.deepStrictEqual(gcd(16n, 24n), 8n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => bigint
+  /**
+   * Determines the greatest common divisor of two `bigint`s.
+   *
+   * @param a - The first `bigint`.
+   * @param b - The second `bigint`.
+   *
+   * @example
+   * import { gcd } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(gcd(2n, 3n), 1n)
+   * assert.deepStrictEqual(gcd(2n, 4n), 2n)
+   * assert.deepStrictEqual(gcd(16n, 24n), 8n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): bigint
 } = dual(2, (self: bigint, that: bigint): bigint => {
   while (that !== bigint0) {
@@ -447,7 +915,39 @@ export const gcd: {
  * @since 2.0.0
  */
 export const lcm: {
+  /**
+   * Determines the least common multiple of two `bigint`s.
+   *
+   * @param a - The first `bigint`.
+   * @param b - The second `bigint`.
+   *
+   * @example
+   * import { lcm } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(lcm(2n, 3n), 6n)
+   * assert.deepStrictEqual(lcm(2n, 4n), 4n)
+   * assert.deepStrictEqual(lcm(16n, 24n), 48n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (that: bigint): (self: bigint) => bigint
+  /**
+   * Determines the least common multiple of two `bigint`s.
+   *
+   * @param a - The first `bigint`.
+   * @param b - The second `bigint`.
+   *
+   * @example
+   * import { lcm } from "effect/BigInt"
+   *
+   * assert.deepStrictEqual(lcm(2n, 3n), 6n)
+   * assert.deepStrictEqual(lcm(2n, 4n), 4n)
+   * assert.deepStrictEqual(lcm(16n, 24n), 48n)
+   *
+   * @category math
+   * @since 2.0.0
+   */
   (self: bigint, that: bigint): bigint
 } = dual(2, (self: bigint, that: bigint): bigint => (self * that) / gcd(self, that))