Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Construction (Decimal)

Decimal can be constructed from various types of input using the Decimal() constructor or factory methods. Among these, the most common way is from a string representation of the decimal number, which is the most accurate way to create a Decimal without any precision loss.

From String (Decimal)

It is highly recommended to construct Decimal from a string. Please consider using this method whenever possible.

var a = Decimal("123456789.123456789")  # Basic decimal string
var b = Decimal("1.23E+10")             # Scientific notation
var c = Decimal("-0.000001")            # Negative
var d = Decimal("1_000_000.50")         # Separator support

From zero (Decimal)

var x = Decimal("0")  # Explicitly from string
var y = Decimal()    # Default constructor creates zero, same as Decimal("0")

From Int or an integer literal (Decimal)

var x = Decimal(42)     # From Int
var y: Decimal = 100    # From an integer literal
var z: Decimal = 123456789012345678901234567890  # Wider than Int, still exact
var w = Decimal(2**200)  # Worked out exactly at compile time

An integer literal of any size is exact, as decimal.Decimal(int) is in Python. A run-time Int is 64 bits, so Decimal(n << 100) for an Int n has already lost its high bits before Decimal sees it.

From integral scalars

var x = Decimal(Int64(123456789))
var y = Decimal(UInt128(99999999999999))

Works with all integral SIMD types. Floating-point scalars are rejected at compile time — use from_float_scalar() instead.

From floating-point — from_float_scalar()

from_float_scalar() reads the bits of the float and returns the value the float actually holds, not the literal that was written to produce it: from_float_scalar(0.1) is 0.1000000000000000055511151231257827021181583404541015625, which is what decimal.Decimal(0.1) gives as well.

Note that not all decimal numbers can be represented exactly as binary floating-point. You may lose precision without awareness.

To make the conversion from float to Decimal more explicit so that you are aware of the potential precision issues, the Decimal() constructor does not accept floating-point numbers directly. Instead, to create a Decimal from a float, you must use the from_float_scalar() factory method. It accepts any floating-point width — Float16, BFloat16, Float32, Float64 and the 8-bit formats — since every one of them widens to Float64 exactly.

Consider never using Decimal.from_float_scalar() in performance-sensitive code, but use string construction instead.

var x = Decimal.from_float_scalar(3.14159)
var y = Decimal.from_float_scalar(Float32(2.71828))

from_float() is the former name and still works, forwarding unchanged. It is deprecated in favour of from_float_scalar(), which lines up with from_integral_scalar().

From Python — from_python_decimal()

You can always safely construct a Decimal from a Python decimal.Decimal using the from_python_decimal() method without worrying about precision loss.

from std.python import Python

var decimal = Python.import_module("decimal")
var py_dec = decimal.Decimal("123.456")

var a = Decimal.from_python_decimal(py_dec)
var b = Decimal(py=py_dec)  # Alternative keyword-only syntax

Summary of Decimal constructors

ConstructorDescription
Decimal()Zero
Decimal(value: IntLiteral)From a literal of any size
Decimal(value: String)From string (raises)
Decimal(value: Scalar)From any integral scalar (impl)
Decimal(py=py_obj)From Python Decimal (raises)
Decimal.from_integral_scalar(value)From any integral scalar type
Decimal.from_float_scalar(value)From any float scalar (raises)
Decimal.from_float(value)Deprecated alias of the above
Decimal.from_string(value)Explicit factory from string
Decimal.from_python_decimal(py_obj)From Python Decimal (raises)

Unsafe Decimal constructors

These constructors skip validation for performance-sensitive code. The caller must ensure the data is valid.

ConstructorDescription
Decimal(coefficient: BigUInt, scale: Int, sign: Bool)From raw components
Decimal.from_raw_components(words, scale=0, sign=False)From raw List[BigUInt.Word] words (unsafe)
Decimal.from_raw_components(word, scale=0, sign=False)From a single BigUInt.Word (unsafe)