effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/BigDecimal.d.ts

@@ -1,15 +1,59 @@
 /**
- * This module provides utility functions and type class instances for working with the `BigDecimal` type in TypeScript.
- * It includes functions for basic arithmetic operations.
+ * Decimal arithmetic backed by an unscaled `bigint` and a decimal scale.
+ *
+ * `BigDecimal` is useful when values must keep their decimal representation
+ * instead of inheriting JavaScript's binary floating-point rounding, such as
+ * money, quantities, measurements, or protocol values exchanged as decimal
+ * strings. The module includes constructors, parsers, arithmetic operations,
+ * comparisons, rounding helpers, and string formatting.
+ *
+ * **Mental model**
+ *
+ * - A `BigDecimal` stores `value * 10^-scale`; `make(12345n, 2)` represents
+ *   `123.45`
+ * - Values are immutable; arithmetic returns new `BigDecimal` values
+ * - Equivalent values can have different internal scales, so equality and
+ *   ordering normalize trailing zeros
+ * - Division can produce repeating decimals, so {@link divide} and
+ *   {@link divideUnsafe} use the module's default division precision
+ *
+ * **Common tasks**
+ *
+ * - Construct values: {@link make}, {@link fromBigInt}, {@link fromString},
+ *   {@link fromNumber}
+ * - Render values: {@link format}, {@link toExponential},
+ *   {@link toNumberUnsafe}
+ * - Do arithmetic: {@link sum}, {@link subtract}, {@link multiply},
+ *   {@link divide}, {@link remainder}, {@link negate}, {@link abs}
+ * - Compare and constrain values: {@link equals}, {@link Order},
+ *   {@link isLessThan}, {@link between}, {@link clamp}, {@link min},
+ *   {@link max}
+ * - Adjust decimal places: {@link scale}, {@link round}, {@link truncate},
+ *   {@link ceil}, {@link floor}
  *
- * A `BigDecimal` allows storing any real number to arbitrary precision; which avoids common floating point errors
- * (such as 0.1 + 0.2 ≠ 0.3) at the cost of complexity.
+ * **Gotchas**
+ *
+ * - Prefer {@link fromString} or {@link fromBigInt} for external decimal data.
+ *   {@link fromNumber} can only preserve the decimal spelling of a finite
+ *   JavaScript number after any binary floating-point precision has already
+ *   been lost.
+ * - {@link divide} and {@link remainder} return `Option.none()` for division
+ *   by zero; {@link divideUnsafe} and {@link remainderUnsafe} throw instead.
+ * - Parsed scales must fit in JavaScript's safe integer range.
+ *
+ * **Example** (Decimal arithmetic)
+ *
+ * ```ts
+ * import { BigDecimal } from "effect"
  *
- * Internally, `BigDecimal` uses a `BigInt` object, paired with a 64-bit integer which determines the position of the
- * decimal point. Therefore, the precision *is not* actually arbitrary, but limited to 2<sup>63</sup> decimal places.
+ * const subtotal = BigDecimal.multiply(
+ *   BigDecimal.fromStringUnsafe("19.99"),
+ *   BigDecimal.fromBigInt(3n)
+ * )
+ * const total = BigDecimal.sum(subtotal, BigDecimal.fromStringUnsafe("1.50"))
  *
- * It is not recommended to convert a floating point number to a decimal directly, as the floating point representation
- * may be unexpected.
+ * console.log(BigDecimal.format(total)) // "61.47"
+ * ```
  *
  * @since 2.0.0
  */
@@ -24,6 +68,11 @@ declare const TypeId = "~effect/BigDecimal";
 /**
  * Represents an arbitrary precision decimal number.
  *
+ * **When to use**
+ *
+ * Use when decimal arithmetic needs to avoid JavaScript floating point
+ * representation errors.
+ *
  * **Example** (Inspecting BigDecimal storage)
  *
  * ```ts
@@ -44,7 +93,11 @@ export interface BigDecimal extends Equal.Equal, Pipeable, Inspectable {
     readonly scale: number;
 }
 /**
- * Checks if a given value is a `BigDecimal`.
+ * Checks whether a given value is a `BigDecimal`.
+ *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `BigDecimal`.
  *
  * **Example** (Checking BigDecimal values)
  *
@@ -64,6 +117,11 @@ export declare const isBigDecimal: (u: unknown) => u is BigDecimal;
 /**
  * Creates a `BigDecimal` from a `bigint` value and a scale.
  *
+ * **When to use**
+ *
+ * Use to construct a decimal directly from its unscaled integer value and
+ * decimal scale.
+ *
  * **Example** (Creating decimals from bigint and scale)
  *
  * ```ts
@@ -78,6 +136,8 @@ export declare const isBigDecimal: (u: unknown) => u is BigDecimal;
  * console.log(BigDecimal.format(integer)) // "42"
  * ```
  *
+ * @see {@link fromBigInt} for constructing an integer decimal from a `bigint`
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -85,6 +145,11 @@ export declare const make: (value: bigint, scale: number) => BigDecimal;
 /**
  * Normalizes a given `BigDecimal` by removing trailing zeros.
  *
+ * **When to use**
+ *
+ * Use to canonicalize decimals that have equivalent values but different
+ * internal scales.
+ *
  * **Example** (Normalizing trailing zeros)
  *
  * ```ts
@@ -101,12 +166,18 @@ export declare const make: (value: bigint, scale: number) => BigDecimal;
  * )
  * ```
  *
+ * @see {@link format} for rendering normalized decimals as strings
+ *
  * @category scaling
  * @since 2.0.0
  */
 export declare const normalize: (self: BigDecimal) => BigDecimal;
 /**
- * Scales a `BigDecimal` to the specified scale.
+ * Changes a `BigDecimal` to the specified scale.
+ *
+ * **When to use**
+ *
+ * Use to change how many decimal places are represented by a `BigDecimal`.
  *
  * **Details**
  *
@@ -130,12 +201,18 @@ export declare const normalize: (self: BigDecimal) => BigDecimal;
  * console.log(BigDecimal.format(reduced)) // "123.4"
  * ```
  *
+ * @see {@link round} for changing scale with configurable rounding
+ *
  * @category scaling
  * @since 2.0.0
  */
 export declare const scale: {
     /**
-     * Scales a `BigDecimal` to the specified scale.
+     * Changes a `BigDecimal` to the specified scale.
+     *
+     * **When to use**
+     *
+     * Use to change how many decimal places are represented by a `BigDecimal`.
      *
      * **Details**
      *
@@ -159,12 +236,18 @@ export declare const scale: {
      * console.log(BigDecimal.format(reduced)) // "123.4"
      * ```
      *
+     * @see {@link round} for changing scale with configurable rounding
+     *
      * @category scaling
      * @since 2.0.0
      */
     (scale: number): (self: BigDecimal) => BigDecimal;
     /**
-     * Scales a `BigDecimal` to the specified scale.
+     * Changes a `BigDecimal` to the specified scale.
+     *
+     * **When to use**
+     *
+     * Use to change how many decimal places are represented by a `BigDecimal`.
      *
      * **Details**
      *
@@ -188,6 +271,8 @@ export declare const scale: {
      * console.log(BigDecimal.format(reduced)) // "123.4"
      * ```
      *
+     * @see {@link round} for changing scale with configurable rounding
+     *
      * @category scaling
      * @since 2.0.0
      */
@@ -196,6 +281,10 @@ export declare const scale: {
 /**
  * Provides an addition operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to add two `BigDecimal` values.
+ *
  * **Example** (Adding decimals)
  *
  * ```ts
@@ -208,6 +297,8 @@ export declare const scale: {
  * )
  * ```
  *
+ * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -215,6 +306,10 @@ export declare const sum: {
     /**
      * Provides an addition operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to add two `BigDecimal` values.
+     *
      * **Example** (Adding decimals)
      *
      * ```ts
@@ -227,6 +322,8 @@ export declare const sum: {
      * )
      * ```
      *
+     * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+     *
      * @category math
      * @since 2.0.0
      */
@@ -234,6 +331,10 @@ export declare const sum: {
     /**
      * Provides an addition operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to add two `BigDecimal` values.
+     *
      * **Example** (Adding decimals)
      *
      * ```ts
@@ -246,6 +347,8 @@ export declare const sum: {
      * )
      * ```
      *
+     * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+     *
      * @category math
      * @since 2.0.0
      */
@@ -254,6 +357,10 @@ export declare const sum: {
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their sum as a single `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to sum all `BigDecimal` values in an iterable.
+ *
  * **Example** (Adding multiple decimals)
  *
  * ```ts
@@ -266,6 +373,8 @@ export declare const sum: {
  * )
  * ```
  *
+ * @see {@link sum} for adding two `BigDecimal` values
+ *
  * @category math
  * @since 3.16.0
  */
@@ -273,6 +382,10 @@ export declare const sumAll: (collection: Iterable<BigDecimal>) => BigDecimal;
 /**
  * Provides a multiplication operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to multiply two `BigDecimal` values.
+ *
  * **Example** (Multiplying decimals)
  *
  * ```ts
@@ -285,6 +398,8 @@ export declare const sumAll: (collection: Iterable<BigDecimal>) => BigDecimal;
  * )
  * ```
  *
+ * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -292,6 +407,10 @@ export declare const multiply: {
     /**
      * Provides a multiplication operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to multiply two `BigDecimal` values.
+     *
      * **Example** (Multiplying decimals)
      *
      * ```ts
@@ -304,6 +423,8 @@ export declare const multiply: {
      * )
      * ```
      *
+     * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+     *
      * @category math
      * @since 2.0.0
      */
@@ -311,6 +432,10 @@ export declare const multiply: {
     /**
      * Provides a multiplication operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to multiply two `BigDecimal` values.
+     *
      * **Example** (Multiplying decimals)
      *
      * ```ts
@@ -323,6 +448,8 @@ export declare const multiply: {
      * )
      * ```
      *
+     * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+     *
      * @category math
      * @since 2.0.0
      */
@@ -331,6 +458,10 @@ export declare const multiply: {
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their multiplication as a single `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to multiply all `BigDecimal` values in an iterable.
+ *
  * **Example** (Multiplying multiple decimals)
  *
  * ```ts
@@ -343,6 +474,8 @@ export declare const multiply: {
  * )
  * ```
  *
+ * @see {@link multiply} for multiplying two `BigDecimal` values
+ *
  * @category math
  * @since 4.0.0
  */
@@ -350,6 +483,10 @@ export declare const multiplyAll: (collection: Iterable<BigDecimal>) => BigDecim
 /**
  * Provides a subtraction operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to subtract one `BigDecimal` value from another.
+ *
  * **Example** (Subtracting decimals)
  *
  * ```ts
@@ -369,6 +506,10 @@ export declare const subtract: {
     /**
      * Provides a subtraction operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to subtract one `BigDecimal` value from another.
+     *
      * **Example** (Subtracting decimals)
      *
      * ```ts
@@ -388,6 +529,10 @@ export declare const subtract: {
     /**
      * Provides a subtraction operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to subtract one `BigDecimal` value from another.
+     *
      * **Example** (Subtracting decimals)
      *
      * ```ts
@@ -406,7 +551,12 @@ export declare const subtract: {
     (self: BigDecimal, that: BigDecimal): BigDecimal;
 };
 /**
- * Provides a division operation on `BigDecimal`s.
+ * Divides `BigDecimal`s safely.
+ *
+ * **When to use**
+ *
+ * Use to divide `BigDecimal` values while representing division by zero as
+ * `Option.none`.
  *
  * **Details**
  *
@@ -445,12 +595,20 @@ export declare const subtract: {
  * ) // true
  * ```
  *
+ * @see {@link divideUnsafe} for division that throws when the divisor is zero
+ * @see {@link remainder} for the decimal remainder operation
+ *
  * @category math
  * @since 2.0.0
  */
 export declare const divide: {
     /**
-     * Provides a division operation on `BigDecimal`s.
+     * Divides `BigDecimal`s safely.
+     *
+     * **When to use**
+     *
+     * Use to divide `BigDecimal` values while representing division by zero as
+     * `Option.none`.
      *
      * **Details**
      *
@@ -489,12 +647,20 @@ export declare const divide: {
      * ) // true
      * ```
      *
+     * @see {@link divideUnsafe} for division that throws when the divisor is zero
+     * @see {@link remainder} for the decimal remainder operation
+     *
      * @category math
      * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>;
     /**
-     * Provides a division operation on `BigDecimal`s.
+     * Divides `BigDecimal`s safely.
+     *
+     * **When to use**
+     *
+     * Use to divide `BigDecimal` values while representing division by zero as
+     * `Option.none`.
      *
      * **Details**
      *
@@ -533,6 +699,9 @@ export declare const divide: {
      * ) // true
      * ```
      *
+     * @see {@link divideUnsafe} for division that throws when the divisor is zero
+     * @see {@link remainder} for the decimal remainder operation
+     *
      * @category math
      * @since 2.0.0
      */
@@ -541,6 +710,11 @@ export declare const divide: {
 /**
  * Provides an unsafe division operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use when you need the decimal quotient and the divisor is known to be
+ * non-zero, so division by zero should be a thrown exception.
+ *
  * **Details**
  *
  * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -559,6 +733,8 @@ export declare const divide: {
  * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
  * ```
  *
+ * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
@@ -566,6 +742,11 @@ export declare const divideUnsafe: {
     /**
      * Provides an unsafe division operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use when you need the decimal quotient and the divisor is known to be
+     * non-zero, so division by zero should be a thrown exception.
+     *
      * **Details**
      *
      * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -584,6 +765,8 @@ export declare const divideUnsafe: {
      * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
      * ```
      *
+     * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+     *
      * @category math
      * @since 4.0.0
      */
@@ -591,6 +774,11 @@ export declare const divideUnsafe: {
     /**
      * Provides an unsafe division operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use when you need the decimal quotient and the divisor is known to be
+     * non-zero, so division by zero should be a thrown exception.
+     *
      * **Details**
      *
      * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -609,6 +797,8 @@ export declare const divideUnsafe: {
      * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
      * ```
      *
+     * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+     *
      * @category math
      * @since 4.0.0
      */
@@ -617,6 +807,11 @@ export declare const divideUnsafe: {
 /**
  * Provides an `Order` instance for `BigDecimal` that allows comparing and sorting BigDecimal values.
  *
+ * **When to use**
+ *
+ * Use when sorting or comparing decimal values through APIs that accept an
+ * ordering instance.
+ *
  * **Example** (Comparing decimals)
  *
  * ```ts
@@ -638,6 +833,10 @@ export declare const Order: order.Order<BigDecimal>;
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is strictly less than another.
+ *
  * **Example** (Checking less-than comparisons)
  *
  * ```ts
@@ -665,6 +864,10 @@ export declare const isLessThan: {
     /**
      * Returns `true` if the first argument is less than the second, otherwise `false`.
      *
+     * **When to use**
+     *
+     * Use to test whether one `BigDecimal` is strictly less than another.
+     *
      * **Example** (Checking less-than comparisons)
      *
      * ```ts
@@ -692,6 +895,10 @@ export declare const isLessThan: {
     /**
      * Returns `true` if the first argument is less than the second, otherwise `false`.
      *
+     * **When to use**
+     *
+     * Use to test whether one `BigDecimal` is strictly less than another.
+     *
      * **Example** (Checking less-than comparisons)
      *
      * ```ts
@@ -718,7 +925,11 @@ export declare const isLessThan: {
     (self: BigDecimal, that: BigDecimal): boolean;
 };
 /**
- * Checks if a given `BigDecimal` is less than or equal to the provided one.
+ * Checks whether a given `BigDecimal` is less than or equal to the provided one.
+ *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is less than or equal to another.
  *
  * **Example** (Checking less-than-or-equal comparisons)
  *
@@ -745,7 +956,11 @@ export declare const isLessThan: {
  */
 export declare const isLessThanOrEqualTo: {
     /**
-     * Checks if a given `BigDecimal` is less than or equal to the provided one.
+     * Checks whether a given `BigDecimal` is less than or equal to the provided one.
+     *
+     * **When to use**
+     *
+     * Use to test whether one `BigDecimal` is less than or equal to another.
      *
      * **Example** (Checking less-than-or-equal comparisons)
      *
@@ -772,7 +987,11 @@ export declare const isLessThanOrEqualTo: {
      */
     (that: BigDecimal): (self: BigDecimal) => boolean;
     /**
-     * Checks if a given `BigDecimal` is less than or equal to the provided one.
+     * Checks whether a given `BigDecimal` is less than or equal to the provided one.
+     *
+     * **When to use**
+     *
+     * Use to test whether one `BigDecimal` is less than or equal to another.
      *
      * **Example** (Checking less-than-or-equal comparisons)
      *
@@ -802,6 +1021,10 @@ export declare const isLessThanOrEqualTo: {
 /**
  * Returns `true` if the first argument is greater than the second, otherwise `false`.
  *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is strictly greater than another.
+ *
  * **Example** (Checking greater-than comparisons)
  *
  * ```ts
@@ -829,6 +1052,10 @@ export declare const isGreaterThan: {
     /**
      * Returns `true` if the first argument is greater than the second, otherwise `false`.
      *
+     * **When to use**
+     *
+     * Use to test whether one `BigDecimal` is strictly greater than another.
+     *
      * **Example** (Checking greater-than comparisons)
      *
      * ```ts
@@ -856,6 +1083,10 @@ export declare const isGreaterThan: {
     /**
      * Returns `true` if the first argument is greater than the second, otherwise `false`.
      *
+     * **When to use**
+     *
+     * Use to test whether one `BigDecimal` is strictly greater than another.
+     *
      * **Example** (Checking greater-than comparisons)
      *
      * ```ts
@@ -882,7 +1113,11 @@ export declare const isGreaterThan: {
     (self: BigDecimal, that: BigDecimal): boolean;
 };
 /**
- * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+ * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
+ *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is greater than or equal to another.
  *
  * **Example** (Checking greater-than-or-equal comparisons)
  *
@@ -909,7 +1144,11 @@ export declare const isGreaterThan: {
  */
 export declare const isGreaterThanOrEqualTo: {
     /**
-     * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+     * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
+     *
+     * **When to use**
+     *
+     * Use to test whether one `BigDecimal` is greater than or equal to another.
      *
      * **Example** (Checking greater-than-or-equal comparisons)
      *
@@ -936,7 +1175,11 @@ export declare const isGreaterThanOrEqualTo: {
      */
     (that: BigDecimal): (self: BigDecimal) => boolean;
     /**
-     * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+     * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
+     *
+     * **When to use**
+     *
+     * Use to test whether one `BigDecimal` is greater than or equal to another.
      *
      * **Example** (Checking greater-than-or-equal comparisons)
      *
@@ -964,7 +1207,11 @@ export declare const isGreaterThanOrEqualTo: {
     (self: BigDecimal, that: BigDecimal): boolean;
 };
 /**
- * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+ * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` falls inside an inclusive range.
  *
  * **Example** (Checking decimal ranges)
  *
@@ -982,12 +1229,18 @@ export declare const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
  * ```
  *
+ * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+ *
  * @category predicates
  * @since 2.0.0
  */
 export declare const between: {
     /**
-     * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+     * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+     *
+     * **When to use**
+     *
+     * Use to test whether a `BigDecimal` falls inside an inclusive range.
      *
      * **Example** (Checking decimal ranges)
      *
@@ -1005,6 +1258,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
      * ```
      *
+     * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+     *
      * @category predicates
      * @since 2.0.0
      */
@@ -1013,7 +1268,11 @@ export declare const between: {
         maximum: BigDecimal;
     }): (self: BigDecimal) => boolean;
     /**
-     * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+     * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+     *
+     * **When to use**
+     *
+     * Use to test whether a `BigDecimal` falls inside an inclusive range.
      *
      * **Example** (Checking decimal ranges)
      *
@@ -1031,6 +1290,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
      * ```
      *
+     * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+     *
      * @category predicates
      * @since 2.0.0
      */
@@ -1042,6 +1303,10 @@ export declare const between: {
 /**
  * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
  *
+ * **When to use**
+ *
+ * Use to force a `BigDecimal` into an inclusive range.
+ *
  * **Details**
  *
  * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1073,6 +1338,8 @@ export declare const between: {
  * )
  * ```
  *
+ * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1080,6 +1347,10 @@ export declare const clamp: {
     /**
      * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
      *
+     * **When to use**
+     *
+     * Use to force a `BigDecimal` into an inclusive range.
+     *
      * **Details**
      *
      * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1111,6 +1382,8 @@ export declare const clamp: {
      * )
      * ```
      *
+     * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1121,6 +1394,10 @@ export declare const clamp: {
     /**
      * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
      *
+     * **When to use**
+     *
+     * Use to force a `BigDecimal` into an inclusive range.
+     *
      * **Details**
      *
      * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1152,6 +1429,8 @@ export declare const clamp: {
      * )
      * ```
      *
+     * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1163,6 +1442,10 @@ export declare const clamp: {
 /**
  * Returns the minimum between two `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to select the smaller of two `BigDecimal` values.
+ *
  * **Example** (Selecting the smaller decimal)
  *
  * ```ts
@@ -1175,6 +1458,8 @@ export declare const clamp: {
  * )
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1182,6 +1467,10 @@ export declare const min: {
     /**
      * Returns the minimum between two `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to select the smaller of two `BigDecimal` values.
+     *
      * **Example** (Selecting the smaller decimal)
      *
      * ```ts
@@ -1194,6 +1483,8 @@ export declare const min: {
      * )
      * ```
      *
+     * @see {@link max} for selecting the larger value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1201,6 +1492,10 @@ export declare const min: {
     /**
      * Returns the minimum between two `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to select the smaller of two `BigDecimal` values.
+     *
      * **Example** (Selecting the smaller decimal)
      *
      * ```ts
@@ -1213,6 +1508,8 @@ export declare const min: {
      * )
      * ```
      *
+     * @see {@link max} for selecting the larger value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1221,6 +1518,10 @@ export declare const min: {
 /**
  * Returns the maximum between two `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to select the larger of two `BigDecimal` values.
+ *
  * **Example** (Selecting the larger decimal)
  *
  * ```ts
@@ -1233,6 +1534,8 @@ export declare const min: {
  * )
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1240,6 +1543,10 @@ export declare const max: {
     /**
      * Returns the maximum between two `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to select the larger of two `BigDecimal` values.
+     *
      * **Example** (Selecting the larger decimal)
      *
      * ```ts
@@ -1252,6 +1559,8 @@ export declare const max: {
      * )
      * ```
      *
+     * @see {@link min} for selecting the smaller value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1259,6 +1568,10 @@ export declare const max: {
     /**
      * Returns the maximum between two `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to select the larger of two `BigDecimal` values.
+     *
      * **Example** (Selecting the larger decimal)
      *
      * ```ts
@@ -1271,6 +1584,8 @@ export declare const max: {
      * )
      * ```
      *
+     * @see {@link min} for selecting the smaller value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1279,6 +1594,10 @@ export declare const max: {
 /**
  * Determines the sign of a given `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to classify a `BigDecimal` as negative, zero, or positive.
+ *
  * **Example** (Reading decimal signs)
  *
  * ```ts
@@ -1297,6 +1616,10 @@ export declare const sign: (n: BigDecimal) => Ordering;
 /**
  * Determines the absolute value of a given `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to remove the sign from a `BigDecimal` while preserving its magnitude.
+ *
  * **Example** (Calculating absolute values)
  *
  * ```ts
@@ -1315,6 +1638,10 @@ export declare const abs: (n: BigDecimal) => BigDecimal;
 /**
  * Provides a negate operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to flip the sign of a `BigDecimal`.
+ *
  * **Example** (Negating decimals)
  *
  * ```ts
@@ -1330,7 +1657,13 @@ export declare const abs: (n: BigDecimal) => BigDecimal;
  */
 export declare const negate: (n: BigDecimal) => BigDecimal;
 /**
- * Returns the remainder left over when one operand is divided by a second operand.
+ * Computes the decimal remainder safely when one operand is divided by a second
+ * operand.
+ *
+ * **When to use**
+ *
+ * Use to compute a decimal remainder while representing division by zero as
+ * `Option.none`.
  *
  * **Details**
  *
@@ -1365,12 +1698,21 @@ export declare const negate: (n: BigDecimal) => BigDecimal;
  * )
  * ```
  *
+ * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+ * @see {@link divide} for decimal quotient calculation
+ *
  * @category math
  * @since 2.0.0
  */
 export declare const remainder: {
     /**
-     * Returns the remainder left over when one operand is divided by a second operand.
+     * Computes the decimal remainder safely when one operand is divided by a second
+     * operand.
+     *
+     * **When to use**
+     *
+     * Use to compute a decimal remainder while representing division by zero as
+     * `Option.none`.
      *
      * **Details**
      *
@@ -1405,12 +1747,21 @@ export declare const remainder: {
      * )
      * ```
      *
+     * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+     * @see {@link divide} for decimal quotient calculation
+     *
      * @category math
      * @since 2.0.0
      */
     (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>;
     /**
-     * Returns the remainder left over when one operand is divided by a second operand.
+     * Computes the decimal remainder safely when one operand is divided by a second
+     * operand.
+     *
+     * **When to use**
+     *
+     * Use to compute a decimal remainder while representing division by zero as
+     * `Option.none`.
      *
      * **Details**
      *
@@ -1445,13 +1796,22 @@ export declare const remainder: {
      * )
      * ```
      *
+     * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+     * @see {@link divide} for decimal quotient calculation
+     *
      * @category math
      * @since 2.0.0
      */
     (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal>;
 };
 /**
- * Returns the remainder left over when one operand is divided by a second operand.
+ * Returns the decimal remainder left over when one operand is divided by a
+ * non-zero second operand, throwing for division by zero.
+ *
+ * **When to use**
+ *
+ * Use when you need the decimal remainder and the divisor is known to be
+ * non-zero, so division by zero should be a thrown exception.
  *
  * **Gotchas**
  *
@@ -1477,12 +1837,20 @@ export declare const remainder: {
  * )
  * ```
  *
+ * @see {@link remainder} for returning `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
 export declare const remainderUnsafe: {
     /**
-     * Returns the remainder left over when one operand is divided by a second operand.
+     * Returns the decimal remainder left over when one operand is divided by a
+     * non-zero second operand, throwing for division by zero.
+     *
+     * **When to use**
+     *
+     * Use when you need the decimal remainder and the divisor is known to be
+     * non-zero, so division by zero should be a thrown exception.
      *
      * **Gotchas**
      *
@@ -1508,12 +1876,20 @@ export declare const remainderUnsafe: {
      * )
      * ```
      *
+     * @see {@link remainder} for returning `Option.none` when the divisor is zero
+     *
      * @category math
      * @since 4.0.0
      */
     (divisor: BigDecimal): (self: BigDecimal) => BigDecimal;
     /**
-     * Returns the remainder left over when one operand is divided by a second operand.
+     * Returns the decimal remainder left over when one operand is divided by a
+     * non-zero second operand, throwing for division by zero.
+     *
+     * **When to use**
+     *
+     * Use when you need the decimal remainder and the divisor is known to be
+     * non-zero, so division by zero should be a thrown exception.
      *
      * **Gotchas**
      *
@@ -1539,6 +1915,8 @@ export declare const remainderUnsafe: {
      * )
      * ```
      *
+     * @see {@link remainder} for returning `Option.none` when the divisor is zero
+     *
      * @category math
      * @since 4.0.0
      */
@@ -1547,6 +1925,11 @@ export declare const remainderUnsafe: {
 /**
  * Provides an `Equivalence` instance for `BigDecimal` that determines equality between BigDecimal values.
  *
+ * **When to use**
+ *
+ * Use when comparing decimal values through APIs that accept an equivalence
+ * relation.
+ *
  * **Example** (Checking decimal equivalence)
  *
  * ```ts
@@ -1565,7 +1948,11 @@ export declare const remainderUnsafe: {
  */
 export declare const Equivalence: Equ.Equivalence<BigDecimal>;
 /**
- * Checks if two `BigDecimal`s are equal.
+ * Checks whether two `BigDecimal`s are equal.
+ *
+ * **When to use**
+ *
+ * Use to compare two `BigDecimal` values for numeric equality.
  *
  * **Example** (Checking decimal equality)
  *
@@ -1580,12 +1967,18 @@ export declare const Equivalence: Equ.Equivalence<BigDecimal>;
  * console.log(BigDecimal.equals(a, c)) // false
  * ```
  *
+ * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+ *
  * @category predicates
  * @since 2.0.0
  */
 export declare const equals: {
     /**
-     * Checks if two `BigDecimal`s are equal.
+     * Checks whether two `BigDecimal`s are equal.
+     *
+     * **When to use**
+     *
+     * Use to compare two `BigDecimal` values for numeric equality.
      *
      * **Example** (Checking decimal equality)
      *
@@ -1600,12 +1993,18 @@ export declare const equals: {
      * console.log(BigDecimal.equals(a, c)) // false
      * ```
      *
+     * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+     *
      * @category predicates
      * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => boolean;
     /**
-     * Checks if two `BigDecimal`s are equal.
+     * Checks whether two `BigDecimal`s are equal.
+     *
+     * **When to use**
+     *
+     * Use to compare two `BigDecimal` values for numeric equality.
      *
      * **Example** (Checking decimal equality)
      *
@@ -1620,6 +2019,8 @@ export declare const equals: {
      * console.log(BigDecimal.equals(a, c)) // false
      * ```
      *
+     * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+     *
      * @category predicates
      * @since 2.0.0
      */
@@ -1628,6 +2029,10 @@ export declare const equals: {
 /**
  * Creates a `BigDecimal` from a `bigint` value.
  *
+ * **When to use**
+ *
+ * Use to construct an integer `BigDecimal` from a `bigint`.
+ *
  * **Example** (Creating decimals from bigint)
  *
  * ```ts
@@ -1640,12 +2045,19 @@ export declare const equals: {
  * console.log(BigDecimal.format(largeBigInt)) // "9007199254740991"
  * ```
  *
+ * @see {@link make} for constructing a decimal with an explicit scale
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const fromBigInt: (n: bigint) => BigDecimal;
 /**
- * Creates a `BigDecimal` from a `number` value.
+ * Creates a `BigDecimal` from a finite `number`, throwing for non-finite input.
+ *
+ * **When to use**
+ *
+ * Use when a finite JavaScript number must become a `BigDecimal` and invalid
+ * input should throw.
  *
  * **Gotchas**
  *
@@ -1663,12 +2075,19 @@ export declare const fromBigInt: (n: bigint) => BigDecimal;
  * assert.deepStrictEqual(BigDecimal.fromNumberUnsafe(123.456), BigDecimal.make(123456n, 3))
  * ```
  *
+ * @see {@link fromNumber} for returning `Option.none` when the number is not finite
+ *
  * @category constructors
  * @since 4.0.0
  */
 export declare const fromNumberUnsafe: (n: number) => BigDecimal;
 /**
- * Creates a `BigDecimal` from a `number` value.
+ * Creates a `BigDecimal` safely from a finite `number`.
+ *
+ * **When to use**
+ *
+ * Use to convert a finite JavaScript number to a `BigDecimal` without throwing
+ * on invalid input.
  *
  * **Details**
  *
@@ -1693,12 +2112,19 @@ export declare const fromNumberUnsafe: (n: number) => BigDecimal;
  * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), Option.none())
  * ```
  *
+ * @see {@link fromNumberUnsafe} for throwing when the number is not finite
+ * @see {@link fromString} for parsing decimal strings directly
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const fromNumber: (n: number) => Option.Option<BigDecimal>;
 /**
- * Safely parses a decimal string into a `BigDecimal`.
+ * Parses a decimal string into a `BigDecimal` safely.
+ *
+ * **When to use**
+ *
+ * Use to parse external decimal text without throwing on invalid input.
  *
  * **Details**
  *
@@ -1720,6 +2146,9 @@ export declare const fromNumber: (n: number) => Option.Option<BigDecimal>;
  * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
  * ```
  *
+ * @see {@link fromStringUnsafe} for parsing that throws on invalid input
+ * @see {@link fromNumber} for converting finite JavaScript numbers
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1728,6 +2157,10 @@ export declare const fromString: (s: string) => Option.Option<BigDecimal>;
  * Parses a decimal string into a `BigDecimal`, throwing if the string is
  * invalid.
  *
+ * **When to use**
+ *
+ * Use when decimal text is expected to be valid and parse errors should throw.
+ *
  * **Details**
  *
  * Accepts the same syntax as `fromString`. Use `fromString` when invalid input
@@ -1744,6 +2177,8 @@ export declare const fromString: (s: string) => Option.Option<BigDecimal>;
  * assert.throws(() => BigDecimal.fromStringUnsafe("123.abc"))
  * ```
  *
+ * @see {@link fromString} for returning `Option.none` on invalid input
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1751,6 +2186,10 @@ export declare const fromStringUnsafe: (s: string) => BigDecimal;
 /**
  * Formats a `BigDecimal` as a string.
  *
+ * **When to use**
+ *
+ * Use to render a `BigDecimal` as plain decimal text when possible.
+ *
  * **Details**
  *
  * The value is normalized before formatting. Scientific notation is used when
@@ -1768,6 +2207,8 @@ export declare const fromStringUnsafe: (s: string) => BigDecimal;
  * assert.deepStrictEqual(BigDecimal.format(BigDecimal.fromStringUnsafe("-0.00000123")), "-0.00000123")
  * ```
  *
+ * @see {@link toExponential} for always rendering scientific notation
+ *
  * @category converting
  * @since 2.0.0
  */
@@ -1775,6 +2216,10 @@ export declare const format: (n: BigDecimal) => string;
 /**
  * Formats a given `BigDecimal` as a `string` in scientific notation.
  *
+ * **When to use**
+ *
+ * Use to render a `BigDecimal` in scientific notation.
+ *
  * **Example** (Formatting decimals exponentially)
  *
  * ```ts
@@ -1784,6 +2229,8 @@ export declare const format: (n: BigDecimal) => string;
  * assert.deepStrictEqual(BigDecimal.toExponential(BigDecimal.make(123456n, -5)), "1.23456e+10")
  * ```
  *
+ * @see {@link format} for plain decimal formatting when possible
+ *
  * @category converting
  * @since 3.11.0
  */
@@ -1791,6 +2238,11 @@ export declare const toExponential: (n: BigDecimal) => string;
 /**
  * Converts a `BigDecimal` to a JavaScript `number`.
  *
+ * **When to use**
+ *
+ * Use when an interop boundary requires a JavaScript number and can tolerate
+ * precision loss.
+ *
  * **Gotchas**
  *
  * This conversion is unsafe because the result can lose integer or fractional
@@ -1806,12 +2258,18 @@ export declare const toExponential: (n: BigDecimal) => string;
  * assert.deepStrictEqual(BigDecimal.toNumberUnsafe(BigDecimal.fromStringUnsafe("123.456")), 123.456)
  * ```
  *
+ * @see {@link format} for preserving decimal precision as text
+ *
  * @category converting
  * @since 4.0.0
  */
 export declare const toNumberUnsafe: (n: BigDecimal) => number;
 /**
- * Checks if a given `BigDecimal` is an integer.
+ * Checks whether a given `BigDecimal` is an integer.
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` has no fractional decimal part.
  *
  * **Example** (Checking integer decimals)
  *
@@ -1829,7 +2287,11 @@ export declare const toNumberUnsafe: (n: BigDecimal) => number;
  */
 export declare const isInteger: (n: BigDecimal) => boolean;
 /**
- * Checks if a given `BigDecimal` is `0`.
+ * Checks whether a given `BigDecimal` is `0`.
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is exactly zero.
  *
  * **Example** (Checking zero decimals)
  *
@@ -1846,7 +2308,11 @@ export declare const isInteger: (n: BigDecimal) => boolean;
  */
 export declare const isZero: (n: BigDecimal) => boolean;
 /**
- * Checks if a given `BigDecimal` is negative.
+ * Checks whether a given `BigDecimal` is negative.
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is less than zero.
  *
  * **Example** (Checking negative decimals)
  *
@@ -1864,7 +2330,11 @@ export declare const isZero: (n: BigDecimal) => boolean;
  */
 export declare const isNegative: (n: BigDecimal) => boolean;
 /**
- * Checks if a given `BigDecimal` is positive.
+ * Checks whether a given `BigDecimal` is positive.
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is greater than zero.
  *
  * **Example** (Checking positive decimals)
  *
@@ -1884,6 +2354,11 @@ export declare const isPositive: (n: BigDecimal) => boolean;
 /**
  * Rounding modes for `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use with `round` to choose how discarded digits affect a `BigDecimal`
+ * rounded to a target scale.
+ *
  * **Details**
  *
  * - `ceil`: round towards positive infinity
@@ -1897,12 +2372,21 @@ export declare const isPositive: (n: BigDecimal) => boolean;
  * - `half-even`: round to the nearest neighbor; if equidistant round to the neighbor with an even digit
  * - `half-odd`: round to the nearest neighbor; if equidistant round to the neighbor with an odd digit
  *
+ * @see {@link round} for configurable rounding with a `RoundingMode`
+ * @see {@link ceil} for fixed rounding toward positive infinity
+ * @see {@link floor} for fixed rounding toward negative infinity
+ * @see {@link truncate} for fixed rounding toward zero
+ *
  * @category math
  * @since 3.16.0
  */
 export type RoundingMode = "ceil" | "floor" | "to-zero" | "from-zero" | "half-ceil" | "half-floor" | "half-to-zero" | "half-from-zero" | "half-even" | "half-odd";
 /**
- * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+ * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
+ *
+ * **When to use**
+ *
+ * Use to round a decimal at a requested scale with an explicit rounding mode.
  *
  * **Example** (Rounding decimals)
  *
@@ -1920,12 +2404,20 @@ export type RoundingMode = "ceil" | "floor" | "to-zero" | "from-zero" | "half-ce
  * )
  * ```
  *
+ * @see {@link ceil} for fixed rounding toward positive infinity
+ * @see {@link floor} for fixed rounding toward negative infinity
+ * @see {@link truncate} for fixed rounding toward zero
+ *
  * @category math
  * @since 3.16.0
  */
 export declare const round: {
     /**
-     * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+     * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
+     *
+     * **When to use**
+     *
+     * Use to round a decimal at a requested scale with an explicit rounding mode.
      *
      * **Example** (Rounding decimals)
      *
@@ -1943,6 +2435,10 @@ export declare const round: {
      * )
      * ```
      *
+     * @see {@link ceil} for fixed rounding toward positive infinity
+     * @see {@link floor} for fixed rounding toward negative infinity
+     * @see {@link truncate} for fixed rounding toward zero
+     *
      * @category math
      * @since 3.16.0
      */
@@ -1951,7 +2447,11 @@ export declare const round: {
         mode?: RoundingMode;
     }): (self: BigDecimal) => BigDecimal;
     /**
-     * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+     * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
+     *
+     * **When to use**
+     *
+     * Use to round a decimal at a requested scale with an explicit rounding mode.
      *
      * **Example** (Rounding decimals)
      *
@@ -1969,6 +2469,10 @@ export declare const round: {
      * )
      * ```
      *
+     * @see {@link ceil} for fixed rounding toward positive infinity
+     * @see {@link floor} for fixed rounding toward negative infinity
+     * @see {@link truncate} for fixed rounding toward zero
+     *
      * @category math
      * @since 3.16.0
      */
@@ -1978,9 +2482,13 @@ export declare const round: {
     }): BigDecimal;
 };
 /**
- * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+ * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
  * rounding toward zero.
  *
+ * **When to use**
+ *
+ * Use to remove digits beyond a requested scale by rounding toward zero.
+ *
  * **Example** (Truncating decimals)
  *
  * ```ts
@@ -1990,14 +2498,22 @@ export declare const round: {
  * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
  * ```
  *
+ * @see {@link round} for configurable rounding modes
+ * @see {@link ceil} for rounding toward positive infinity
+ * @see {@link floor} for rounding toward negative infinity
+ *
  * @category math
  * @since 3.16.0
  */
 export declare const truncate: {
     /**
-     * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+     * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
      * rounding toward zero.
      *
+     * **When to use**
+     *
+     * Use to remove digits beyond a requested scale by rounding toward zero.
+     *
      * **Example** (Truncating decimals)
      *
      * ```ts
@@ -2007,14 +2523,22 @@ export declare const truncate: {
      * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
      * ```
      *
+     * @see {@link round} for configurable rounding modes
+     * @see {@link ceil} for rounding toward positive infinity
+     * @see {@link floor} for rounding toward negative infinity
+     *
      * @category math
      * @since 3.16.0
      */
     (scale: number): (self: BigDecimal) => BigDecimal;
     /**
-     * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+     * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
      * rounding toward zero.
      *
+     * **When to use**
+     *
+     * Use to remove digits beyond a requested scale by rounding toward zero.
+     *
      * **Example** (Truncating decimals)
      *
      * ```ts
@@ -2024,13 +2548,31 @@ export declare const truncate: {
      * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
      * ```
      *
+     * @see {@link round} for configurable rounding modes
+     * @see {@link ceil} for rounding toward positive infinity
+     * @see {@link floor} for rounding toward negative infinity
+     *
      * @category math
      * @since 3.16.0
      */
     (self: BigDecimal, scale?: number): BigDecimal;
 };
 /**
- * Calculate the ceiling of a `BigDecimal` at the given scale.
+ * Computes the ceiling of a `BigDecimal` at the given scale.
+ *
+ * **When to use**
+ *
+ * Use to round a decimal toward positive infinity at a requested scale.
+ *
+ * **Details**
+ *
+ * The default scale is `0`. Positive scales keep digits to the right of the
+ * decimal point, and negative scales round positions to the left of the decimal
+ * point.
+ *
+ * @see {@link floor} for rounding toward negative infinity
+ * @see {@link truncate} for rounding toward zero
+ * @see {@link round} for configurable rounding modes
  *
  * **Example** (Rounding decimals up)
  *
@@ -2050,7 +2592,21 @@ export declare const truncate: {
  */
 export declare const ceil: {
     /**
-     * Calculate the ceiling of a `BigDecimal` at the given scale.
+     * Computes the ceiling of a `BigDecimal` at the given scale.
+     *
+     * **When to use**
+     *
+     * Use to round a decimal toward positive infinity at a requested scale.
+     *
+     * **Details**
+     *
+     * The default scale is `0`. Positive scales keep digits to the right of the
+     * decimal point, and negative scales round positions to the left of the decimal
+     * point.
+     *
+     * @see {@link floor} for rounding toward negative infinity
+     * @see {@link truncate} for rounding toward zero
+     * @see {@link round} for configurable rounding modes
      *
      * **Example** (Rounding decimals up)
      *
@@ -2070,7 +2626,21 @@ export declare const ceil: {
      */
     (scale: number): (self: BigDecimal) => BigDecimal;
     /**
-     * Calculate the ceiling of a `BigDecimal` at the given scale.
+     * Computes the ceiling of a `BigDecimal` at the given scale.
+     *
+     * **When to use**
+     *
+     * Use to round a decimal toward positive infinity at a requested scale.
+     *
+     * **Details**
+     *
+     * The default scale is `0`. Positive scales keep digits to the right of the
+     * decimal point, and negative scales round positions to the left of the decimal
+     * point.
+     *
+     * @see {@link floor} for rounding toward negative infinity
+     * @see {@link truncate} for rounding toward zero
+     * @see {@link round} for configurable rounding modes
      *
      * **Example** (Rounding decimals up)
      *
@@ -2091,7 +2661,11 @@ export declare const ceil: {
     (self: BigDecimal, scale?: number): BigDecimal;
 };
 /**
- * Calculate the floor of a `BigDecimal` at the given scale.
+ * Computes the floor of a `BigDecimal` at the given scale.
+ *
+ * **When to use**
+ *
+ * Use to round a decimal toward negative infinity at a requested scale.
  *
  * **Example** (Rounding decimals down)
  *
@@ -2109,12 +2683,20 @@ export declare const ceil: {
  * )
  * ```
  *
+ * @see {@link ceil} for rounding toward positive infinity
+ * @see {@link truncate} for rounding toward zero
+ * @see {@link round} for configurable rounding modes
+ *
  * @category math
  * @since 3.16.0
  */
 export declare const floor: {
     /**
-     * Calculate the floor of a `BigDecimal` at the given scale.
+     * Computes the floor of a `BigDecimal` at the given scale.
+     *
+     * **When to use**
+     *
+     * Use to round a decimal toward negative infinity at a requested scale.
      *
      * **Example** (Rounding decimals down)
      *
@@ -2132,12 +2714,20 @@ export declare const floor: {
      * )
      * ```
      *
+     * @see {@link ceil} for rounding toward positive infinity
+     * @see {@link truncate} for rounding toward zero
+     * @see {@link round} for configurable rounding modes
+     *
      * @category math
      * @since 3.16.0
      */
     (scale: number): (self: BigDecimal) => BigDecimal;
     /**
-     * Calculate the floor of a `BigDecimal` at the given scale.
+     * Computes the floor of a `BigDecimal` at the given scale.
+     *
+     * **When to use**
+     *
+     * Use to round a decimal toward negative infinity at a requested scale.
      *
      * **Example** (Rounding decimals down)
      *
@@ -2155,6 +2745,10 @@ export declare const floor: {
      * )
      * ```
      *
+     * @see {@link ceil} for rounding toward positive infinity
+     * @see {@link truncate} for rounding toward zero
+     * @see {@link round} for configurable rounding modes
+     *
      * @category math
      * @since 3.16.0
      */