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
| Constructor | Description |
|---|---|
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.
| Constructor | Description |
|---|---|
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) |