Docs / Standard Library / BigDecimal

BigDecimal

The BigDecimal module provides arbitrary-precision decimal arithmetic. Unlike floating-point numbers, BigDecimals can represent decimal fractions exactly, making them ideal for financial calculations and other applications where precision is critical.

Representation

A BigDecimal is represented as a significand (integer) and a scale (number of decimal places). For example, 12.345 has significand 12345 and scale 3.

Creation

BigDecimal.new
Int -> Int -> BigDecimal
Creates a BigDecimal from a significand and scale. 
# Create 12.345 (significand=12345, scale=3)
d = BigDecimal.new 12345 3
println (BigDecimal.to-string d)
# => "12.345"

# Create 100 (significand=100, scale=0)
d = BigDecimal.new 100 0
println (BigDecimal.to-string d)
# => "100"
BigDecimal.from-int
Int -> BigDecimal
Creates a BigDecimal from an integer (scale = 0). 
d = BigDecimal.from-int 42
println (BigDecimal.to-string d)
# => "42"
BigDecimal.from-float
Float -> Int -> BigDecimal
Creates a BigDecimal from a float with specified scale (decimal places). 
d = BigDecimal.from-float 3.14159 4
println (BigDecimal.to-string d)
# => "3.1416"
BigDecimal.parse
String -> Option BigDecimal
Parses a string into a BigDecimal. 
match BigDecimal.parse "123.456"
  | Some d -> println (BigDecimal.to-string d)
  | None -> println "Invalid"
# => "123.456"

Accessors

BigDecimal.significand
BigDecimal -> Int
Returns the significand (unscaled value) of the BigDecimal. 
d = BigDecimal.new 12345 3  # 12.345
println (BigDecimal.significand d)
# => 12345
BigDecimal.scale
BigDecimal -> Int
Returns the scale (number of decimal places) of the BigDecimal. 
d = BigDecimal.new 12345 3  # 12.345
println (BigDecimal.scale d)
# => 3

Arithmetic

BigDecimal.add
BigDecimal -> BigDecimal -> BigDecimal
Adds two BigDecimals. 
a = BigDecimal.from-int 10
b = BigDecimal.new 25 1  # 2.5
println (BigDecimal.to-string (BigDecimal.add a b))
# => "12.5"
BigDecimal.subtract
BigDecimal -> BigDecimal -> BigDecimal
Subtracts two BigDecimals.
BigDecimal.multiply
BigDecimal -> BigDecimal -> BigDecimal
Multiplies two BigDecimals. 
price = BigDecimal.new 1999 2  # $19.99
qty = BigDecimal.from-int 3
println (BigDecimal.to-string (BigDecimal.multiply price qty))
# => "59.97"
BigDecimal.divide
BigDecimal -> BigDecimal -> Int -> Option BigDecimal
Divides two BigDecimals with specified scale for the result. Returns None if dividing by zero. 
a = BigDecimal.from-int 10
b = BigDecimal.from-int 3
match BigDecimal.divide a b 4  # 4 decimal places
  | Some d -> println (BigDecimal.to-string d)
  | None -> println "Division by zero"
# => "3.3333"
BigDecimal.negate
BigDecimal -> BigDecimal
Negates a BigDecimal (changes sign).
BigDecimal.abs
BigDecimal -> BigDecimal
Returns the absolute value.

Comparison

BigDecimal.compare
BigDecimal -> BigDecimal -> Int
Returns -1 if less than, 0 if equal, 1 if greater than.
BigDecimal.eq?
BigDecimal -> BigDecimal -> Bool
Tests equality.
BigDecimal.lt?
BigDecimal -> BigDecimal -> Bool
Tests if less than.
BigDecimal.le?
BigDecimal -> BigDecimal -> Bool
Tests if less than or equal.
BigDecimal.gt?
BigDecimal -> BigDecimal -> Bool
Tests if greater than.
BigDecimal.ge?
BigDecimal -> BigDecimal -> Bool
Tests if greater than or equal.

Predicates

BigDecimal.zero?
BigDecimal -> Bool
Returns true if the BigDecimal is zero.
BigDecimal.positive?
BigDecimal -> Bool
Returns true if positive.
BigDecimal.negative?
BigDecimal -> Bool
Returns true if negative.
BigDecimal.integer?
BigDecimal -> Bool
Returns true if the BigDecimal represents a whole number (no fractional part).

Rounding

BigDecimal.round
BigDecimal -> Int -> BigDecimal
Rounds to the specified number of decimal places using half-up rounding. 
d = BigDecimal.new 12345 3  # 12.345
println (BigDecimal.to-string (BigDecimal.round d 2))
# => "12.35"
BigDecimal.floor
BigDecimal -> BigDecimal
Rounds down to the nearest integer (toward negative infinity).
BigDecimal.ceil
BigDecimal -> BigDecimal
Rounds up to the nearest integer (toward positive infinity).
BigDecimal.truncate
BigDecimal -> BigDecimal
Truncates toward zero (removes the fractional part).
BigDecimal.set-scale
BigDecimal -> Int -> BigDecimal
Sets the scale (number of decimal places) with rounding. 
d = BigDecimal.new 1 0  # 1
println (BigDecimal.to-string (BigDecimal.set-scale d 2))
# => "1.00"

Conversion

BigDecimal.to-float
BigDecimal -> Float
Converts to a floating-point number (may lose precision).
BigDecimal.to-int
BigDecimal -> Int
Converts to an integer by truncating the fractional part.
BigDecimal.to-string
BigDecimal -> String
Converts to a string representation. 
d = BigDecimal.new 12345 2  # 123.45
println (BigDecimal.to-string d)
# => "123.45"