Struct Decimal

pub struct Decimal(/* private fields */);

A fixed-point decimal number type.

This type should be used for precise arithmetic operations on numbers represented in base 10. A typical use case is representing currency.

Example

Decimal: #(decimal("0.1") + decimal("0.2")) \
Float: #(0.1 + 0.2)

Construction and casts

To create a decimal number, use the {decimal(string)} constructor, such as in {decimal("3.141592653")} (note the double quotes!). This constructor preserves all given fractional digits, provided they are representable as per the limits specified below (otherwise, an error is raised).

You can also convert any integer to a decimal with the {decimal(int)} constructor, e.g. {decimal(59)}. However, note that constructing a decimal from a floating-point number, while supported, is an imprecise conversion and therefore discouraged. A warning will be raised if Typst detects that there was an accidental float to decimal cast through its constructor, e.g. if writing {decimal(3.14)} (note the lack of double quotes, indicating this is an accidental float cast and therefore imprecise). It is recommended to use strings for constant decimal values instead (e.g. {decimal("3.14")}).

The precision of a float to decimal cast can be slightly improved by rounding the result to 15 digits with calc.round, but there are still no precision guarantees for that kind of conversion.

Operations

Basic arithmetic operations are supported on two decimals and on pairs of decimals and integers.

Built-in operations between float and decimal are not supported in order to guard against accidental loss of precision. They will raise an error instead.

Certain calc functions, such as trigonometric functions and power between two real numbers, are also only supported for float (although raising decimal to integer exponents is supported). You can opt into potentially imprecise operations with the {float(decimal)} constructor, which casts the decimal number into a float, allowing for operations without precision guarantees.

Displaying decimals

To display a decimal, simply insert the value into the document. To only display a certain number of digits, round the decimal first. Localized formatting of decimals and other numbers is not yet supported, but planned for the future.

You can convert decimals to strings using the str constructor. This way, you can post-process the displayed representation, e.g. to replace the period with a comma (as a stand-in for proper built-in localization to languages that use the comma).

Precision and limits

A decimal number has a limit of 28 to 29 significant base-10 digits. This includes the sum of digits before and after the decimal point. As such, numbers with more fractional digits have a smaller range. The maximum and minimum decimal numbers have a value of {79228162514264337593543950335} and {-79228162514264337593543950335} respectively. In contrast with [float], this type does not support infinity or NaN, so overflowing or underflowing operations will raise an error.

Typical operations between decimal numbers, such as addition, multiplication, and power to an integer, will be highly precise due to their fixed-point representation. Note, however, that multiplication and division may not preserve all digits in some edge cases: while they are considered precise, digits past the limits specified above are rounded off and lost, so some loss of precision beyond the maximum representable digits is possible. Note that this behavior can be observed not only when dividing, but also when multiplying by numbers between 0 and 1, as both operations can push a number’s fractional digits beyond the limits described above, leading to rounding. When those two operations do not surpass the digit limits, they are fully precise.

Implementations

impl Decimal

pub const ZERO: Decimal

pub const ONE: Decimal

pub const MIN: Decimal

pub const MAX: Decimal

pub const fn is_zero(self) -> bool

Whether this decimal value is zero.

pub const fn is_negative(self) -> bool

Whether this decimal value is negative.

pub fn is_integer(self) -> bool

Whether this decimal has fractional part equal to zero (is an integer).

pub fn abs(self) -> Decimal

Computes the absolute value of this decimal.

pub fn floor(self) -> Decimal

Computes the largest integer less than or equal to this decimal.

A decimal is returned as this may not be within i64’s range of values.

pub fn ceil(self) -> Decimal

Computes the smallest integer greater than or equal to this decimal.

A decimal is returned as this may not be within i64’s range of values.

pub fn trunc(self) -> Decimal

Returns the integer part of this decimal.

pub fn fract(self) -> Decimal

Returns the fractional part of this decimal (with the integer part set to zero).

pub fn round(self, digits: i32) -> Option<Decimal>

Rounds this decimal up to the specified amount of digits with the traditional rounding rules, using the “midpoint away from zero” strategy (6.5 -> 7, -6.5 -> -7).

If given a negative amount of digits, rounds to integer digits instead with the same rounding strategy. For example, rounding to -3 digits will turn 34567.89 into 35000.00 and -34567.89 into -35000.00.

Note that this can return None when using negative digits where the rounded number would overflow the available range for decimals.

pub fn checked_add(self, other: Decimal) -> Option<Decimal>

Attempts to add two decimals.

Returns None on overflow or underflow.

pub fn checked_sub(self, other: Decimal) -> Option<Decimal>

Attempts to subtract a decimal from another.

Returns None on overflow or underflow.

pub fn checked_mul(self, other: Decimal) -> Option<Decimal>

Attempts to multiply two decimals.

Returns None on overflow or underflow.

pub fn checked_div(self, other: Decimal) -> Option<Decimal>

Attempts to divide two decimals.

Returns None if other is zero, as well as on overflow or underflow.

pub fn checked_div_euclid(self, other: Decimal) -> Option<Decimal>

Attempts to obtain the quotient of Euclidean division between two decimals. Implemented similarly to f64::div_euclid.

The returned quotient is truncated and adjusted if the remainder was negative.

Returns None if other is zero, as well as on overflow or underflow.

pub fn checked_rem_euclid(self, other: Decimal) -> Option<Decimal>

Attempts to obtain the remainder of Euclidean division between two decimals. Implemented similarly to f64::rem_euclid.

The returned decimal r is non-negative within the range 0.0 <= r < other.abs().

Returns None if other is zero, as well as on overflow or underflow.

pub fn checked_rem(self, other: Decimal) -> Option<Decimal>

Attempts to calculate the remainder of the division of two decimals.

Returns None if other is zero, as well as on overflow or underflow.

pub fn checked_powi(self, other: i64) -> Option<Decimal>

Attempts to take one decimal to the power of an integer.

Returns None for invalid operands, as well as on overflow or underflow.

impl Decimal

pub fn construct( engine: &mut Engine<'_>, value: Spanned<ToDecimal>, ) -> Result<Decimal, EcoVec<SourceDiagnostic>>

Converts a value to a decimal.

It is recommended to use a string to construct the decimal number, or an integer (if desired). The string must contain a number in the format {"3.14159"} (or {"-3.141519"} for negative numbers). The fractional digits are fully preserved; if that’s not possible due to the limit of significant digits (around 28 to 29) having been reached, an error is raised as the given decimal number wouldn’t be representable.

While this constructor can be used with floating-point numbers to cast them to decimal, doing so is discouraged as this cast is inherently imprecise. It is easy to accidentally perform this cast by writing {decimal(1.234)} (note the lack of double quotes), which is why Typst will emit a warning in that case. Please write {decimal("1.234")} instead for that particular case (initialization of a constant decimal). Also note that floats that are NaN or infinite cannot be cast to decimals and will raise an error.

#decimal("1.222222222222222")

Trait Implementations

impl Clone for Decimal

fn clone(&self) -> Decimal

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Decimal

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Decimal

fn default() -> Decimal

Returns the “default value” for a type.

impl Display for Decimal

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<i64> for Decimal

fn from(value: i64) -> Decimal

Converts to this type from the input type.

impl FromStr for Decimal

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Decimal, <Decimal as FromStr>::Err>

Parses a string s to return a value of this type.

impl FromValue for Decimal

fn from_value(value: Value) -> Result<Decimal, HintedString>

Try to cast the value into an instance of Self.

impl Hash for Decimal

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for Decimal

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Decimal

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl NativeType for Decimal

const NAME: &'static str = "decimal"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl Neg for Decimal

type Output = Decimal

The resulting type after applying the - operator.

fn neg(self) -> Decimal

Performs the unary - operation.

impl Ord for Decimal

fn cmp(&self, other: &Decimal) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Decimal

fn eq(&self, other: &Decimal) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Decimal

fn partial_cmp(&self, other: &Decimal) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Reflect for Decimal

fn input() -> CastInfo

Describe what can be cast into this value.

fn output() -> CastInfo

Describe what this value can be cast into.

fn castable(value: &Value) -> bool

Whether the given value can be converted to T.

fn error(found: &Value) -> HintedString

Produce an error message for an unacceptable value type.

impl Repr for Decimal

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl TryFrom<f64> for Decimal

fn try_from(value: f64) -> Result<Decimal, <Decimal as TryFrom<f64>>::Error>

Attempts to convert a Decimal to a float.

This can fail if the float is infinite or NaN, or otherwise cannot be represented by a decimal number.

type Error = ()

The type returned in the event of a conversion error.

impl Copy for Decimal

impl Eq for Decimal

impl StructuralPartialEq for Decimal