effect 4.0.0 → 4.0.2

package/src/BigDecimal.ts

@@ -5,6 +5,7 @@
  * divide, round, and format decimal values such as money, quantities, and
  * measurements.
  *
+ * @stability stable
  * @since 2.0.0
  */
 
@@ -43,6 +44,7 @@ const TypeId = "~effect/BigDecimal"
  * d.scale // => 2
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -100,6 +102,7 @@ const BigDecimalProto: Omit<BigDecimal, "value" | "scale" | "normalized"> = {
  * BigDecimal.isBigDecimal("123.45") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -133,6 +136,7 @@ export const isBigDecimal = (u: unknown): u is BigDecimal => hasProperty(u, Type
  *
  * @see {@link fromBigInt} for constructing an integer decimal from a `bigint`
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -197,6 +201,7 @@ const one = makeNormalizedUnsafe(bigint1, 0)
  *
  * @see {@link format} for rendering normalized decimals as strings
  *
+ * @stability stable
  * @category scaling
  * @since 2.0.0
  */
@@ -246,6 +251,7 @@ export const normalize = (self: BigDecimal): BigDecimal => {
  *
  * @see {@link round} for changing scale with configurable rounding
  *
+ * @stability stable
  * @category scaling
  * @since 2.0.0
  */
@@ -281,6 +287,7 @@ export const scale: {
    *
    * @see {@link round} for changing scale with configurable rounding
    *
+   * @stability stable
    * @category scaling
    * @since 2.0.0
    */
@@ -316,6 +323,7 @@ export const scale: {
    *
    * @see {@link round} for changing scale with configurable rounding
    *
+   * @stability stable
    * @category scaling
    * @since 2.0.0
    */
@@ -353,6 +361,7 @@ export const scale: {
  *
  * @see {@link sumAll} for summing an iterable of `BigDecimal` values
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -378,6 +387,7 @@ export const sum: {
    *
    * @see {@link sumAll} for summing an iterable of `BigDecimal` values
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -403,6 +413,7 @@ export const sum: {
    *
    * @see {@link sumAll} for summing an iterable of `BigDecimal` values
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -449,6 +460,7 @@ export const sum: {
  *
  * @see {@link sum} for adding two `BigDecimal` values
  *
+ * @stability stable
  * @category math
  * @since 3.16.0
  */
@@ -480,6 +492,7 @@ export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
  *
  * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -504,6 +517,7 @@ export const multiply: {
    *
    * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -528,6 +542,7 @@ export const multiply: {
    *
    * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -561,6 +576,7 @@ export const multiply: {
  *
  * @see {@link multiply} for multiplying two `BigDecimal` values
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */
@@ -593,6 +609,7 @@ export const multiplyAll = (collection: Iterable<BigDecimal>): BigDecimal => {
  * ) // => BigDecimal.fromBigInt(-1n)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -615,6 +632,7 @@ export const subtract: {
    * ) // => BigDecimal.fromBigInt(-1n)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -637,6 +655,7 @@ export const subtract: {
    * ) // => BigDecimal.fromBigInt(-1n)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -758,6 +777,7 @@ export const roundTerminal = (n: bigint): bigint => {
  * @see {@link divideUnsafe} for division that throws when the divisor is zero
  * @see {@link remainder} for the decimal remainder operation
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -791,6 +811,7 @@ export const divide: {
    * @see {@link divideUnsafe} for division that throws when the divisor is zero
    * @see {@link remainder} for the decimal remainder operation
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -824,6 +845,7 @@ export const divide: {
    * @see {@link divideUnsafe} for division that throws when the divisor is zero
    * @see {@link remainder} for the decimal remainder operation
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -873,6 +895,7 @@ export const divide: {
  *
  * @see {@link divide} for division that returns `Option.none` when the divisor is zero
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */
@@ -905,6 +928,7 @@ export const divideUnsafe: {
    *
    * @see {@link divide} for division that returns `Option.none` when the divisor is zero
    *
+   * @stability stable
    * @category math
    * @since 4.0.0
    */
@@ -937,6 +961,7 @@ export const divideUnsafe: {
    *
    * @see {@link divide} for division that returns `Option.none` when the divisor is zero
    *
+   * @stability stable
    * @category math
    * @since 4.0.0
    */
@@ -1014,6 +1039,7 @@ const compare = (self: BigDecimal, that: BigDecimal): Ordering => {
  * BigDecimal.Order(a, c) // => 0
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 2.0.0
  */
@@ -1040,6 +1066,7 @@ export const Order: order.Order<BigDecimal> = order.make(compare)
  * BigDecimal.isLessThan(four, three) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -1065,6 +1092,7 @@ export const isLessThan: {
    * BigDecimal.isLessThan(four, three) // => false
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -1090,6 +1118,7 @@ export const isLessThan: {
    * BigDecimal.isLessThan(four, three) // => false
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -1117,6 +1146,7 @@ export const isLessThan: {
  * BigDecimal.isLessThanOrEqualTo(four, three) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -1142,6 +1172,7 @@ export const isLessThanOrEqualTo: {
    * BigDecimal.isLessThanOrEqualTo(four, three) // => false
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -1167,6 +1198,7 @@ export const isLessThanOrEqualTo: {
    * BigDecimal.isLessThanOrEqualTo(four, three) // => false
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -1194,6 +1226,7 @@ export const isLessThanOrEqualTo: {
  * BigDecimal.isGreaterThan(four, three) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -1219,6 +1252,7 @@ export const isGreaterThan: {
    * BigDecimal.isGreaterThan(four, three) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -1244,6 +1278,7 @@ export const isGreaterThan: {
    * BigDecimal.isGreaterThan(four, three) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -1271,6 +1306,7 @@ export const isGreaterThan: {
  * BigDecimal.isGreaterThanOrEqualTo(four, three) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -1296,6 +1332,7 @@ export const isGreaterThanOrEqualTo: {
    * BigDecimal.isGreaterThanOrEqualTo(four, three) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -1321,6 +1358,7 @@ export const isGreaterThanOrEqualTo: {
    * BigDecimal.isGreaterThanOrEqualTo(four, three) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -1351,6 +1389,7 @@ export const isGreaterThanOrEqualTo: {
  *
  * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -1379,6 +1418,7 @@ export const between: {
    *
    * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -1412,6 +1452,7 @@ export const between: {
    *
    * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -1454,6 +1495,7 @@ export const between: {
  *
  * @see {@link between} for checking whether a `BigDecimal` is already inside a range
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1488,6 +1530,7 @@ export const clamp: {
    *
    * @see {@link between} for checking whether a `BigDecimal` is already inside a range
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1527,6 +1570,7 @@ export const clamp: {
    *
    * @see {@link between} for checking whether a `BigDecimal` is already inside a range
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1559,6 +1603,7 @@ export const clamp: {
  *
  * @see {@link max} for selecting the larger value
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1583,6 +1628,7 @@ export const min: {
    *
    * @see {@link max} for selecting the larger value
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1607,6 +1653,7 @@ export const min: {
    *
    * @see {@link max} for selecting the larger value
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1633,6 +1680,7 @@ export const min: {
  *
  * @see {@link min} for selecting the smaller value
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1657,6 +1705,7 @@ export const max: {
    *
    * @see {@link min} for selecting the smaller value
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1681,6 +1730,7 @@ export const max: {
    *
    * @see {@link min} for selecting the smaller value
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1704,6 +1754,7 @@ export const max: {
  * BigDecimal.sign(BigDecimal.fromStringUnsafe("5")) // => 1
  * ```
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1726,6 +1777,7 @@ export const sign = (n: BigDecimal): Ordering => n.value === bigint0 ? 0 : n.val
  * BigDecimal.abs(BigDecimal.fromStringUnsafe("5")) // => BigDecimal.fromBigInt(5n)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1747,6 +1799,7 @@ export const abs = (n: BigDecimal): BigDecimal => n.value < bigint0 ? make(-n.va
  * BigDecimal.negate(BigDecimal.fromStringUnsafe("-6")) // => BigDecimal.fromBigInt(6n)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1781,6 +1834,7 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
  * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
  * @see {@link divide} for decimal quotient calculation
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1814,6 +1868,7 @@ export const remainder: {
    * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
    * @see {@link divide} for decimal quotient calculation
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1847,6 +1902,7 @@ export const remainder: {
    * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
    * @see {@link divide} for decimal quotient calculation
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1886,6 +1942,7 @@ export const remainder: {
  *
  * @see {@link remainder} for returning `Option.none` when the divisor is zero
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */
@@ -1916,6 +1973,7 @@ export const remainderUnsafe: {
    *
    * @see {@link remainder} for returning `Option.none` when the divisor is zero
    *
+   * @stability stable
    * @category math
    * @since 4.0.0
    */
@@ -1946,6 +2004,7 @@ export const remainderUnsafe: {
    *
    * @see {@link remainder} for returning `Option.none` when the divisor is zero
    *
+   * @stability stable
    * @category math
    * @since 4.0.0
    */
@@ -1980,6 +2039,7 @@ export const remainderUnsafe: {
  * BigDecimal.Equivalence(a, c) // => false
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 2.0.0
  */
@@ -2007,6 +2067,7 @@ export const Equivalence: Equ.Equivalence<BigDecimal> = Equ.make((self, that) =>
  *
  * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -2033,6 +2094,7 @@ export const equals: {
    *
    * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -2059,6 +2121,7 @@ export const equals: {
    *
    * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -2086,6 +2149,7 @@ export const equals: {
  *
  * @see {@link make} for constructing a decimal with an explicit scale
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -2116,6 +2180,7 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
  *
  * @see {@link fromNumber} for returning `Option.none` when the number is not finite
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -2152,6 +2217,7 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
  * @see {@link fromNumberUnsafe} for throwing when the number is not finite
  * @see {@link fromString} for parsing decimal strings directly
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -2194,6 +2260,7 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
  * @see {@link fromStringUnsafe} for parsing that throws on invalid input
  * @see {@link fromNumber} for converting finite JavaScript numbers
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -2266,6 +2333,7 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  *
  * @see {@link fromString} for returning `Option.none` on invalid input
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -2298,6 +2366,7 @@ export const fromStringUnsafe = (s: string): BigDecimal => {
  *
  * @see {@link toExponential} for always rendering scientific notation
  *
+ * @stability stable
  * @category converting
  * @since 2.0.0
  */
@@ -2334,6 +2403,7 @@ export const format = (n: BigDecimal): string => {
  *
  * @see {@link format} for plain decimal formatting when possible
  *
+ * @stability stable
  * @category converting
  * @since 3.11.0
  */
@@ -2375,6 +2445,7 @@ export const toExponential = (n: BigDecimal): string => {
  *
  * @see {@link format} for preserving decimal precision as text
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -2397,6 +2468,7 @@ export const toNumberUnsafe = (n: BigDecimal): number => Number(format(n))
  * BigDecimal.isInteger(BigDecimal.fromStringUnsafe("1.1")) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -2418,6 +2490,7 @@ export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
  * BigDecimal.isZero(BigDecimal.fromStringUnsafe("1")) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -2440,6 +2513,7 @@ export const isZero = (n: BigDecimal): boolean => n.value === bigint0
  * BigDecimal.isNegative(BigDecimal.fromStringUnsafe("1")) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -2462,6 +2536,7 @@ export const isNegative = (n: BigDecimal): boolean => n.value < bigint0
  * BigDecimal.isPositive(BigDecimal.fromStringUnsafe("1")) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -2495,6 +2570,7 @@ const isBigDecimalArgs = (args: IArguments) => isBigDecimal(args[0])
  * @see {@link floor} for fixed rounding toward negative infinity
  * @see {@link truncate} for fixed rounding toward zero
  *
+ * @stability stable
  * @category math
  * @since 3.16.0
  */
@@ -2533,6 +2609,7 @@ export type RoundingMode =
  * @see {@link floor} for fixed rounding toward negative infinity
  * @see {@link truncate} for fixed rounding toward zero
  *
+ * @stability stable
  * @category math
  * @since 3.16.0
  */
@@ -2560,6 +2637,7 @@ export const round: {
    * @see {@link floor} for fixed rounding toward negative infinity
    * @see {@link truncate} for fixed rounding toward zero
    *
+   * @stability stable
    * @category math
    * @since 3.16.0
    */
@@ -2587,6 +2665,7 @@ export const round: {
    * @see {@link floor} for fixed rounding toward negative infinity
    * @see {@link truncate} for fixed rounding toward zero
    *
+   * @stability stable
    * @category math
    * @since 3.16.0
    */
@@ -2660,6 +2739,7 @@ export const round: {
  * @see {@link ceil} for rounding toward positive infinity
  * @see {@link floor} for rounding toward negative infinity
  *
+ * @stability stable
  * @category math
  * @since 3.16.0
  */
@@ -2686,6 +2766,7 @@ export const truncate: {
    * @see {@link ceil} for rounding toward positive infinity
    * @see {@link floor} for rounding toward negative infinity
    *
+   * @stability stable
    * @category math
    * @since 3.16.0
    */
@@ -2712,6 +2793,7 @@ export const truncate: {
    * @see {@link ceil} for rounding toward positive infinity
    * @see {@link floor} for rounding toward negative infinity
    *
+   * @stability stable
    * @category math
    * @since 3.16.0
    */
@@ -2751,6 +2833,7 @@ export const truncate: {
  * BigDecimal.ceil(BigDecimal.fromStringUnsafe("-14.5")) // => BigDecimal.fromBigInt(-14n)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 3.16.0
  */
@@ -2781,6 +2864,7 @@ export const ceil: {
    * BigDecimal.ceil(BigDecimal.fromStringUnsafe("-14.5")) // => BigDecimal.fromBigInt(-14n)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.16.0
    */
@@ -2811,6 +2895,7 @@ export const ceil: {
    * BigDecimal.ceil(BigDecimal.fromStringUnsafe("-14.5")) // => BigDecimal.fromBigInt(-14n)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.16.0
    */
@@ -2878,6 +2963,7 @@ export const digitAt: {
  * @see {@link truncate} for rounding toward zero
  * @see {@link round} for configurable rounding modes
  *
+ * @stability stable
  * @category math
  * @since 3.16.0
  */
@@ -2902,6 +2988,7 @@ export const floor: {
    * @see {@link truncate} for rounding toward zero
    * @see {@link round} for configurable rounding modes
    *
+   * @stability stable
    * @category math
    * @since 3.16.0
    */
@@ -2926,6 +3013,7 @@ export const floor: {
    * @see {@link truncate} for rounding toward zero
    * @see {@link round} for configurable rounding modes
    *
+   * @stability stable
    * @category math
    * @since 3.16.0
    */