effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/BigDecimal.d.ts

@@ -24,14 +24,15 @@ declare const TypeId = "~effect/BigDecimal";
 /**
  * Represents an arbitrary precision decimal number.
  *
- * @example
+ * **Example** (Inspecting BigDecimal storage)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
- * const d = BigDecimal.fromNumberUnsafe(123.45)
+ * const d = BigDecimal.fromStringUnsafe("123.45")
  *
- * d.value // 12345n
- * d.scale // 2
+ * console.log(d.value) // 12345n
+ * console.log(d.scale) // 2
  * ```
  *
  * @category models
@@ -45,7 +46,8 @@ export interface BigDecimal extends Equal.Equal, Pipeable, Inspectable {
 /**
  * Checks if a given value is a `BigDecimal`.
  *
- * @example
+ * **Example** (Checking BigDecimal values)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -55,14 +57,15 @@ export interface BigDecimal extends Equal.Equal, Pipeable, Inspectable {
  * console.log(BigDecimal.isBigDecimal("123.45")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export declare const isBigDecimal: (u: unknown) => u is BigDecimal;
 /**
  * Creates a `BigDecimal` from a `bigint` value and a scale.
  *
- * @example
+ * **Example** (Creating decimals from bigint and scale)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -75,14 +78,15 @@ export declare const isBigDecimal: (u: unknown) => u is BigDecimal;
  * console.log(BigDecimal.format(integer)) // "42"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: (value: bigint, scale: number) => BigDecimal;
 /**
  * Normalizes a given `BigDecimal` by removing trailing zeros.
  *
- * @example
+ * **Example** (Normalizing trailing zeros)
+ *
  * ```ts
  * import { fromStringUnsafe, make, normalize } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -97,17 +101,19 @@ export declare const make: (value: bigint, scale: number) => BigDecimal;
  * )
  * ```
  *
- * @since 2.0.0
  * @category scaling
+ * @since 2.0.0
  */
 export declare const normalize: (self: BigDecimal) => BigDecimal;
 /**
- * Scales a given `BigDecimal` to the specified scale.
+ * Scales a `BigDecimal` to the specified scale.
+ *
+ * Increasing the scale appends decimal zeros. Decreasing the scale discards
+ * digits beyond the target scale by `bigint` division, which truncates toward
+ * zero.
  *
- * If the given scale is smaller than the current scale, the value will be rounded down to
- * the nearest integer.
+ * **Example** (Scaling decimal precision)
  *
- * @example
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -122,17 +128,19 @@ export declare const normalize: (self: BigDecimal) => BigDecimal;
  * console.log(BigDecimal.format(reduced)) // "123.4"
  * ```
  *
- * @since 2.0.0
  * @category scaling
+ * @since 2.0.0
  */
 export declare const scale: {
     /**
-     * Scales a given `BigDecimal` to the specified scale.
+     * Scales a `BigDecimal` to the specified scale.
+     *
+     * Increasing the scale appends decimal zeros. Decreasing the scale discards
+     * digits beyond the target scale by `bigint` division, which truncates toward
+     * zero.
      *
-     * If the given scale is smaller than the current scale, the value will be rounded down to
-     * the nearest integer.
+     * **Example** (Scaling decimal precision)
      *
-     * @example
      * ```ts
      * import { BigDecimal } from "effect"
      *
@@ -147,17 +155,19 @@ export declare const scale: {
      * console.log(BigDecimal.format(reduced)) // "123.4"
      * ```
      *
-     * @since 2.0.0
      * @category scaling
+     * @since 2.0.0
      */
     (scale: number): (self: BigDecimal) => BigDecimal;
     /**
-     * Scales a given `BigDecimal` to the specified scale.
+     * Scales a `BigDecimal` to the specified scale.
      *
-     * If the given scale is smaller than the current scale, the value will be rounded down to
-     * the nearest integer.
+     * Increasing the scale appends decimal zeros. Decreasing the scale discards
+     * digits beyond the target scale by `bigint` division, which truncates toward
+     * zero.
+     *
+     * **Example** (Scaling decimal precision)
      *
-     * @example
      * ```ts
      * import { BigDecimal } from "effect"
      *
@@ -172,15 +182,16 @@ export declare const scale: {
      * console.log(BigDecimal.format(reduced)) // "123.4"
      * ```
      *
-     * @since 2.0.0
      * @category scaling
+     * @since 2.0.0
      */
     (self: BigDecimal, scale: number): BigDecimal;
 };
 /**
  * Provides an addition operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Adding decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, sum } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -191,14 +202,15 @@ export declare const scale: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const sum: {
     /**
      * Provides an addition operation on `BigDecimal`s.
      *
-     * @example
+     * **Example** (Adding decimals)
+     *
      * ```ts
      * import { fromStringUnsafe, sum } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -209,14 +221,15 @@ export declare const sum: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => BigDecimal;
     /**
      * Provides an addition operation on `BigDecimal`s.
      *
-     * @example
+     * **Example** (Adding decimals)
+     *
      * ```ts
      * import { fromStringUnsafe, sum } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -227,15 +240,16 @@ export declare const sum: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): BigDecimal;
 };
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their sum as a single `BigDecimal`.
  *
- * @example
+ * **Example** (Adding multiple decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, sumAll } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -246,14 +260,15 @@ export declare const sum: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const sumAll: (collection: Iterable<BigDecimal>) => BigDecimal;
 /**
  * Provides a multiplication operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Multiplying decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, multiply } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -264,14 +279,15 @@ export declare const sumAll: (collection: Iterable<BigDecimal>) => BigDecimal;
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const multiply: {
     /**
      * Provides a multiplication operation on `BigDecimal`s.
      *
-     * @example
+     * **Example** (Multiplying decimals)
+     *
      * ```ts
      * import { fromStringUnsafe, multiply } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -282,14 +298,15 @@ export declare const multiply: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => BigDecimal;
     /**
      * Provides a multiplication operation on `BigDecimal`s.
      *
-     * @example
+     * **Example** (Multiplying decimals)
+     *
      * ```ts
      * import { fromStringUnsafe, multiply } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -300,15 +317,16 @@ export declare const multiply: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): BigDecimal;
 };
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their multiplication as a single `BigDecimal`.
  *
- * @example
+ * **Example** (Multiplying multiple decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, multiplyAll } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -319,14 +337,15 @@ export declare const multiply: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const multiplyAll: (collection: Iterable<BigDecimal>) => BigDecimal;
 /**
  * Provides a subtraction operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Subtracting decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, subtract } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -337,14 +356,15 @@ export declare const multiplyAll: (collection: Iterable<BigDecimal>) => BigDecim
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const subtract: {
     /**
      * Provides a subtraction operation on `BigDecimal`s.
      *
-     * @example
+     * **Example** (Subtracting decimals)
+     *
      * ```ts
      * import { fromStringUnsafe, subtract } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -355,14 +375,15 @@ export declare const subtract: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => BigDecimal;
     /**
      * Provides a subtraction operation on `BigDecimal`s.
      *
-     * @example
+     * **Example** (Subtracting decimals)
+     *
      * ```ts
      * import { fromStringUnsafe, subtract } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -373,218 +394,210 @@ export declare const subtract: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): BigDecimal;
 };
 /**
  * Provides a division operation on `BigDecimal`s.
  *
- * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
- * which represents the integer division rounded down to the nearest integer.
+ * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+ * with up to the default division precision.
  *
  * If the divisor is `0`, the result will be `Option.none()`.
  *
- * @example
+ * **Example** (Dividing decimals safely)
+ *
  * ```ts
  * import { BigDecimal, Option } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(
- *   BigDecimal.divide(
- *     BigDecimal.fromStringUnsafe("6"),
- *     BigDecimal.fromStringUnsafe("3")
- *   ),
- *   Option.some(BigDecimal.fromStringUnsafe("2"))
- * )
- * assert.deepStrictEqual(
- *   BigDecimal.divide(
- *     BigDecimal.fromStringUnsafe("6"),
- *     BigDecimal.fromStringUnsafe("4")
- *   ),
- *   Option.some(BigDecimal.fromStringUnsafe("1.5"))
- * )
- * assert.deepStrictEqual(
- *   BigDecimal.divide(
- *     BigDecimal.fromStringUnsafe("6"),
- *     BigDecimal.fromStringUnsafe("0")
- *   ),
- *   Option.none()
- * )
+ * console.log(
+ *   Option.getOrThrow(
+ *     BigDecimal.divide(
+ *       BigDecimal.fromStringUnsafe("6"),
+ *       BigDecimal.fromStringUnsafe("3")
+ *     )
+ *   )
+ * ) // BigDecimal(2)
+ * console.log(
+ *   Option.getOrThrow(
+ *     BigDecimal.divide(
+ *       BigDecimal.fromStringUnsafe("6"),
+ *       BigDecimal.fromStringUnsafe("4")
+ *     )
+ *   )
+ * ) // BigDecimal(1.5)
+ * console.log(
+ *   Option.isNone(
+ *     BigDecimal.divide(
+ *       BigDecimal.fromStringUnsafe("6"),
+ *       BigDecimal.fromStringUnsafe("0")
+ *     )
+ *   )
+ * ) // true
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const divide: {
     /**
      * Provides a division operation on `BigDecimal`s.
      *
-     * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
-     * which represents the integer division rounded down to the nearest integer.
+     * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+     * with up to the default division precision.
      *
      * If the divisor is `0`, the result will be `Option.none()`.
      *
-     * @example
+     * **Example** (Dividing decimals safely)
+     *
      * ```ts
      * import { BigDecimal, Option } from "effect"
-     * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(
-     *   BigDecimal.divide(
-     *     BigDecimal.fromStringUnsafe("6"),
-     *     BigDecimal.fromStringUnsafe("3")
-     *   ),
-     *   Option.some(BigDecimal.fromStringUnsafe("2"))
-     * )
-     * assert.deepStrictEqual(
-     *   BigDecimal.divide(
-     *     BigDecimal.fromStringUnsafe("6"),
-     *     BigDecimal.fromStringUnsafe("4")
-     *   ),
-     *   Option.some(BigDecimal.fromStringUnsafe("1.5"))
-     * )
-     * assert.deepStrictEqual(
-     *   BigDecimal.divide(
-     *     BigDecimal.fromStringUnsafe("6"),
-     *     BigDecimal.fromStringUnsafe("0")
-     *   ),
-     *   Option.none()
-     * )
+     * console.log(
+     *   Option.getOrThrow(
+     *     BigDecimal.divide(
+     *       BigDecimal.fromStringUnsafe("6"),
+     *       BigDecimal.fromStringUnsafe("3")
+     *     )
+     *   )
+     * ) // BigDecimal(2)
+     * console.log(
+     *   Option.getOrThrow(
+     *     BigDecimal.divide(
+     *       BigDecimal.fromStringUnsafe("6"),
+     *       BigDecimal.fromStringUnsafe("4")
+     *     )
+     *   )
+     * ) // BigDecimal(1.5)
+     * console.log(
+     *   Option.isNone(
+     *     BigDecimal.divide(
+     *       BigDecimal.fromStringUnsafe("6"),
+     *       BigDecimal.fromStringUnsafe("0")
+     *     )
+     *   )
+     * ) // true
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>;
     /**
      * Provides a division operation on `BigDecimal`s.
      *
-     * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
-     * which represents the integer division rounded down to the nearest integer.
+     * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+     * with up to the default division precision.
      *
      * If the divisor is `0`, the result will be `Option.none()`.
      *
-     * @example
+     * **Example** (Dividing decimals safely)
+     *
      * ```ts
      * import { BigDecimal, Option } from "effect"
-     * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(
-     *   BigDecimal.divide(
-     *     BigDecimal.fromStringUnsafe("6"),
-     *     BigDecimal.fromStringUnsafe("3")
-     *   ),
-     *   Option.some(BigDecimal.fromStringUnsafe("2"))
-     * )
-     * assert.deepStrictEqual(
-     *   BigDecimal.divide(
-     *     BigDecimal.fromStringUnsafe("6"),
-     *     BigDecimal.fromStringUnsafe("4")
-     *   ),
-     *   Option.some(BigDecimal.fromStringUnsafe("1.5"))
-     * )
-     * assert.deepStrictEqual(
-     *   BigDecimal.divide(
-     *     BigDecimal.fromStringUnsafe("6"),
-     *     BigDecimal.fromStringUnsafe("0")
-     *   ),
-     *   Option.none()
-     * )
+     * console.log(
+     *   Option.getOrThrow(
+     *     BigDecimal.divide(
+     *       BigDecimal.fromStringUnsafe("6"),
+     *       BigDecimal.fromStringUnsafe("3")
+     *     )
+     *   )
+     * ) // BigDecimal(2)
+     * console.log(
+     *   Option.getOrThrow(
+     *     BigDecimal.divide(
+     *       BigDecimal.fromStringUnsafe("6"),
+     *       BigDecimal.fromStringUnsafe("4")
+     *     )
+     *   )
+     * ) // BigDecimal(1.5)
+     * console.log(
+     *   Option.isNone(
+     *     BigDecimal.divide(
+     *       BigDecimal.fromStringUnsafe("6"),
+     *       BigDecimal.fromStringUnsafe("0")
+     *     )
+     *   )
+     * ) // true
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): Option.Option<BigDecimal>;
 };
 /**
  * Provides an unsafe division operation on `BigDecimal`s.
  *
- * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
- * which represents the integer division rounded down to the nearest integer.
+ * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+ * with up to the default division precision.
  *
  * Throws a `RangeError` if the divisor is `0`.
  *
- * @example
+ * **Example** (Dividing decimals unsafely)
+ *
  * ```ts
  * import { divideUnsafe, fromStringUnsafe } from "effect/BigDecimal"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(
- *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3")),
- *   fromStringUnsafe("2")
- * )
- * assert.deepStrictEqual(
- *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4")),
- *   fromStringUnsafe("1.5")
- * )
+ * console.log(divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3"))) // BigDecimal(2)
+ * console.log(divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4"))) // BigDecimal(1.5)
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const divideUnsafe: {
     /**
      * Provides an unsafe division operation on `BigDecimal`s.
      *
-     * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
-     * which represents the integer division rounded down to the nearest integer.
+     * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+     * with up to the default division precision.
      *
      * Throws a `RangeError` if the divisor is `0`.
      *
-     * @example
+     * **Example** (Dividing decimals unsafely)
+     *
      * ```ts
      * import { divideUnsafe, fromStringUnsafe } from "effect/BigDecimal"
-     * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(
-     *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3")),
-     *   fromStringUnsafe("2")
-     * )
-     * assert.deepStrictEqual(
-     *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4")),
-     *   fromStringUnsafe("1.5")
-     * )
+     * console.log(divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3"))) // BigDecimal(2)
+     * console.log(divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4"))) // BigDecimal(1.5)
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => BigDecimal;
     /**
      * Provides an unsafe division operation on `BigDecimal`s.
      *
-     * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
-     * which represents the integer division rounded down to the nearest integer.
+     * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+     * with up to the default division precision.
      *
      * Throws a `RangeError` if the divisor is `0`.
      *
-     * @example
+     * **Example** (Dividing decimals unsafely)
+     *
      * ```ts
      * import { divideUnsafe, fromStringUnsafe } from "effect/BigDecimal"
-     * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(
-     *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3")),
-     *   fromStringUnsafe("2")
-     * )
-     * assert.deepStrictEqual(
-     *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4")),
-     *   fromStringUnsafe("1.5")
-     * )
+     * console.log(divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3"))) // BigDecimal(2)
+     * console.log(divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4"))) // BigDecimal(1.5)
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): BigDecimal;
 };
 /**
  * Provides an `Order` instance for `BigDecimal` that allows comparing and sorting BigDecimal values.
  *
- * @example
+ * **Example** (Comparing decimals)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -597,14 +610,15 @@ export declare const divideUnsafe: {
  * console.log(BigDecimal.Order(a, c)) // 0 (a === c)
  * ```
  *
- * @since 2.0.0
  * @category instances
+ * @since 2.0.0
  */
 export declare const Order: order.Order<BigDecimal>;
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
- * @example
+ * **Example** (Checking less-than comparisons)
+ *
  * ```ts
  * import { fromStringUnsafe, isLessThan } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -623,14 +637,15 @@ export declare const Order: order.Order<BigDecimal>;
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isLessThan: {
     /**
      * Returns `true` if the first argument is less than the second, otherwise `false`.
      *
-     * @example
+     * **Example** (Checking less-than comparisons)
+     *
      * ```ts
      * import { fromStringUnsafe, isLessThan } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -649,14 +664,15 @@ export declare const isLessThan: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => boolean;
     /**
      * Returns `true` if the first argument is less than the second, otherwise `false`.
      *
-     * @example
+     * **Example** (Checking less-than comparisons)
+     *
      * ```ts
      * import { fromStringUnsafe, isLessThan } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -675,15 +691,16 @@ export declare const isLessThan: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): boolean;
 };
 /**
  * Checks if a given `BigDecimal` is less than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking less-than-or-equal comparisons)
+ *
  * ```ts
  * import { fromStringUnsafe, isLessThanOrEqualTo } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -702,14 +719,15 @@ export declare const isLessThan: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isLessThanOrEqualTo: {
     /**
      * Checks if a given `BigDecimal` is less than or equal to the provided one.
      *
-     * @example
+     * **Example** (Checking less-than-or-equal comparisons)
+     *
      * ```ts
      * import { fromStringUnsafe, isLessThanOrEqualTo } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -728,14 +746,15 @@ export declare const isLessThanOrEqualTo: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => boolean;
     /**
      * Checks if a given `BigDecimal` is less than or equal to the provided one.
      *
-     * @example
+     * **Example** (Checking less-than-or-equal comparisons)
+     *
      * ```ts
      * import { fromStringUnsafe, isLessThanOrEqualTo } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -754,15 +773,16 @@ export declare const isLessThanOrEqualTo: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): boolean;
 };
 /**
  * Returns `true` if the first argument is greater than the second, otherwise `false`.
  *
- * @example
+ * **Example** (Checking greater-than comparisons)
+ *
  * ```ts
  * import { fromStringUnsafe, isGreaterThan } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -781,14 +801,15 @@ export declare const isLessThanOrEqualTo: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isGreaterThan: {
     /**
      * Returns `true` if the first argument is greater than the second, otherwise `false`.
      *
-     * @example
+     * **Example** (Checking greater-than comparisons)
+     *
      * ```ts
      * import { fromStringUnsafe, isGreaterThan } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -807,14 +828,15 @@ export declare const isGreaterThan: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => boolean;
     /**
      * Returns `true` if the first argument is greater than the second, otherwise `false`.
      *
-     * @example
+     * **Example** (Checking greater-than comparisons)
+     *
      * ```ts
      * import { fromStringUnsafe, isGreaterThan } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -833,15 +855,16 @@ export declare const isGreaterThan: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): boolean;
 };
 /**
  * Checks if a given `BigDecimal` is greater than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking greater-than-or-equal comparisons)
+ *
  * ```ts
  * import { fromStringUnsafe, isGreaterThanOrEqualTo } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -860,14 +883,15 @@ export declare const isGreaterThan: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isGreaterThanOrEqualTo: {
     /**
      * Checks if a given `BigDecimal` is greater than or equal to the provided one.
      *
-     * @example
+     * **Example** (Checking greater-than-or-equal comparisons)
+     *
      * ```ts
      * import { fromStringUnsafe, isGreaterThanOrEqualTo } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -886,14 +910,15 @@ export declare const isGreaterThanOrEqualTo: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => boolean;
     /**
      * Checks if a given `BigDecimal` is greater than or equal to the provided one.
      *
-     * @example
+     * **Example** (Checking greater-than-or-equal comparisons)
+     *
      * ```ts
      * import { fromStringUnsafe, isGreaterThanOrEqualTo } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -912,15 +937,16 @@ export declare const isGreaterThanOrEqualTo: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): boolean;
 };
 /**
  * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
  *
- * @example
+ * **Example** (Checking decimal ranges)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
@@ -935,14 +961,15 @@ export declare const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const between: {
     /**
      * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
      *
-     * @example
+     * **Example** (Checking decimal ranges)
+     *
      * ```ts
      * import { BigDecimal } from "effect"
      * import * as assert from "node:assert"
@@ -957,8 +984,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (options: {
         minimum: BigDecimal;
@@ -967,7 +994,8 @@ export declare const between: {
     /**
      * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
      *
-     * @example
+     * **Example** (Checking decimal ranges)
+     *
      * ```ts
      * import { BigDecimal } from "effect"
      * import * as assert from "node:assert"
@@ -982,8 +1010,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: BigDecimal, options: {
         minimum: BigDecimal;
@@ -997,7 +1025,8 @@ export declare const between: {
  * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
  * - Otherwise, it returns the original `BigDecimal`.
  *
- * @example
+ * **Example** (Clamping decimals to a range)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
@@ -1021,8 +1050,8 @@ export declare const between: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const clamp: {
     /**
@@ -1032,7 +1061,8 @@ export declare const clamp: {
      * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
      * - Otherwise, it returns the original `BigDecimal`.
      *
-     * @example
+     * **Example** (Clamping decimals to a range)
+     *
      * ```ts
      * import { BigDecimal } from "effect"
      * import * as assert from "node:assert"
@@ -1056,8 +1086,8 @@ export declare const clamp: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (options: {
         minimum: BigDecimal;
@@ -1070,7 +1100,8 @@ export declare const clamp: {
      * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
      * - Otherwise, it returns the original `BigDecimal`.
      *
-     * @example
+     * **Example** (Clamping decimals to a range)
+     *
      * ```ts
      * import { BigDecimal } from "effect"
      * import * as assert from "node:assert"
@@ -1094,8 +1125,8 @@ export declare const clamp: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, options: {
         minimum: BigDecimal;
@@ -1105,7 +1136,8 @@ export declare const clamp: {
 /**
  * Returns the minimum between two `BigDecimal`s.
  *
- * @example
+ * **Example** (Selecting the smaller decimal)
+ *
  * ```ts
  * import { fromStringUnsafe, min } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1116,14 +1148,15 @@ export declare const clamp: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const min: {
     /**
      * Returns the minimum between two `BigDecimal`s.
      *
-     * @example
+     * **Example** (Selecting the smaller decimal)
+     *
      * ```ts
      * import { fromStringUnsafe, min } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1134,14 +1167,15 @@ export declare const min: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => BigDecimal;
     /**
      * Returns the minimum between two `BigDecimal`s.
      *
-     * @example
+     * **Example** (Selecting the smaller decimal)
+     *
      * ```ts
      * import { fromStringUnsafe, min } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1152,15 +1186,16 @@ export declare const min: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): BigDecimal;
 };
 /**
  * Returns the maximum between two `BigDecimal`s.
  *
- * @example
+ * **Example** (Selecting the larger decimal)
+ *
  * ```ts
  * import { fromStringUnsafe, max } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1171,14 +1206,15 @@ export declare const min: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const max: {
     /**
      * Returns the maximum between two `BigDecimal`s.
      *
-     * @example
+     * **Example** (Selecting the larger decimal)
+     *
      * ```ts
      * import { fromStringUnsafe, max } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1189,14 +1225,15 @@ export declare const max: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => BigDecimal;
     /**
      * Returns the maximum between two `BigDecimal`s.
      *
-     * @example
+     * **Example** (Selecting the larger decimal)
+     *
      * ```ts
      * import { fromStringUnsafe, max } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1207,15 +1244,16 @@ export declare const max: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): BigDecimal;
 };
 /**
  * Determines the sign of a given `BigDecimal`.
  *
- * @example
+ * **Example** (Reading decimal signs)
+ *
  * ```ts
  * import { fromStringUnsafe, sign } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1225,14 +1263,15 @@ export declare const max: {
  * assert.deepStrictEqual(sign(fromStringUnsafe("5")), 1)
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const sign: (n: BigDecimal) => Ordering;
 /**
  * Determines the absolute value of a given `BigDecimal`.
  *
- * @example
+ * **Example** (Calculating absolute values)
+ *
  * ```ts
  * import { abs, fromStringUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1242,14 +1281,15 @@ export declare const sign: (n: BigDecimal) => Ordering;
  * assert.deepStrictEqual(abs(fromStringUnsafe("5")), fromStringUnsafe("5"))
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const abs: (n: BigDecimal) => BigDecimal;
 /**
  * Provides a negate operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Negating decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, negate } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1258,8 +1298,8 @@ export declare const abs: (n: BigDecimal) => BigDecimal;
  * assert.deepStrictEqual(negate(fromStringUnsafe("-6")), fromStringUnsafe("6"))
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const negate: (n: BigDecimal) => BigDecimal;
 /**
@@ -1267,7 +1307,8 @@ export declare const negate: (n: BigDecimal) => BigDecimal;
  *
  * If the divisor is `0`, the result will be `Option.none()`.
  *
- * @example
+ * **Example** (Computing remainders safely)
+ *
  * ```ts
  * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
@@ -1295,8 +1336,8 @@ export declare const negate: (n: BigDecimal) => BigDecimal;
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const remainder: {
     /**
@@ -1304,7 +1345,8 @@ export declare const remainder: {
      *
      * If the divisor is `0`, the result will be `Option.none()`.
      *
-     * @example
+     * **Example** (Computing remainders safely)
+     *
      * ```ts
      * import { BigDecimal, Option } from "effect"
      * import * as assert from "node:assert"
@@ -1332,8 +1374,8 @@ export declare const remainder: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>;
     /**
@@ -1341,7 +1383,8 @@ export declare const remainder: {
      *
      * If the divisor is `0`, the result will be `Option.none()`.
      *
-     * @example
+     * **Example** (Computing remainders safely)
+     *
      * ```ts
      * import { BigDecimal, Option } from "effect"
      * import * as assert from "node:assert"
@@ -1369,8 +1412,8 @@ export declare const remainder: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal>;
 };
@@ -1379,7 +1422,8 @@ export declare const remainder: {
  *
  * Throws a `RangeError` if the divisor is `0`.
  *
- * @example
+ * **Example** (Computing remainders unsafely)
+ *
  * ```ts
  * import { fromStringUnsafe, remainderUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1398,8 +1442,8 @@ export declare const remainder: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const remainderUnsafe: {
     /**
@@ -1407,7 +1451,8 @@ export declare const remainderUnsafe: {
      *
      * Throws a `RangeError` if the divisor is `0`.
      *
-     * @example
+     * **Example** (Computing remainders unsafely)
+     *
      * ```ts
      * import { fromStringUnsafe, remainderUnsafe } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1426,8 +1471,8 @@ export declare const remainderUnsafe: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (divisor: BigDecimal): (self: BigDecimal) => BigDecimal;
     /**
@@ -1435,7 +1480,8 @@ export declare const remainderUnsafe: {
      *
      * Throws a `RangeError` if the divisor is `0`.
      *
-     * @example
+     * **Example** (Computing remainders unsafely)
+     *
      * ```ts
      * import { fromStringUnsafe, remainderUnsafe } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1454,21 +1500,22 @@ export declare const remainderUnsafe: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, divisor: BigDecimal): BigDecimal;
 };
 /**
  * Provides an `Equivalence` instance for `BigDecimal` that determines equality between BigDecimal values.
  *
- * @example
+ * **Example** (Checking decimal equivalence)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
- * const a = BigDecimal.fromNumberUnsafe(1.50)
- * const b = BigDecimal.fromNumberUnsafe(1.5)
- * const c = BigDecimal.fromNumberUnsafe(2.0)
+ * const a = BigDecimal.fromStringUnsafe("1.50")
+ * const b = BigDecimal.fromStringUnsafe("1.5")
+ * const c = BigDecimal.fromStringUnsafe("2.0")
  *
  * console.log(BigDecimal.Equivalence(a, b)) // true (1.50 === 1.5)
  * console.log(BigDecimal.Equivalence(a, c)) // false (1.50 !== 2.0)
@@ -1481,65 +1528,69 @@ export declare const Equivalence: Equ.Equivalence<BigDecimal>;
 /**
  * Checks if two `BigDecimal`s are equal.
  *
- * @example
+ * **Example** (Checking decimal equality)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
- * const a = BigDecimal.fromNumberUnsafe(1.5)
- * const b = BigDecimal.fromNumberUnsafe(1.50)
- * const c = BigDecimal.fromNumberUnsafe(2.0)
+ * const a = BigDecimal.fromStringUnsafe("1.5")
+ * const b = BigDecimal.fromStringUnsafe("1.50")
+ * const c = BigDecimal.fromStringUnsafe("2.0")
  *
  * console.log(BigDecimal.equals(a, b)) // true
  * console.log(BigDecimal.equals(a, c)) // false
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const equals: {
     /**
      * Checks if two `BigDecimal`s are equal.
      *
-     * @example
+     * **Example** (Checking decimal equality)
+     *
      * ```ts
      * import { BigDecimal } from "effect"
      *
-     * const a = BigDecimal.fromNumberUnsafe(1.5)
-     * const b = BigDecimal.fromNumberUnsafe(1.50)
-     * const c = BigDecimal.fromNumberUnsafe(2.0)
+     * const a = BigDecimal.fromStringUnsafe("1.5")
+     * const b = BigDecimal.fromStringUnsafe("1.50")
+     * const c = BigDecimal.fromStringUnsafe("2.0")
      *
      * console.log(BigDecimal.equals(a, b)) // true
      * console.log(BigDecimal.equals(a, c)) // false
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: BigDecimal): (self: BigDecimal) => boolean;
     /**
      * Checks if two `BigDecimal`s are equal.
      *
-     * @example
+     * **Example** (Checking decimal equality)
+     *
      * ```ts
      * import { BigDecimal } from "effect"
      *
-     * const a = BigDecimal.fromNumberUnsafe(1.5)
-     * const b = BigDecimal.fromNumberUnsafe(1.50)
-     * const c = BigDecimal.fromNumberUnsafe(2.0)
+     * const a = BigDecimal.fromStringUnsafe("1.5")
+     * const b = BigDecimal.fromStringUnsafe("1.50")
+     * const c = BigDecimal.fromStringUnsafe("2.0")
      *
      * console.log(BigDecimal.equals(a, b)) // true
      * console.log(BigDecimal.equals(a, c)) // false
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: BigDecimal, that: BigDecimal): boolean;
 };
 /**
  * Creates a `BigDecimal` from a `bigint` value.
  *
- * @example
+ * **Example** (Creating decimals from bigint)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -1550,8 +1601,8 @@ export declare const equals: {
  * console.log(BigDecimal.format(largeBigInt)) // "9007199254740991"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromBigInt: (n: bigint) => BigDecimal;
 /**
@@ -1562,7 +1613,8 @@ export declare const fromBigInt: (n: bigint) => BigDecimal;
  *
  * Throws a `RangeError` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
  *
- * @example
+ * **Example** (Creating decimals from finite numbers)
+ *
  * ```ts
  * import { fromNumberUnsafe, make } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1571,8 +1623,8 @@ export declare const fromBigInt: (n: bigint) => BigDecimal;
  * assert.deepStrictEqual(fromNumberUnsafe(123.456), make(123456n, 3))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromNumberUnsafe: (n: number) => BigDecimal;
 /**
@@ -1583,7 +1635,8 @@ export declare const fromNumberUnsafe: (n: number) => BigDecimal;
  *
  * Returns `Option.none()` for `NaN`, `+Infinity` or `-Infinity`.
  *
- * @example
+ * **Example** (Creating decimals from numbers safely)
+ *
  * ```ts
  * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
@@ -1596,14 +1649,19 @@ export declare const fromNumberUnsafe: (n: number) => BigDecimal;
  * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), Option.none())
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromNumber: (n: number) => Option.Option<BigDecimal>;
 /**
- * Parses a numerical `string` into a `BigDecimal`.
+ * Safely parses a decimal string into a `BigDecimal`.
+ *
+ * Returns `Option.some` for valid decimal or exponent notation and
+ * `Option.none` when the string cannot be parsed or would produce an unsafe
+ * scale. The empty string parses as zero.
+ *
+ * **Example** (Parsing decimal strings safely)
  *
- * @example
  * ```ts
  * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
@@ -1616,14 +1674,19 @@ export declare const fromNumber: (n: number) => Option.Option<BigDecimal>;
  * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromString: (s: string) => Option.Option<BigDecimal>;
 /**
- * Parses a numerical `string` into a `BigDecimal`.
+ * Parses a decimal string into a `BigDecimal`, throwing if the string is
+ * invalid.
+ *
+ * Accepts the same syntax as `fromString`. Use `fromString` when invalid input
+ * should be represented as `Option.none` instead of throwing.
+ *
+ * **Example** (Parsing decimal strings unsafely)
  *
- * @example
  * ```ts
  * import { fromStringUnsafe, make } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1633,17 +1696,19 @@ export declare const fromString: (s: string) => Option.Option<BigDecimal>;
  * assert.throws(() => fromStringUnsafe("123.abc"))
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromStringUnsafe: (s: string) => BigDecimal;
 /**
- * Formats a given `BigDecimal` as a `string`.
+ * Formats a `BigDecimal` as a string.
+ *
+ * The value is normalized before formatting. Scientific notation is used when
+ * the absolute value of the normalized scale is at least `16`; otherwise plain
+ * decimal notation is used.
  *
- * If the scale of the `BigDecimal` is greater than or equal to 16, the `BigDecimal` will
- * be formatted in scientific notation.
+ * **Example** (Formatting decimals)
  *
- * @example
  * ```ts
  * import { format, fromStringUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1653,14 +1718,15 @@ export declare const fromStringUnsafe: (s: string) => BigDecimal;
  * assert.deepStrictEqual(format(fromStringUnsafe("-0.00000123")), "-0.00000123")
  * ```
  *
- * @since 2.0.0
  * @category conversions
+ * @since 2.0.0
  */
 export declare const format: (n: BigDecimal) => string;
 /**
  * Formats a given `BigDecimal` as a `string` in scientific notation.
  *
- * @example
+ * **Example** (Formatting decimals exponentially)
+ *
  * ```ts
  * import { make, toExponential } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1668,16 +1734,19 @@ export declare const format: (n: BigDecimal) => string;
  * assert.deepStrictEqual(toExponential(make(123456n, -5)), "1.23456e+10")
  * ```
  *
- * @since 4.0.0
  * @category conversions
+ * @since 4.0.0
  */
 export declare const toExponential: (n: BigDecimal) => string;
 /**
- * Converts a `BigDecimal` to a `number`.
+ * Converts a `BigDecimal` to a JavaScript `number`.
+ *
+ * This conversion is unsafe because the result can lose integer or fractional
+ * precision, round to a nearby representable value, or become `Infinity` when
+ * the decimal cannot be represented as a finite JavaScript `number`.
  *
- * This function will produce incorrect results if the `BigDecimal` exceeds the 64-bit range of a `number`.
+ * **Example** (Converting decimals to numbers)
  *
- * @example
  * ```ts
  * import { fromStringUnsafe, toNumberUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1685,14 +1754,15 @@ export declare const toExponential: (n: BigDecimal) => string;
  * assert.deepStrictEqual(toNumberUnsafe(fromStringUnsafe("123.456")), 123.456)
  * ```
  *
- * @since 2.0.0
  * @category conversions
+ * @since 2.0.0
  */
 export declare const toNumberUnsafe: (n: BigDecimal) => number;
 /**
  * Checks if a given `BigDecimal` is an integer.
  *
- * @example
+ * **Example** (Checking integer decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, isInteger } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1702,14 +1772,15 @@ export declare const toNumberUnsafe: (n: BigDecimal) => number;
  * assert.deepStrictEqual(isInteger(fromStringUnsafe("1.1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isInteger: (n: BigDecimal) => boolean;
 /**
  * Checks if a given `BigDecimal` is `0`.
  *
- * @example
+ * **Example** (Checking zero decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, isZero } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1718,14 +1789,15 @@ export declare const isInteger: (n: BigDecimal) => boolean;
  * assert.deepStrictEqual(isZero(fromStringUnsafe("1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isZero: (n: BigDecimal) => boolean;
 /**
  * Checks if a given `BigDecimal` is negative.
  *
- * @example
+ * **Example** (Checking negative decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, isNegative } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1735,14 +1807,15 @@ export declare const isZero: (n: BigDecimal) => boolean;
  * assert.deepStrictEqual(isNegative(fromStringUnsafe("1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isNegative: (n: BigDecimal) => boolean;
 /**
  * Checks if a given `BigDecimal` is positive.
  *
- * @example
+ * **Example** (Checking positive decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, isPositive } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1752,8 +1825,8 @@ export declare const isNegative: (n: BigDecimal) => boolean;
  * assert.deepStrictEqual(isPositive(fromStringUnsafe("1")), true)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isPositive: (n: BigDecimal) => boolean;
 /**
@@ -1770,14 +1843,15 @@ 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
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.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.
  *
- * @example
+ * **Example** (Rounding decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, round } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1792,14 +1866,15 @@ export type RoundingMode = "ceil" | "floor" | "to-zero" | "from-zero" | "half-ce
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const round: {
     /**
      * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
      *
-     * @example
+     * **Example** (Rounding decimals)
+     *
      * ```ts
      * import { fromStringUnsafe, round } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1814,8 +1889,8 @@ export declare const round: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (options: {
         scale?: number;
@@ -1824,7 +1899,8 @@ export declare const round: {
     /**
      * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
      *
-     * @example
+     * **Example** (Rounding decimals)
+     *
      * ```ts
      * import { fromStringUnsafe, round } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1839,8 +1915,8 @@ export declare const round: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (n: BigDecimal, options?: {
         scale?: number;
@@ -1848,76 +1924,62 @@ export declare const round: {
     }): BigDecimal;
 };
 /**
- * Truncate a `BigDecimal` at the given scale. This is the same operation as rounding away from zero.
+ * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+ * rounding toward zero.
+ *
+ * **Example** (Truncating decimals)
  *
- * @example
  * ```ts
  * import { fromStringUnsafe, truncate } from "effect/BigDecimal"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(
- *   truncate(fromStringUnsafe("145"), -1),
- *   fromStringUnsafe("140")
- * )
- * assert.deepStrictEqual(
- *   truncate(fromStringUnsafe("-14.5")),
- *   fromStringUnsafe("-14")
- * )
+ * console.log(truncate(fromStringUnsafe("145"), -1)) // BigDecimal(140)
+ * console.log(truncate(fromStringUnsafe("-14.5"))) // BigDecimal(-14)
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const truncate: {
     /**
-     * Truncate a `BigDecimal` at the given scale. This is the same operation as rounding away from zero.
+     * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+     * rounding toward zero.
+     *
+     * **Example** (Truncating decimals)
      *
-     * @example
      * ```ts
      * import { fromStringUnsafe, truncate } from "effect/BigDecimal"
-     * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(
-     *   truncate(fromStringUnsafe("145"), -1),
-     *   fromStringUnsafe("140")
-     * )
-     * assert.deepStrictEqual(
-     *   truncate(fromStringUnsafe("-14.5")),
-     *   fromStringUnsafe("-14")
-     * )
+     * console.log(truncate(fromStringUnsafe("145"), -1)) // BigDecimal(140)
+     * console.log(truncate(fromStringUnsafe("-14.5"))) // BigDecimal(-14)
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (scale: number): (self: BigDecimal) => BigDecimal;
     /**
-     * Truncate a `BigDecimal` at the given scale. This is the same operation as rounding away from zero.
+     * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+     * rounding toward zero.
+     *
+     * **Example** (Truncating decimals)
      *
-     * @example
      * ```ts
      * import { fromStringUnsafe, truncate } from "effect/BigDecimal"
-     * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(
-     *   truncate(fromStringUnsafe("145"), -1),
-     *   fromStringUnsafe("140")
-     * )
-     * assert.deepStrictEqual(
-     *   truncate(fromStringUnsafe("-14.5")),
-     *   fromStringUnsafe("-14")
-     * )
+     * console.log(truncate(fromStringUnsafe("145"), -1)) // BigDecimal(140)
+     * console.log(truncate(fromStringUnsafe("-14.5"))) // BigDecimal(-14)
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (self: BigDecimal, scale?: number): BigDecimal;
 };
 /**
  * Calculate the ceiling of a `BigDecimal` at the given scale.
  *
- * @example
+ * **Example** (Rounding decimals up)
+ *
  * ```ts
  * import { ceil, fromStringUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1929,14 +1991,15 @@ export declare const truncate: {
  * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const ceil: {
     /**
      * Calculate the ceiling of a `BigDecimal` at the given scale.
      *
-     * @example
+     * **Example** (Rounding decimals up)
+     *
      * ```ts
      * import { ceil, fromStringUnsafe } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1948,14 +2011,15 @@ export declare const ceil: {
      * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (scale: number): (self: BigDecimal) => BigDecimal;
     /**
      * Calculate the ceiling of a `BigDecimal` at the given scale.
      *
-     * @example
+     * **Example** (Rounding decimals up)
+     *
      * ```ts
      * import { ceil, fromStringUnsafe } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -1967,15 +2031,16 @@ export declare const ceil: {
      * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (self: BigDecimal, scale?: number): BigDecimal;
 };
 /**
  * Calculate the floor of a `BigDecimal` at the given scale.
  *
- * @example
+ * **Example** (Rounding decimals down)
+ *
  * ```ts
  * import { floor, fromStringUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1990,14 +2055,15 @@ export declare const ceil: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const floor: {
     /**
      * Calculate the floor of a `BigDecimal` at the given scale.
      *
-     * @example
+     * **Example** (Rounding decimals down)
+     *
      * ```ts
      * import { floor, fromStringUnsafe } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -2012,14 +2078,15 @@ export declare const floor: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (scale: number): (self: BigDecimal) => BigDecimal;
     /**
      * Calculate the floor of a `BigDecimal` at the given scale.
      *
-     * @example
+     * **Example** (Rounding decimals down)
+     *
      * ```ts
      * import { floor, fromStringUnsafe } from "effect/BigDecimal"
      * import * as assert from "node:assert"
@@ -2034,8 +2101,8 @@ export declare const floor: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (self: BigDecimal, scale?: number): BigDecimal;
 };