BigDecimal

Creates a BigDecimal from a bigint value.

When to use

Use to construct an integer BigDecimal from a bigint.

See

• make for constructing a decimal with an explicit scale

declare function fromBigInt(n: bigint): BigDecimal

import { BigDecimal } from "effect"

const decimal = BigDecimal.fromBigInt(123n)
decimal // => BigDecimal.fromStringUnsafe("123")

const largeBigInt = BigDecimal.fromBigInt(9007199254740991n)
largeBigInt // => BigDecimal.fromStringUnsafe("9007199254740991")

Creates a BigDecimal safely from a finite number.

When to use

Use to convert a finite JavaScript number to a BigDecimal without throwing on invalid input.

Details

Returns Option.none() for NaN, +Infinity or -Infinity.

Gotchas

It is not recommended to convert a floating point number to a decimal directly, as the floating point representation may be unexpected.

See

• fromNumberUnsafe for throwing when the number is not finite
• fromString for parsing decimal strings directly

declare function fromNumber(n: number): Option<BigDecimal>

import { BigDecimal, Option } from "effect"

BigDecimal.fromNumber(123.456) // => Option.some(BigDecimal.fromStringUnsafe("123.456"))
BigDecimal.fromNumber(Infinity) // => Option.none()

Creates a BigDecimal from a finite number.

When to use

Use when you need to convert a trusted finite JavaScript number to a BigDecimal and want a plain result instead of an Option.

Gotchas

It is not recommended to convert a floating point number to a decimal directly, as the floating point representation may be unexpected. Throws a RangeError if the number is not finite (NaN, +Infinity or -Infinity).

See

• fromNumber for returning Option.none when the number is not finite

declare function fromNumberUnsafe(n: number): BigDecimal

import { BigDecimal } from "effect"

BigDecimal.fromNumberUnsafe(123) // => BigDecimal.fromBigInt(123n)
BigDecimal.fromNumberUnsafe(123.456) // => BigDecimal.fromStringUnsafe("123.456")

Parses a decimal string into a BigDecimal safely.

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 Option.none when the string cannot be parsed or would produce an unsafe scale. The empty string parses as zero.

See

• fromStringUnsafe for parsing that throws on invalid input
• fromNumber for converting finite JavaScript numbers

declare function fromString(s: string): Option<BigDecimal>

import { BigDecimal, Option } from "effect"

BigDecimal.fromString("123.456") // => Option.some(BigDecimal.make(123456n, 3))
BigDecimal.fromString("123.abc") // => Option.none()

Parses a decimal string into a BigDecimal, throwing if the string is invalid.

When to use

Use when you expect decimal text to be valid and want parse errors to throw.

Details

Accepts the same syntax as fromString. Use fromString when invalid input should be represented as Option.none instead of throwing.

See

• fromString for returning Option.none on invalid input

declare function fromStringUnsafe(s: string): BigDecimal

import { BigDecimal } from "effect"

BigDecimal.fromStringUnsafe("123") // => BigDecimal.fromBigInt(123n)
BigDecimal.fromStringUnsafe("123.456") // => BigDecimal.make(123456n, 3)

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.

See

• fromBigInt for constructing an integer decimal from a bigint

declare function make(value: bigint, scale: number): BigDecimal

import { BigDecimal } from "effect"

// Create 123.45 (12345 with scale 2)
const decimal = BigDecimal.make(12345n, 2)
decimal // => BigDecimal.fromStringUnsafe("123.45")

// Create 42 (42 with scale 0)
const integer = BigDecimal.make(42n, 0)
integer // => BigDecimal.fromBigInt(42n)

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 the absolute value of the normalized scale is at least 16; otherwise plain decimal notation is used.

See

• toExponential for always rendering scientific notation

declare function format(n: BigDecimal): string

import { BigDecimal } from "effect"

BigDecimal.format(BigDecimal.fromStringUnsafe("-5")) // => "-5"
BigDecimal.format(BigDecimal.fromStringUnsafe("123.456")) // => "123.456"
BigDecimal.format(BigDecimal.fromStringUnsafe("-0.00000123")) // => "-0.00000123"

Formats a given BigDecimal as a string in scientific notation.

When to use

Use to render a BigDecimal in scientific notation.

See

• format for plain decimal formatting when possible

declare function toExponential(n: BigDecimal): string

import { BigDecimal } from "effect"

BigDecimal.toExponential(BigDecimal.make(123456n, -5)) // => "1.23456e+10"

Converts a BigDecimal to a JavaScript number.

When to use

Use when you need a JavaScript number at an interop boundary where precision loss is acceptable.

Gotchas

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.

See

• format for preserving decimal precision as text

declare function toNumberUnsafe(n: BigDecimal): number

import { BigDecimal } from "effect"

BigDecimal.toNumberUnsafe(BigDecimal.fromStringUnsafe("123.456")) // => 123.456

Checks whether a given value is a BigDecimal.

When to use

Use to validate unknown input and narrow it to BigDecimal.

declare function isBigDecimal(u: unknown): u is BigDecimal

import { BigDecimal } from "effect"

const decimal = BigDecimal.fromNumber(123.45)
BigDecimal.isBigDecimal(decimal) // => false
BigDecimal.isBigDecimal(BigDecimal.fromStringUnsafe("123.45")) // => true
BigDecimal.isBigDecimal(123.45) // => false
BigDecimal.isBigDecimal("123.45") // => false

Provides an Equivalence instance for BigDecimal that determines equality between BigDecimal values.

When to use

Use when comparing decimal values through APIs that accept an equivalence relation.

declare const Equivalence: Equ.Equivalence<BigDecimal>

import { BigDecimal } from "effect"

const a = BigDecimal.fromStringUnsafe("1.50")
const b = BigDecimal.fromStringUnsafe("1.5")
const c = BigDecimal.fromStringUnsafe("2.0")

BigDecimal.Equivalence(a, b) // => true
BigDecimal.Equivalence(a, c) // => false

Provides an Order instance for BigDecimal that allows comparing and sorting BigDecimal values.

When to use

Use when you need to sort or compare decimal values through APIs that accept an ordering instance.

declare const Order: order.Order<BigDecimal>

import { BigDecimal } from "effect"

const a = BigDecimal.fromNumberUnsafe(1.5)
const b = BigDecimal.fromNumberUnsafe(2.3)
const c = BigDecimal.fromNumberUnsafe(1.5)

BigDecimal.Order(a, b) // => -1
BigDecimal.Order(b, a) // => 1
BigDecimal.Order(a, c) // => 0

Determines the absolute value of a given BigDecimal.

When to use

Use to remove the sign from a BigDecimal while preserving its magnitude.

declare function abs(n: BigDecimal): BigDecimal

import { BigDecimal } from "effect"

BigDecimal.abs(BigDecimal.fromStringUnsafe("-5")) // => BigDecimal.fromBigInt(5n)
BigDecimal.abs(BigDecimal.fromStringUnsafe("0")) // => BigDecimal.fromBigInt(0n)
BigDecimal.abs(BigDecimal.fromStringUnsafe("5")) // => BigDecimal.fromBigInt(5n)

Computes the ceiling of a BigDecimal at the given scale.

When to use

Use to round a decimal toward positive infinity at a requested scale.

Details

The default scale is 0. Positive scales keep digits to the right of the decimal point, and negative scales round positions to the left of the decimal point.

See

• floor for rounding toward negative infinity
• truncate for rounding toward zero
• round for configurable rounding modes

declare const ceil: {
  (scale: number): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, scale?: number): BigDecimal;
}

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 the minimum value. If it is greater than the maximum value, the function returns the maximum value. Otherwise, it returns the original BigDecimal.

See

• between for checking whether a BigDecimal is already inside a range

declare const clamp: {
  (options: {
    maximum: BigDecimal;
    minimum: BigDecimal;
  }): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, options: {
    maximum: BigDecimal;
    minimum: BigDecimal;
  }): BigDecimal;
}

import { BigDecimal } from "effect"

const clamp = BigDecimal.clamp({
  minimum: BigDecimal.fromStringUnsafe("1"),
  maximum: BigDecimal.fromStringUnsafe("5")
})

clamp(BigDecimal.fromStringUnsafe("3")) // => BigDecimal.fromBigInt(3n)
clamp(BigDecimal.fromStringUnsafe("0")) // => BigDecimal.fromBigInt(1n)
clamp(BigDecimal.fromStringUnsafe("6")) // => BigDecimal.fromBigInt(5n)

Divides BigDecimals safely.

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 with up to the default division precision. If the divisor is 0, the result will be Option.none().

See

• divideUnsafe for division that throws when the divisor is zero
• remainder for the decimal remainder operation

declare const divide: {
  (that: BigDecimal): (self: BigDecimal) => Option<BigDecimal>;
  (self: BigDecimal, that: BigDecimal): Option<BigDecimal>;
}

import { BigDecimal, Option } from "effect"

const six = BigDecimal.fromBigInt(6n)

BigDecimal.divide(six, BigDecimal.fromBigInt(3n)) // => Option.some(BigDecimal.fromBigInt(2n))
BigDecimal.divide(six, BigDecimal.fromBigInt(4n)) // => Option.some(BigDecimal.fromStringUnsafe("1.5"))
BigDecimal.divide(six, BigDecimal.fromBigInt(0n)) // => Option.none()

Provides an unsafe division operation on BigDecimals.

When to use

Use when you need to divide BigDecimal values where the divisor is known to be non-zero, so division by zero should be a thrown exception.

Details

If the dividend is not a multiple of the divisor, the result will be a BigDecimal value with up to the default division precision.

Gotchas

Throws a RangeError if the divisor is 0.

See

• divide for division that returns Option.none when the divisor is zero

declare const divideUnsafe: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, that: BigDecimal): BigDecimal;
}

import { BigDecimal } from "effect"

BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("3")) // => BigDecimal.fromBigInt(2n)
BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4")) // => BigDecimal.fromStringUnsafe("1.5")

Computes the floor of a BigDecimal at the given scale.

When to use

Use to round a decimal toward negative infinity at a requested scale.

See

• ceil for rounding toward positive infinity
• truncate for rounding toward zero
• round for configurable rounding modes

declare const floor: {
  (scale: number): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, scale?: number): BigDecimal;
}

import { BigDecimal } from "effect"

BigDecimal.floor(BigDecimal.fromStringUnsafe("145"), -1) // => BigDecimal.fromBigInt(140n)
BigDecimal.floor(BigDecimal.fromStringUnsafe("-14.5")) // => BigDecimal.fromBigInt(-15n)

Returns the maximum between two BigDecimals.

When to use

Use to select the larger of two BigDecimal values.

See

• min for selecting the smaller value

declare const max: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, that: BigDecimal): BigDecimal;
}

import { BigDecimal } from "effect"

const result = BigDecimal.max(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(3n)

Returns the minimum between two BigDecimals.

When to use

Use to select the smaller of two BigDecimal values.

See

• max for selecting the larger value

declare const min: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, that: BigDecimal): BigDecimal;
}

import { BigDecimal } from "effect"

const result = BigDecimal.min(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(2n)

Provides a multiplication operation on BigDecimals.

When to use

Use to multiply two BigDecimal values.

See

• multiplyAll for multiplying an iterable of BigDecimal values

declare const multiply: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, that: BigDecimal): BigDecimal;
}

import { BigDecimal } from "effect"

const result = BigDecimal.multiply(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(6n)

Takes an Iterable of BigDecimals and returns their multiplication as a single BigDecimal.

When to use

Use to multiply all BigDecimal values in an iterable.

See

• multiply for multiplying two BigDecimal values

declare function multiplyAll(collection: Iterable<BigDecimal>): BigDecimal

import { BigDecimal } from "effect"

const result = BigDecimal.multiplyAll([
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3"),
  BigDecimal.fromStringUnsafe("4")
]) // => BigDecimal.fromBigInt(24n)

Provides a negate operation on BigDecimals.

When to use

Use to flip the sign of a BigDecimal.

declare function negate(n: BigDecimal): BigDecimal

import { BigDecimal } from "effect"

BigDecimal.negate(BigDecimal.fromStringUnsafe("3")) // => BigDecimal.fromBigInt(-3n)
BigDecimal.negate(BigDecimal.fromStringUnsafe("-6")) // => BigDecimal.fromBigInt(6n)

Computes the decimal remainder safely when one operand is divided by a second operand.

When to use

Use to compute a decimal remainder while representing division by zero as Option.none.

Details

If the divisor is 0, the result will be Option.none().

See

• remainderUnsafe for remainder calculation that throws when the divisor is zero
• divide for decimal quotient calculation

declare const remainder: {
  (divisor: BigDecimal): (self: BigDecimal) => Option<BigDecimal>;
  (self: BigDecimal, divisor: BigDecimal): Option<BigDecimal>;
}

import { BigDecimal, Option } from "effect"

const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const zero = BigDecimal.fromStringUnsafe("0")

BigDecimal.remainder(three, two) // => Option.some(BigDecimal.fromBigInt(1n))
BigDecimal.remainder(two, zero) // => Option.none()

Returns the decimal remainder left over when one operand is divided by a non-zero second operand.

When to use

Use when you need to compute a BigDecimal remainder with a divisor known to be non-zero and want a plain BigDecimal result instead of an Option.

Gotchas

Throws a RangeError if the divisor is 0.

See

• remainder for returning Option.none when the divisor is zero

declare const remainderUnsafe: {
  (divisor: BigDecimal): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, divisor: BigDecimal): BigDecimal;
}

import { BigDecimal } from "effect"

BigDecimal.remainderUnsafe(
  BigDecimal.fromStringUnsafe("3"),
  BigDecimal.fromStringUnsafe("2")
) // => BigDecimal.fromBigInt(1n)

Computes a rounded BigDecimal at the given scale with the specified rounding mode.

When to use

Use to round a decimal at a requested scale with an explicit rounding mode.

See

• ceil for fixed rounding toward positive infinity
• floor for fixed rounding toward negative infinity
• truncate for fixed rounding toward zero

declare const round: {
  (options: {
    mode?: RoundingMode;
    scale?: number;
  }): (self: BigDecimal) => BigDecimal;
  (n: BigDecimal, options?: {
    mode?: RoundingMode;
    scale?: number;
  }): BigDecimal;
}

import { BigDecimal } from "effect"

const positive = BigDecimal.round(BigDecimal.fromStringUnsafe("145"), { mode: "from-zero", scale: -1 })
positive // => BigDecimal.fromBigInt(150n)

const negative = BigDecimal.round(BigDecimal.fromStringUnsafe("-14.5"))
negative // => BigDecimal.fromBigInt(-15n)

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
• floor: round towards negative infinity
• to-zero: round towards zero
• from-zero: round away from zero
• half-ceil: round to the nearest neighbor; if equidistant round towards positive infinity
• half-floor: round to the nearest neighbor; if equidistant round towards negative infinity
• half-to-zero: round to the nearest neighbor; if equidistant round towards zero
• half-from-zero: round to the nearest neighbor; if equidistant round away from zero
• 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

• round for configurable rounding with a RoundingMode
• ceil for fixed rounding toward positive infinity
• floor for fixed rounding toward negative infinity
• truncate for fixed rounding toward zero

type RoundingMode = "ceil" | "floor" | "to-zero" | "from-zero" | "half-ceil" | "half-floor" | "half-to-zero" | "half-from-zero" | "half-even" | "half-odd"

Determines the sign of a given BigDecimal.

When to use

Use to classify a BigDecimal as negative, zero, or positive.

declare function sign(n: BigDecimal): Ordering

import { BigDecimal } from "effect"

BigDecimal.sign(BigDecimal.fromStringUnsafe("-5")) // => -1
BigDecimal.sign(BigDecimal.fromStringUnsafe("0")) // => 0
BigDecimal.sign(BigDecimal.fromStringUnsafe("5")) // => 1

Provides a subtraction operation on BigDecimals.

When to use

Use to subtract one BigDecimal value from another.

declare const subtract: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, that: BigDecimal): BigDecimal;
}

import { BigDecimal } from "effect"

const result = BigDecimal.subtract(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(-1n)

Provides an addition operation on BigDecimals.

When to use

Use when you need a decimal addition function for piping or higher-order APIs while preserving decimal precision.

See

• sumAll for summing an iterable of BigDecimal values

declare const sum: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, that: BigDecimal): BigDecimal;
}

import { BigDecimal } from "effect"

const result = BigDecimal.sum(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(5n)

Takes an Iterable of BigDecimals and returns their sum as a single BigDecimal.

When to use

Use when you need to aggregate decimal quantities with decimal precision instead of converting through JavaScript numbers.

See

• sum for adding two BigDecimal values

declare function sumAll(collection: Iterable<BigDecimal>): BigDecimal

import { BigDecimal } from "effect"

const result = BigDecimal.sumAll([
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3"),
  BigDecimal.fromStringUnsafe("4")
]) // => BigDecimal.fromBigInt(9n)

Computes a truncated BigDecimal at the given scale. This removes fractional digits beyond the scale, rounding toward zero.

When to use

Use when you need to discard fractional digits beyond a scale rather than round half up, half down, or toward an infinity.

See

• round for configurable rounding modes
• ceil for rounding toward positive infinity
• floor for rounding toward negative infinity

declare const truncate: {
  (scale: number): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, scale?: number): BigDecimal;
}

import { BigDecimal } from "effect"

BigDecimal.truncate(BigDecimal.fromStringUnsafe("145"), -1) // => BigDecimal.fromBigInt(140n)
BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5")) // => BigDecimal.fromBigInt(-14n)

Represents an arbitrary precision decimal number.

When to use

Use when decimal arithmetic needs to avoid JavaScript floating point representation errors.

interface BigDecimal extends Equal, Pipeable, Inspectable {
  readonly "~effect/BigDecimal": "~effect/BigDecimal";
  readonly scale: number;
  readonly value: bigint;
}

import { BigDecimal } from "effect"

const d = BigDecimal.fromStringUnsafe("123.45")

d.value // => 12345n
d.scale // => 2

Checks whether a BigDecimal is between a minimum and maximum value (inclusive).

When to use

Use to test whether a BigDecimal falls inside an inclusive range.

See

• clamp for forcing a BigDecimal into an inclusive range

declare const between: {
  (options: {
    maximum: BigDecimal;
    minimum: BigDecimal;
  }): (self: BigDecimal) => boolean;
  (self: BigDecimal, options: {
    maximum: BigDecimal;
    minimum: BigDecimal;
  }): boolean;
}

import { BigDecimal } from "effect"

const between = BigDecimal.between({
  minimum: BigDecimal.fromStringUnsafe("1"),
  maximum: BigDecimal.fromStringUnsafe("5")
})

between(BigDecimal.fromStringUnsafe("3")) // => true
between(BigDecimal.fromStringUnsafe("0")) // => false
between(BigDecimal.fromStringUnsafe("6")) // => false

Checks whether two BigDecimals are equal.

When to use

Use to compare two BigDecimal values for numeric equality.

See

• Equivalence for passing decimal equality to APIs that require an Equivalence

declare const equals: {
  (that: BigDecimal): (self: BigDecimal) => boolean;
  (self: BigDecimal, that: BigDecimal): boolean;
}

import { BigDecimal } from "effect"

const a = BigDecimal.fromStringUnsafe("1.5")
const b = BigDecimal.fromStringUnsafe("1.50")
const c = BigDecimal.fromStringUnsafe("2.0")

BigDecimal.equals(a, b) // => true
BigDecimal.equals(a, c) // => false

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.

declare const isGreaterThan: {
  (that: BigDecimal): (self: BigDecimal) => boolean;
  (self: BigDecimal, that: BigDecimal): boolean;
}

import { BigDecimal } from "effect"

const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const four = BigDecimal.fromStringUnsafe("4")

BigDecimal.isGreaterThan(two, three) // => false
BigDecimal.isGreaterThan(three, three) // => false
BigDecimal.isGreaterThan(four, three) // => true

Checks whether a given BigDecimal is greater than or equal to the provided one.

When to use

Use to test whether one BigDecimal is greater than or equal to another.

declare const isGreaterThanOrEqualTo: {
  (that: BigDecimal): (self: BigDecimal) => boolean;
  (self: BigDecimal, that: BigDecimal): boolean;
}

import { BigDecimal } from "effect"

const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const four = BigDecimal.fromStringUnsafe("4")

BigDecimal.isGreaterThanOrEqualTo(two, three) // => false
BigDecimal.isGreaterThanOrEqualTo(three, three) // => true
BigDecimal.isGreaterThanOrEqualTo(four, three) // => true

Checks whether a given BigDecimal is an integer.

When to use

Use to test whether a BigDecimal has no fractional decimal part.

declare function isInteger(n: BigDecimal): boolean

import { BigDecimal } from "effect"

BigDecimal.isInteger(BigDecimal.fromStringUnsafe("0")) // => true
BigDecimal.isInteger(BigDecimal.fromStringUnsafe("1")) // => true
BigDecimal.isInteger(BigDecimal.fromStringUnsafe("1.1")) // => false

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.

declare const isLessThan: {
  (that: BigDecimal): (self: BigDecimal) => boolean;
  (self: BigDecimal, that: BigDecimal): boolean;
}

import { BigDecimal } from "effect"

const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const four = BigDecimal.fromStringUnsafe("4")

BigDecimal.isLessThan(two, three) // => true
BigDecimal.isLessThan(three, three) // => false
BigDecimal.isLessThan(four, three) // => false

Checks whether a given BigDecimal is less than or equal to the provided one.

When to use

Use to test whether one BigDecimal is less than or equal to another.

declare const isLessThanOrEqualTo: {
  (that: BigDecimal): (self: BigDecimal) => boolean;
  (self: BigDecimal, that: BigDecimal): boolean;
}

import { BigDecimal } from "effect"

const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const four = BigDecimal.fromStringUnsafe("4")

BigDecimal.isLessThanOrEqualTo(two, three) // => true
BigDecimal.isLessThanOrEqualTo(three, three) // => true
BigDecimal.isLessThanOrEqualTo(four, three) // => false

Checks whether a given BigDecimal is negative.

When to use

Use to test whether a BigDecimal is less than zero.

declare function isNegative(n: BigDecimal): boolean

import { BigDecimal } from "effect"

BigDecimal.isNegative(BigDecimal.fromStringUnsafe("-1")) // => true
BigDecimal.isNegative(BigDecimal.fromStringUnsafe("0")) // => false
BigDecimal.isNegative(BigDecimal.fromStringUnsafe("1")) // => false

Checks whether a given BigDecimal is positive.

When to use

Use to test whether a BigDecimal is greater than zero.

declare function isPositive(n: BigDecimal): boolean

import { BigDecimal } from "effect"

BigDecimal.isPositive(BigDecimal.fromStringUnsafe("-1")) // => false
BigDecimal.isPositive(BigDecimal.fromStringUnsafe("0")) // => false
BigDecimal.isPositive(BigDecimal.fromStringUnsafe("1")) // => true

Checks whether a given BigDecimal is 0.

When to use

Use to test whether a BigDecimal is exactly zero.

declare function isZero(n: BigDecimal): boolean

import { BigDecimal } from "effect"

BigDecimal.isZero(BigDecimal.fromStringUnsafe("0")) // => true
BigDecimal.isZero(BigDecimal.fromStringUnsafe("1")) // => false

Normalizes a given BigDecimal by removing trailing zeros.

When to use

Use to canonicalize decimals that have equivalent values but different internal scales.

See

• format for rendering normalized decimals as strings

declare function normalize(self: BigDecimal): BigDecimal

import { BigDecimal } from "effect"

const decimal = BigDecimal.normalize(BigDecimal.fromStringUnsafe("123.00000"))
const decimalStorage = [decimal.value, decimal.scale] // => [123n, 0]

const largeDecimal = BigDecimal.normalize(BigDecimal.fromStringUnsafe("12300000"))
const largeDecimalStorage = [largeDecimal.value, largeDecimal.scale] // => [123n, -5]

Changes 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 digits beyond the target scale by bigint division, which truncates toward zero.

See

• round for changing scale with configurable rounding

declare const scale: {
  (scale: number): (self: BigDecimal) => BigDecimal;
  (self: BigDecimal, scale: number): BigDecimal;
}

import { BigDecimal } from "effect"

const decimal = BigDecimal.fromNumberUnsafe(123.45)

// Increase scale (add more precision)
const scaled = BigDecimal.scale(decimal, 4)
const scaledStorage = [scaled.value, scaled.scale] // => [1234500n, 4]

// Decrease scale (reduce precision, truncating toward zero)
const reduced = BigDecimal.scale(decimal, 1)
reduced // => BigDecimal.fromStringUnsafe("123.4")