BigDecimal.ts overview

Extension to the effect/BigDecimal module providing rounding and formatting utilities.

Mental model

BigDecimal is an arbitrary-precision decimal: a bigint value paired with a scale (the number of decimal digits).
This module focuses on rounding their fractional part and formatting to string.

Common tasks

Instances: zero
Rounding: round, roundedAndRest

Quickstart

Example rounding

import { BigDecimal, Option, pipe } from "effect"
import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"
import { MNumberBase10Format } from "../../esm/index.js"

const bd = pipe(3.14, BigDecimal.fromNumber, Option.getOrThrow)
const truncater = MBigDecimal.round(1, MNumberBase10Format.RoundingOption.Trunc)
console.log(truncater(bd)) // BigDecimal(31, 1) i.e. 3.1

See

round — truncate decimal digits

Constructors

fromFormatAndString

Returns a function that tries to convert a whole string into a BigDecimal respecting format. Unlike fromFormatAndStringStart, the whole of the input string must represent a number.

Use a precomputed parser when the same format will be applied many times.

Example (Parse a BigDecimal from a whole string)

import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"
import * as MNumberBase10Format from "@parischap/effect-lib/MNumberBase10Format"

const parse = MBigDecimal.fromFormatAndString(MNumberBase10Format.frenchStyleNumber)
console.log(parse("-45,50")) // Some(BigDecimal(-4550n, 2))
console.log(parse("-45,50Dummy")) // None

Signature

declare const fromFormatAndString: (
  format: MNumberBase10Format.Type
) => MTypes.OneArgFunction<string, Option.Option<Type>>

Source

fromFormatAndStringOrThrow

Same as fromFormatAndString but throws in case of failure

Signature

declare const fromFormatAndStringOrThrow: (format: MNumberBase10Format.Type) => MTypes.OneArgFunction<string, Type>

Source

fromFormatAndStringStart

Returns a function that tries to extract, from the start of a string, a BigDecimal respecting format. If successful, returns a some of a [value, match] pair where match is the part of the string that could be analyzed as representing a number. Otherwise, returns a none.

Use a precomputed extractor when the same format will be applied many times.

Example (Extract a BigDecimal from the start of a string)

import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"
import * as MNumberBase10Format from "@parischap/effect-lib/MNumberBase10Format"

const extract = MBigDecimal.fromFormatAndStringStart(MNumberBase10Format.frenchStyleNumber)
console.log(extract("-45,50Dummy")) // Some([BigDecimal(-4550n, 2), '-45,50'])

Signature

declare const fromFormatAndStringStart: (
  format: MNumberBase10Format.Type
) => MTypes.OneArgFunction<string, Option.Option<[value: Type, match: string]>>

Source

fromFormatAndStringStartOrThrow

Same as fromFormatAndStringStart but throws in case of failure

Signature

declare const fromFormatAndStringStartOrThrow: (
  format: MNumberBase10Format.Type
) => MTypes.OneArgFunction<string, [value: Type, match: string]>

Source

Destructors

roundedAndRest

Splits self into [roundedPart, followingPart] where truncatedPart is self truncated after precision decimal digits and followingPart is self - truncatedPart.

Use when both the truncated value and its remainder are needed (e.g. when building digit-by-digit formatters).
precision must be a non-negative finite integer; defaults to 0.

Example (Separating truncated and remainder parts)

import { BigDecimal, Option, pipe } from "effect"
import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"
import { MNumberBase10Format } from "../../esm/index.js"

const bd = pipe(3.1459, BigDecimal.fromNumber, Option.getOrThrow)
const [rounded, rest] = pipe(bd, MBigDecimal.roundedAndRest(2, MNumberBase10Format.RoundingOption.Trunc))
// rounded ≡ 3.14, rest ≡ 0.00159

Signature

declare const roundedAndRest: (
  precision: number,
  option: MNumberBase10Format.RoundingOption
) => (self: Type) => [rounded: BigDecimal.BigDecimal, rest: BigDecimal.BigDecimal]

Source

Instances

zero

BigDecimal instance representing 0.

Signature

declare const zero: BigDecimal.BigDecimal

Source

Models

Type (type alias)

Type on which this module’s functions operate.

Signature

type Type = BigDecimal.BigDecimal

Source

Utils

round

Returns a function that rounds a BigDecimal to precision decimal digits according to option.

Use a precomputed rounder when the same precision/option pair will be applied many times.

Example (Round to two decimal digits, half away from zero)

import { pipe } from "effect"
import * as BigDecimal from "effect/BigDecimal"
import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"
import * as MNumberBase10Format from "@parischap/effect-lib/MNumberBase10Format"

const round = MBigDecimal.round(2, MNumberBase10Format.RoundingOption.HalfExpand)
console.log(pipe(BigDecimal.make(124_566n, 4), round)) // BigDecimal(12457n, 2) i.e. 124.57

Signature

declare const round: (precision: number, option: MNumberBase10Format.RoundingOption) => MTypes.OneArgFunction<Type>

Source