effect 4.0.0-beta.70 → 4.0.0-beta.71

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
@@ -46,6 +95,10 @@ export interface BigDecimal extends Equal.Equal, Pipeable, Inspectable {
 /**
  * Checks if a given value is a `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `BigDecimal`.
+ *
  * **Example** (Checking BigDecimal values)
  *
  * ```ts
@@ -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,6 +166,8 @@ export declare const make: (value: bigint, scale: number) => BigDecimal;
  * )
  * ```
  *
+ * @see {@link format} for rendering normalized decimals as strings
+ *
  * @category scaling
  * @since 2.0.0
  */
@@ -108,6 +175,10 @@ export declare const normalize: (self: BigDecimal) => BigDecimal;
 /**
  * Scales a `BigDecimal` to the specified scale.
  *
+ * **When to use**
+ *
+ * Use to change how many decimal places are represented by a `BigDecimal`.
+ *
  * **Details**
  *
  * Increasing the scale appends decimal zeros. Decreasing the scale discards
@@ -130,6 +201,8 @@ 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
  */
@@ -137,6 +210,10 @@ export declare const scale: {
     /**
      * Scales a `BigDecimal` to the specified scale.
      *
+     * **When to use**
+     *
+     * Use to change how many decimal places are represented by a `BigDecimal`.
+     *
      * **Details**
      *
      * Increasing the scale appends decimal zeros. Decreasing the scale discards
@@ -159,6 +236,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
      */
@@ -166,6 +245,10 @@ export declare const scale: {
     /**
      * Scales a `BigDecimal` to the specified scale.
      *
+     * **When to use**
+     *
+     * Use to change how many decimal places are represented by a `BigDecimal`.
+     *
      * **Details**
      *
      * Increasing the scale appends decimal zeros. Decreasing the scale discards
@@ -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
@@ -408,6 +553,11 @@ export declare const subtract: {
 /**
  * Provides a division operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to divide `BigDecimal` values while representing division by zero as
+ * `Option.none`.
+ *
  * **Details**
  *
  * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -445,6 +595,9 @@ 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
  */
@@ -452,6 +605,11 @@ export declare const divide: {
     /**
      * Provides a division operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to divide `BigDecimal` values while representing division by zero as
+     * `Option.none`.
+     *
      * **Details**
      *
      * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -489,6 +647,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
      */
@@ -496,6 +657,11 @@ export declare const divide: {
     /**
      * Provides a division operation on `BigDecimal`s.
      *
+     * **When to use**
+     *
+     * Use to divide `BigDecimal` values while representing division by zero as
+     * `Option.none`.
+     *
      * **Details**
      *
      * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -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 the divisor is known to be non-zero and 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 the divisor is known to be non-zero and 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 the divisor is known to be non-zero and 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,10 @@ export declare const divideUnsafe: {
 /**
  * Provides an `Order` instance for `BigDecimal` that allows comparing and sorting BigDecimal values.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Order` instance for `BigDecimal` values.
+ *
  * **Example** (Comparing decimals)
  *
  * ```ts
@@ -638,6 +832,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 +863,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 +894,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
@@ -720,6 +926,10 @@ export declare const isLessThan: {
 /**
  * Checks if 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)
  *
  * ```ts
@@ -747,6 +957,10 @@ export declare const isLessThanOrEqualTo: {
     /**
      * Checks if 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)
      *
      * ```ts
@@ -774,6 +988,10 @@ export declare const isLessThanOrEqualTo: {
     /**
      * Checks if 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)
      *
      * ```ts
@@ -802,6 +1020,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 +1051,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 +1082,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
@@ -884,6 +1114,10 @@ export declare const isGreaterThan: {
 /**
  * Checks if 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)
  *
  * ```ts
@@ -911,6 +1145,10 @@ export declare const isGreaterThanOrEqualTo: {
     /**
      * Checks if 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)
      *
      * ```ts
@@ -938,6 +1176,10 @@ export declare const isGreaterThanOrEqualTo: {
     /**
      * Checks if 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)
      *
      * ```ts
@@ -966,6 +1208,10 @@ export declare const isGreaterThanOrEqualTo: {
 /**
  * Checks if 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)
  *
  * ```ts
@@ -982,6 +1228,8 @@ 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
  */
@@ -989,6 +1237,10 @@ export declare const between: {
     /**
      * Checks if 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)
      *
      * ```ts
@@ -1005,6 +1257,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
      */
@@ -1015,6 +1269,10 @@ export declare const between: {
     /**
      * Checks if 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)
      *
      * ```ts
@@ -1031,6 +1289,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 +1302,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 +1337,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 +1346,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 +1381,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 +1393,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 +1428,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 +1441,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 +1457,8 @@ export declare const clamp: {
  * )
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1182,6 +1466,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 +1482,8 @@ export declare const min: {
      * )
      * ```
      *
+     * @see {@link max} for selecting the larger value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1201,6 +1491,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 +1507,8 @@ export declare const min: {
      * )
      * ```
      *
+     * @see {@link max} for selecting the larger value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1221,6 +1517,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 +1533,8 @@ export declare const min: {
  * )
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1240,6 +1542,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 +1558,8 @@ export declare const max: {
      * )
      * ```
      *
+     * @see {@link min} for selecting the smaller value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1259,6 +1567,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 +1583,8 @@ export declare const max: {
      * )
      * ```
      *
+     * @see {@link min} for selecting the smaller value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1279,6 +1593,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 +1615,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 +1637,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
@@ -1332,6 +1658,11 @@ export declare const negate: (n: BigDecimal) => BigDecimal;
 /**
  * Returns the remainder left over 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**
  *
  * If the divisor is `0`, the result will be `Option.none()`.
@@ -1365,6 +1696,9 @@ 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
  */
@@ -1372,6 +1706,11 @@ export declare const remainder: {
     /**
      * Returns the remainder left over 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**
      *
      * If the divisor is `0`, the result will be `Option.none()`.
@@ -1405,6 +1744,9 @@ 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
      */
@@ -1412,6 +1754,11 @@ export declare const remainder: {
     /**
      * Returns the remainder left over 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**
      *
      * If the divisor is `0`, the result will be `Option.none()`.
@@ -1445,6 +1792,9 @@ 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
      */
@@ -1453,6 +1803,11 @@ export declare const remainder: {
 /**
  * Returns the remainder left over when one operand is divided by a second operand.
  *
+ * **When to use**
+ *
+ * Use when the divisor is known to be non-zero and division by zero should be a
+ * thrown exception.
+ *
  * **Gotchas**
  *
  * Throws a `RangeError` if the divisor is `0`.
@@ -1477,6 +1832,8 @@ export declare const remainder: {
  * )
  * ```
  *
+ * @see {@link remainder} for returning `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1484,6 +1841,11 @@ export declare const remainderUnsafe: {
     /**
      * Returns the remainder left over when one operand is divided by a second operand.
      *
+     * **When to use**
+     *
+     * Use when the divisor is known to be non-zero and division by zero should be a
+     * thrown exception.
+     *
      * **Gotchas**
      *
      * Throws a `RangeError` if the divisor is `0`.
@@ -1508,6 +1870,8 @@ export declare const remainderUnsafe: {
      * )
      * ```
      *
+     * @see {@link remainder} for returning `Option.none` when the divisor is zero
+     *
      * @category math
      * @since 4.0.0
      */
@@ -1515,6 +1879,11 @@ export declare const remainderUnsafe: {
     /**
      * Returns the remainder left over when one operand is divided by a second operand.
      *
+     * **When to use**
+     *
+     * Use when the divisor is known to be non-zero and division by zero should be a
+     * thrown exception.
+     *
      * **Gotchas**
      *
      * Throws a `RangeError` if the divisor is `0`.
@@ -1539,6 +1908,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 +1918,10 @@ export declare const remainderUnsafe: {
 /**
  * Provides an `Equivalence` instance for `BigDecimal` that determines equality between BigDecimal values.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for decimal equality.
+ *
  * **Example** (Checking decimal equivalence)
  *
  * ```ts
@@ -1567,6 +1942,10 @@ export declare const Equivalence: Equ.Equivalence<BigDecimal>;
 /**
  * Checks if two `BigDecimal`s are equal.
  *
+ * **When to use**
+ *
+ * Use to compare two `BigDecimal` values for numeric equality.
+ *
  * **Example** (Checking decimal equality)
  *
  * ```ts
@@ -1580,6 +1959,8 @@ 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
  */
@@ -1587,6 +1968,10 @@ export declare const equals: {
     /**
      * Checks if two `BigDecimal`s are equal.
      *
+     * **When to use**
+     *
+     * Use to compare two `BigDecimal` values for numeric equality.
+     *
      * **Example** (Checking decimal equality)
      *
      * ```ts
@@ -1600,6 +1985,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
      */
@@ -1607,6 +1994,10 @@ export declare const equals: {
     /**
      * Checks if two `BigDecimal`s are equal.
      *
+     * **When to use**
+     *
+     * Use to compare two `BigDecimal` values for numeric equality.
+     *
      * **Example** (Checking decimal equality)
      *
      * ```ts
@@ -1620,6 +2011,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 +2021,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,6 +2037,8 @@ 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
  */
@@ -1647,6 +2046,11 @@ export declare const fromBigInt: (n: bigint) => BigDecimal;
 /**
  * Creates a `BigDecimal` from a `number` value.
  *
+ * **When to use**
+ *
+ * Use when a finite JavaScript number must become a `BigDecimal` and invalid
+ * input should throw.
+ *
  * **Gotchas**
  *
  * It is not recommended to convert a floating point number to a decimal
@@ -1663,6 +2067,8 @@ 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
  */
@@ -1670,6 +2076,11 @@ export declare const fromNumberUnsafe: (n: number) => BigDecimal;
 /**
  * Creates a `BigDecimal` from a `number` value.
  *
+ * **When to use**
+ *
+ * Use to convert a finite JavaScript number to a `BigDecimal` without throwing
+ * on invalid input.
+ *
  * **Details**
  *
  * Returns `Option.none()` for `NaN`, `+Infinity` or `-Infinity`.
@@ -1693,6 +2104,9 @@ 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
  */
@@ -1700,6 +2114,10 @@ export declare const fromNumber: (n: number) => Option.Option<BigDecimal>;
 /**
  * Safely parses a decimal string into a `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to parse external decimal text without throwing on invalid input.
+ *
  * **Details**
  *
  * Returns `Option.some` for valid decimal or exponent notation and
@@ -1720,6 +2138,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 +2149,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 +2169,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 +2178,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 +2199,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 +2208,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 +2221,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 +2230,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,6 +2250,8 @@ 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
  */
@@ -1813,6 +2259,10 @@ export declare const toNumberUnsafe: (n: BigDecimal) => number;
 /**
  * Checks if a given `BigDecimal` is an integer.
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` has no fractional decimal part.
+ *
  * **Example** (Checking integer decimals)
  *
  * ```ts
@@ -1831,6 +2281,10 @@ export declare const isInteger: (n: BigDecimal) => boolean;
 /**
  * Checks if a given `BigDecimal` is `0`.
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is exactly zero.
+ *
  * **Example** (Checking zero decimals)
  *
  * ```ts
@@ -1848,6 +2302,10 @@ export declare const isZero: (n: BigDecimal) => boolean;
 /**
  * Checks if a given `BigDecimal` is negative.
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is less than zero.
+ *
  * **Example** (Checking negative decimals)
  *
  * ```ts
@@ -1866,6 +2324,10 @@ export declare const isNegative: (n: BigDecimal) => boolean;
 /**
  * Checks if a given `BigDecimal` is positive.
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is greater than zero.
+ *
  * **Example** (Checking positive decimals)
  *
  * ```ts
@@ -1884,6 +2346,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,6 +2364,11 @@ 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
  */
@@ -1904,6 +2376,10 @@ export type RoundingMode = "ceil" | "floor" | "to-zero" | "from-zero" | "half-ce
 /**
  * Rounds a `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)
  *
  * ```ts
@@ -1920,6 +2396,10 @@ 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
  */
@@ -1927,6 +2407,10 @@ export declare const round: {
     /**
      * Rounds a `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)
      *
      * ```ts
@@ -1943,6 +2427,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
      */
@@ -1953,6 +2441,10 @@ export declare const round: {
     /**
      * Rounds a `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)
      *
      * ```ts
@@ -1969,6 +2461,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
      */
@@ -1981,6 +2477,10 @@ export declare const round: {
  * Truncate a `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,6 +2490,10 @@ 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
  */
@@ -1998,6 +2502,10 @@ export declare const truncate: {
      * Truncate a `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,6 +2515,10 @@ 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
      */
@@ -2015,6 +2527,10 @@ export declare const truncate: {
      * Truncate a `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,6 +2540,10 @@ 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
      */
@@ -2032,6 +2552,20 @@ export declare const truncate: {
 /**
  * Calculate 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)
  *
  * ```ts
@@ -2052,6 +2586,20 @@ export declare const ceil: {
     /**
      * Calculate 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)
      *
      * ```ts
@@ -2072,6 +2620,20 @@ export declare const ceil: {
     /**
      * Calculate 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)
      *
      * ```ts
@@ -2093,6 +2655,10 @@ export declare const ceil: {
 /**
  * Calculate 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)
  *
  * ```ts
@@ -2109,6 +2675,10 @@ 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
  */
@@ -2116,6 +2686,10 @@ export declare const floor: {
     /**
      * Calculate 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)
      *
      * ```ts
@@ -2132,6 +2706,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
      */
@@ -2139,6 +2717,10 @@ export declare const floor: {
     /**
      * Calculate 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)
      *
      * ```ts
@@ -2155,6 +2737,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
      */