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

    Decimal.div

    Divide at the requested decimal grid and return a recoverable zero divisor error.

    div(other: Decimal, scale: int, mode: RoundingMode = RoundingMode.HalfEven()) -> Result<Decimal, string>
    Receiver
    Decimal
    Minimum arity
    2
    Maximum arity
    3

    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

    Decimal

    Parameter constraints

    Additional contracts are Pending.

    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.

    Related rule: Divide with an explicit result scale

    Result

    Additional contracts are Pending.

    The declared result type is Result<Decimal, string>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Round the exact quotient once with the supplied mode and normalize the result. The default mode is HalfEven. Invalid scales raise TPZ5001 during execution before zero divisor classification.

    Why

    Link

    An explicit result grid gives a nonterminating quotient a defined finite result while Result keeps a zero divisor recoverable.

    Resolved contracts

    Link

    Related entries

    Link

    std.decimal

    Divide with an explicit result scale

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

    Divide with an explicit result scale

    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.

    Why

    A division result needs an explicit decimal grid because a finite pair of decimals can have a nonterminating quotient. Rounding the exact quotient once avoids hidden precision loss. A recoverable zero divisor stays distinct from invalid configuration and from internal scale arithmetic.

    Examples Distinguish exact and repeating quotients at the requested gridApply every rounding mode to signed quotient tiesReturn a recoverable error for every zero divisorKeep a zero quotient at the largest valid scaleEvaluate the receiver and division arguments once in orderReject an invalid scale before classifying a zero divisorReject an invalid scale before classifying a zero divisor

    Diagnostics TPZ5001

    Source evidence

    Distinguish exact and repeating quotients at the requested grid

    Link

    run · running · Verification: not-run

    main.tpzDistinguish exact and repeating quotients at the requested gridOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.test
    3. import std.io
    5. function show(result: Result<Decimal, string>) -> () {
    6. let value: Decimal = test.assertOk(result)
    7. io.writeLine("{value.toString()} {value.scale()}")
    8. }
    10. let one: Decimal = (1).toDecimal()
    11. let third: Result<Decimal, string> = one.div((3).toDecimal(), 6)
    12. let eighth: Result<Decimal, string> = one.div((8).toDecimal(), 2)
    13. let negativeTie: Result<Decimal, string> = (-1).toDecimal().div((8).toDecimal(), 2)
    14. let exact: Result<Decimal, string> = (100).toDecimal().div((4).toDecimal(), 4)
    15. let integerGrid: Result<Decimal, string> = (2).toDecimal().div((3).toDecimal(), 0)
    16. show(third)
    17. show(eighth)
    18. show(negativeTie)
    19. show(exact)
    20. show(integerGrid)
    Expected outputexit 0
    0.333333 6
0.12 2
-0.12 2
25 0
1 0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0.333333 6
    2. 0.12 2
    3. -0.12 2
    4. 25 0
    5. 1 0

    This exact example has not been executed.

    Source evidence

    Apply every rounding mode to signed quotient ties

    Link

    run · running · Verification: not-run

    main.tpzApply every rounding mode to signed quotient tiesOpen 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 quotient(text: string, mode: RoundingMode) -> string {
    12. let value: Decimal = read(text)
    13. let result: Result<Decimal, string> = value.div((2).toDecimal(), 0, mode)
    14. let rounded: Decimal = test.assertOk(result)
    15. return rounded.toString()
    16. }
    18. let modes: Array<RoundingMode> = [RoundingMode.Down(), RoundingMode.Up(), RoundingMode.TowardZero(), RoundingMode.AwayFromZero(), RoundingMode.HalfUp(), RoundingMode.HalfEven()]
    19. for mode in (modes) {
    20. let a = quotient("5", mode)
    21. let b = quotient("7", mode)
    22. let c = quotient("-5", mode)
    23. let d = quotient("-7", mode)
    24. io.writeLine("{a} {b} {c} {d}")
    25. }
    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

    Return a recoverable error for every zero divisor

    Link

    run · running · Verification: not-run

    main.tpzReturn a recoverable error for every zero divisorOpen 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 divisor: Decimal = read("-0.000")
    12. let numerators: Array<Decimal> = [(0).toDecimal(), (1).toDecimal()]
    13. for numerator in (numerators) {
    14. let result: Result<Decimal, string> = numerator.div(divisor, 2)
    15. match (result) {
    16. case Err(message) => io.writeLine(message)
    17. case Ok(_) => io.writeLine("accepted")
    18. }
    19. }
    20. io.writeLine(divisor.toString())
    Expected outputexit 0
    Decimal.div: division by zero
Decimal.div: division by zero
0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. Decimal.div: division by zero
    2. Decimal.div: division by zero
    3. 0

    This exact example has not been executed.

    Source evidence

    Keep a zero quotient at the largest valid scale

    Link

    run · running · Verification: not-run

    main.tpzKeep a zero quotient at the largest valid scaleOpen 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 divisor: Decimal = read("0.1")
    12. let result: Result<Decimal, string> = (0).toDecimal().div(divisor, 4294967295)
    13. match (result) {
    14. case Ok(value) => io.writeLine(value.toString())
    15. case Err(_) => io.writeLine("unexpected error")
    16. }
    Expected outputexit 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. 0

    This exact example has not been executed.

    Source evidence

    Evaluate the receiver and division arguments once in order

    Link

    run · running · Verification: not-run

    main.tpzEvaluate the receiver and division arguments once in orderOpen in Playground
    1. import std.decimal { Decimal, RoundingMode }
    2. import std.test
    3. import std.io
    5. function receiver() -> Decimal {
    6. io.writeLine("receiver")
    7. return (6).toDecimal()
    8. }
    9. function divisor() -> Decimal {
    10. io.writeLine("divisor")
    11. return (4).toDecimal()
    12. }
    13. function scale() -> int {
    14. io.writeLine("scale")
    15. return 1
    16. }
    17. function mode() -> RoundingMode {
    18. io.writeLine("mode")
    19. return RoundingMode.HalfEven()
    20. }
    21. let result: Result<Decimal, string> = receiver().div(divisor(), scale(), mode())
    22. let value: Decimal = test.assertOk(result)
    23. io.writeLine(value.toString())
    Expected outputexit 0
    receiver
divisor
scale
mode
1.5
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. receiver
    2. divisor
    3. scale
    4. mode
    5. 1.5

    This exact example has not been executed.

    Source evidence

    Reject an invalid scale before classifying a zero divisor

    Link

    run · running · Verification: not-run

    main.tpzReject an invalid scale before classifying a zero divisorOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.io
    3. let value: Decimal = (1).toDecimal()
    4. value.div((0).toDecimal(), -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 an invalid scale before classifying a zero divisor

    Link

    run · running · Verification: not-run

    main.tpzReject an invalid scale before classifying a zero divisorOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.io
    3. let value: Decimal = (1).toDecimal()
    4. value.div((0).toDecimal(), 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