Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.decimal

    RoundingMode.AwayFromZero

    Round inexact values away from zero, including midpoint values.

    RoundingMode.AwayFromZero()
    Receiver
    Not applicable
    Minimum arity
    0
    Maximum arity
    0

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.decimal in language mode 5.21.

    The current compiler selects std/decimal.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    Not applicable

    Parameter constraints

    Additional contracts are Pending.

    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.

    Related rule: Choose a decimal grid and a rounding direction

    Result

    Additional contracts are Pending.

    The declared result type is RoundingMode.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Choose the decimal grid value with larger absolute magnitude. Exact grid values remain unchanged.

    Why

    Link

    Increasing absolute magnitude expresses a different bound from rounding toward positive infinity.

    Resolved contracts

    Link

    Related entries

    Link

    std.decimal

    Choose a decimal grid and a rounding direction

    Link
    Ruletopaz.stdlib.contract.decimal-round.rule

    Choose a decimal grid and a rounding direction

    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.

    Why

    A decimal grid states which precision the caller needs. Nearest rounding, an upper or lower bound, and movement toward or away from zero express different numeric intentions. Their results can agree for some inputs without making their meanings interchangeable. HalfEven gives exact ties a stable rule without consistently favoring one magnitude direction.

    Examples Resolve positive and negative ties in every rounding modeDistinguish directed rounding from nearest roundingApply the default mode and normalize a carry or zeroAccept the largest scale without adding stored zerosReject a rounding scale outside the valid rangeReject a rounding scale outside the valid range

    Diagnostics TPZ5001

    Source evidence

    Resolve positive and negative ties in every rounding mode

    Link

    run · running · Verification: not-run

    main.tpzResolve positive and negative ties in every rounding modeOpen in Playground
    1. import std.decimal { Decimal, RoundingMode }
    2. import std.test
    3. import std.io
    5. function read(text: string) -> Decimal {
    6. let parsed: Option<Decimal> = Decimal.parse(text)
    7. let value: Decimal = test.assertSome(parsed)
    8. return value
    9. }
    11. function rounded(text: string, mode: RoundingMode) -> string {
    12. let value: Decimal = read(text)
    13. return value.round(0, mode).toString()
    14. }
    16. let modes: Array<RoundingMode> = [RoundingMode.Down(), RoundingMode.Up(), RoundingMode.TowardZero(), RoundingMode.AwayFromZero(), RoundingMode.HalfUp(), RoundingMode.HalfEven()]
    17. for mode in (modes) {
    18. let a = rounded("2.5", mode)
    19. let b = rounded("3.5", mode)
    20. let c = rounded("-2.5", mode)
    21. let d = rounded("-3.5", mode)
    22. io.writeLine("{a} {b} {c} {d}")
    23. }
    Expected outputexit 0
    2 3 -3 -4
3 4 -2 -3
2 3 -2 -3
3 4 -3 -4
3 4 -3 -4
2 4 -2 -4
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 2 3 -3 -4
    2. 3 4 -2 -3
    3. 2 3 -2 -3
    4. 3 4 -3 -4
    5. 3 4 -3 -4
    6. 2 4 -2 -4

    This exact example has not been executed.

    Source evidence

    Distinguish directed rounding from nearest rounding

    Link

    run · running · Verification: not-run

    main.tpzDistinguish directed rounding from nearest roundingOpen in Playground
    1. import std.decimal { Decimal, RoundingMode }
    2. import std.test
    3. import std.io
    5. function read(text: string) -> Decimal {
    6. let parsed: Option<Decimal> = Decimal.parse(text)
    7. let value: Decimal = test.assertSome(parsed)
    8. return value
    9. }
    11. function rounded(text: string, mode: RoundingMode) -> string {
    12. let value: Decimal = read(text)
    13. return value.round(0, mode).toString()
    14. }
    16. let modes: Array<RoundingMode> = [RoundingMode.Down(), RoundingMode.Up(), RoundingMode.TowardZero(), RoundingMode.AwayFromZero(), RoundingMode.HalfUp(), RoundingMode.HalfEven()]
    17. for mode in (modes) {
    18. let a = rounded("2.1", mode)
    19. let b = rounded("2.9", mode)
    20. let c = rounded("-2.1", mode)
    21. let d = rounded("-2.9", mode)
    22. io.writeLine("{a} {b} {c} {d}")
    23. }
    Expected outputexit 0
    2 2 -3 -3
3 3 -2 -2
2 2 -2 -2
3 3 -3 -3
2 3 -2 -3
2 3 -2 -3
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 2 2 -3 -3
    2. 3 3 -2 -2
    3. 2 2 -2 -2
    4. 3 3 -3 -3
    5. 2 3 -2 -3
    6. 2 3 -2 -3

    This exact example has not been executed.

    Source evidence

    Apply the default mode and normalize a carry or zero

    Link

    run · running · Verification: not-run

    main.tpzApply the default mode and normalize a carry or zeroOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.test
    3. import std.io
    5. function read(text: string) -> Decimal {
    6. let parsed: Option<Decimal> = Decimal.parse(text)
    7. let value: Decimal = test.assertSome(parsed)
    8. return value
    9. }
    11. let value: Decimal = read("1.245")
    12. io.writeLine(value.round(2).toString())
    13. io.writeLine(read("1.255").round(2).toString())
    14. io.writeLine(value.round(5).toString())
    15. let carry: Decimal = read("9.995").round(2)
    16. let zero: Decimal = read("-0.004").round(2)
    17. io.writeLine("{carry.toString()} {carry.scale()}")
    18. io.writeLine("{zero.toString()} {zero.scale()}")
    19. io.writeLine(value.toString())
    Expected outputexit 0
    1.24
1.26
1.245
10 0
0 0
1.245
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 1.24
    2. 1.26
    3. 1.245
    4. 10 0
    5. 0 0
    6. 1.245

    This exact example has not been executed.

    Source evidence

    Accept the largest scale without adding stored zeros

    Link

    run · running · Verification: not-run

    main.tpzAccept the largest scale without adding stored zerosOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.test
    3. import std.io
    5. let one: Decimal = (1).toDecimal()
    6. let zero: Decimal = (0).toDecimal()
    7. let same: Decimal = one.round(4294967295)
    8. let sameZero: Decimal = zero.round(4294967295)
    9. io.writeLine("{same.toString()} {same.scale()}")
    10. io.writeLine("{sameZero.toString()} {sameZero.scale()}")
    Expected outputexit 0
    1 0
0 0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 1 0
    2. 0 0

    This exact example has not been executed.

    Source evidence

    Reject a rounding scale outside the valid range

    Link

    run · running · Verification: not-run

    main.tpzReject a rounding scale outside the valid rangeOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.io
    3. let value: Decimal = (1).toDecimal()
    4. value.round(-1)
    5. io.writeLine("after")
    Expected outputNonzero exit
    No stdout.
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ5001 stdlib-decimal-scale at main.tpz:4:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject a rounding scale outside the valid range

    Link

    run · running · Verification: not-run

    main.tpzReject a rounding scale outside the valid rangeOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.io
    3. let value: Decimal = (1).toDecimal()
    4. value.round(4294967296)
    5. io.writeLine("after")
    Expected outputNonzero exit
    No stdout.
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ5001 stdlib-decimal-scale at main.tpz:4:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Runtime value guard

    Menu

    Download