std.decimal

A Decimal represents a signed integer coefficient multiplied by ten raised to the negative scale. The coefficient has arbitrary precision. The scale is an integer from 0 through 4294967295 inclusive.

Decimal has no fixed significant digit limit or ambient precision context. Increasing the coefficient beyond the int range does not cause numeric overflow. Decimal values are finite and have no infinity or NaN.

Every Decimal is canonical. Remove trailing coefficient zeros while its scale is positive. Zero has coefficient zero and scale zero. A negative zero spelling produces the same value as zero.

Decimal.scale returns the canonical scale as int. It counts fractional decimal places after normalization. It does not retain input padding or a requested display precision.

Decimal.toString returns exact ASCII decimal text without an exponent or locale rules. A negative nonzero value starts with a minus sign. The integer part has at least one digit and no redundant leading zeros.

A positive scale produces a decimal point followed by exactly that many fractional digits. There are no trailing fractional zeros. Scale zero omits the decimal point, and zero is written as 0.

Exact addition and subtraction align the operand scales before combining their coefficients. Exact multiplication multiplies their coefficients and adds their scales without rounding.

Normalize the exact product before enforcing the scale limit. Raise TPZ4004 when its canonical scale exceeds 4294967295. An intermediate scale sum must not reject a product whose canonical scale fits.

Parsing the output of Decimal.toString recovers the same Decimal. A request for more fractional places through round or div does not append stored zeros.

Decimal values are immutable. Receiver and positional argument expressions evaluate once in source order. An earlier fault prevents later evaluation. The decimal operations themselves do not perform external effects.

Decimal.parse reads the complete input string. Text starts with an optional ASCII plus or minus sign. The remaining text contains ASCII digits and at most one decimal point.

Without a decimal point, at least one digit is required. With a decimal point, at least one digit must follow it and the integer digits may be absent. The strings .5 and -.5 are accepted. The strings 1. and . are rejected.

Leading integer zeros and trailing fractional zeros are accepted. Their exact numeric value is normalized by the decimal value rule. An accepted sign on zero does not survive normalization.

The input may contain at most 4294967295 fractional digits before normalization. A larger fractional digit count returns None(). The integer digit count has no fixed numeric precision limit.

Whitespace, non-ASCII digits, separators, radix prefixes, exponents, NaN and infinity spellings are rejected. Parsing does not trim, remove separators, stop at a valid prefix, or convert through a binary float.

Valid text returns Some containing the exact Decimal. Every malformed spelling returns None() without a numeric conversion fault or replacement value.

This grammar describes text data passed to Decimal.parse. Numeric literal spelling follows the language literal rules.

For a requested scale s, rounding selects a multiple of ten raised to negative s. A value already on that grid is unchanged in every rounding mode.

The requested scale must be an int from 0 through 4294967295 inclusive. A negative value or a value above that range raises TPZ5001 during execution. Scale is never clamped or interpreted as digits to the left of the decimal point.

When the requested scale is at least the canonical scale, round returns the same value. Otherwise it chooses a grid value according to the supplied mode and normalizes the result.

RoundingMode.Down() chooses the greatest grid value no greater than the input. It rounds toward negative infinity, including at a midpoint.

RoundingMode.Up() chooses the least grid value no smaller than the input. It rounds toward positive infinity, including at a midpoint.

RoundingMode.TowardZero() chooses the grid value with smaller absolute magnitude when the input is between two grid values. RoundingMode.AwayFromZero() chooses the one with larger absolute magnitude. These directions also apply at midpoints.

RoundingMode.HalfUp() chooses the nearer grid value. At an exact midpoint it chooses the value with greater absolute magnitude for either sign.

RoundingMode.HalfEven() chooses the nearer grid value. At an exact midpoint it chooses the value whose integer coefficient on the requested grid is even. Determine parity before canonical trailing zeros are removed.

Omitting the mode selects RoundingMode.HalfEven(). The default is independent of host settings and applies equally to positive and negative values.

A carry may reduce the canonical scale. A rounded zero has scale zero and no negative sign. Rounding does not pad the result to the requested scale.

Each RoundingMode spelling constructs a distinct zero payload enum variant and uses parentheses. The modes are immutable values that callers may store and pass to both round and div.

Decimal.div evaluates the exact quotient of its receiver and the divisor. For a nonzero divisor it rounds that quotient once to the requested decimal grid and returns Ok containing the normalized Decimal.

The requested scale and mode have the same meaning as in Decimal.round. Omitting the mode selects RoundingMode.HalfEven(). Input scales and coefficient sizes do not introduce another precision limit or an intermediate rounding step.

A nonterminating decimal quotient is rounded to the requested grid. A terminating quotient that is already on the grid remains exact. The canonical result scale can be smaller than the requested scale.

Division signs follow ordinary numeric division. All six rounding modes apply to the signed exact quotient, including negative ties and results that round to zero.

A zero divisor returns Err with the string Decimal.div: division by zero. This includes zero divided by zero and a divisor parsed from a negative zero spelling. This failure is a Result value and does not raise TPZ4002.

A zero dividend and a nonzero divisor return Ok containing zero for every valid requested scale. An internal sum of operand and requested scales must not turn a nonzero divisor into a division by zero error.

An invalid requested scale raises TPZ5001 during execution before the zero divisor is classified. The operation never replaces an invalid scale with zero or reports that scale error as a successful Result.

The receiver, divisor, scale and explicitly supplied mode expressions evaluate once in that order before their values are validated. The operation preserves both operands.

int.toDecimal converts every int value exactly and produces scale zero. Both signed 64 bit endpoints are representable. The conversion does not pass through float.

Decimal.toInt returns Some containing the same integer when the Decimal is integral and fits the integer conversion bounds.

A nonintegral Decimal or an integer outside the int range returns None(). Conversion does not round, truncate, wrap, saturate, or raise an arithmetic overflow fault. The original Decimal remains unchanged.

A value parsed from 1.000 is integral after normalization and converts to Some containing 1. A value parsed from 1.001 is nonintegral and returns None().

Existing int, float and BigInt values do not implicitly become Decimal values in arithmetic or comparisons. The module provides no direct float or BigInt conversion member.

For an exact BigInt conversion, format it with radix 10 and pass that text to Decimal.parse. To request an integral BigInt from a Decimal, pass its canonical text to BigInt.parse with radix 10. Fractional decimal text is rejected by that integer parser.

Converting through explicitly chosen text follows the corresponding text parser. Decimal.parse never recovers decimal digits that were lost in an earlier binary float calculation.

Decimal equality compares exact numeric values. Values parsed from 1.2, 1.20 and 1.200 are equal. Redundant scale in an input spelling is not part of value identity.

The equality operators == and != return complementary results. Zero and every accepted signed or padded zero spelling compare equal.

The ordering operators <, <=, > and >= use exact numeric order. They align decimal places without first rounding either operand or converting either operand to float.

Every pair of Decimal values is comparable. Equality agrees with ordering, and exactly one of less than, equal to or greater than holds.

Comparison leaves both operands and their canonical scales unchanged. Call round explicitly when comparison after rounding is the intended operation.