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.bigint

    BigInt.mod

    Return the remainder associated with division toward zero.

    mod(other: BigInt) -> Result<BigInt, string>
    Receiver
    BigInt
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.bigint in language mode 5.21.

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

    Source evidence

    Receiver

    BigInt

    Parameter constraints

    Additional contracts are Pending.

    For a nonzero divisor, BigInt.div returns Ok containing the exact integer quotient truncated toward zero.

    BigInt.mod returns Ok containing the remainder left by that quotient. For dividend a and divisor b, the values satisfy a = quotient * b + remainder. A nonzero remainder has the sign of the dividend and a magnitude smaller than the divisor magnitude.

    A zero dividend and nonzero divisor produce a zero quotient and zero remainder. A negative divisor changes the quotient sign and does not choose the remainder sign.

    A zero divisor makes either operation return Err containing a descriptive nonempty string. The string has no stable machine readable format. The operation does not raise a division fault for this input.

    Quotients and remainders are BigInt values. Division has no signed 64 bit overflow boundary and does not convert an operand to int.

    The receiver is evaluated before the divisor and each is evaluated once. An earlier fault prevents later evaluation. The operations leave both values unchanged and have no external effects.

    Use div and mod for BigInt division and remainder. The language arithmetic operators on BigInt provide addition, subtraction, and multiplication.

    Related rule: Divide exact integers toward zero

    Result

    Additional contracts are Pending.

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

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    A nonzero remainder has the dividend sign. A zero divisor returns Err containing diagnostic text.

    Resolved contracts

    Link

    Related entries

    Link

    std.bigint

    Divide exact integers toward zero

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

    Divide exact integers toward zero

    For a nonzero divisor, BigInt.div returns Ok containing the exact integer quotient truncated toward zero.

    BigInt.mod returns Ok containing the remainder left by that quotient. For dividend a and divisor b, the values satisfy a = quotient * b + remainder. A nonzero remainder has the sign of the dividend and a magnitude smaller than the divisor magnitude.

    A zero dividend and nonzero divisor produce a zero quotient and zero remainder. A negative divisor changes the quotient sign and does not choose the remainder sign.

    A zero divisor makes either operation return Err containing a descriptive nonempty string. The string has no stable machine readable format. The operation does not raise a division fault for this input.

    Quotients and remainders are BigInt values. Division has no signed 64 bit overflow boundary and does not convert an operand to int.

    The receiver is evaluated before the divisor and each is evaluated once. An earlier fault prevents later evaluation. The operations leave both values unchanged and have no external effects.

    Use div and mod for BigInt division and remainder. The language arithmetic operators on BigInt provide addition, subtraction, and multiplication.

    Why

    Truncating the quotient toward zero keeps signed division aligned with int arithmetic. Returning Err for a zero divisor gives exact integer calculations a recoverable failure value.

    Examples Keep quotient and remainder signs explicitHandle a zero divisor as a Result errorEvaluate the receiver before the divisor

    Source evidence

    Keep quotient and remainder signs explicit

    Link

    run · running · Verification: not-run

    main.tpzKeep quotient and remainder signs explicitOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.test
    3. import std.io
    5. function divide(left: string, right: string) -> () {
    6. let a = test.assertSome(BigInt.parse(left, 10))
    7. let b = test.assertSome(BigInt.parse(right, 10))
    8. let quotient = test.assertOk(a.div(b))
    9. let remainder = test.assertOk(a.mod(b))
    10. io.writeLine(quotient.toString(10) + " " + remainder.toString(10))
    11. }
    12. divide("7", "3")
    13. divide("-7", "3")
    14. divide("7", "-3")
    15. divide("-7", "-3")
    16. divide("2", "7")
    17. divide("0", "-3")
    18. divide("-9223372036854775808", "-1")
    Expected outputexit 0
    2 1
-2 -1
-2 1
2 -1
0 2
0 0
9223372036854775808 0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 2 1
    2. -2 -1
    3. -2 1
    4. 2 -1
    5. 0 2
    6. 0 0
    7. 9223372036854775808 0

    This exact example has not been executed.

    Source evidence

    Handle a zero divisor as a Result error

    Link

    run · running · Verification: not-run

    main.tpzHandle a zero divisor as a Result errorOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.test
    3. import std.io
    5. let value = test.assertSome(BigInt.parse("7", 10))
    6. let zero = test.assertSome(BigInt.parse("0", 10))
    7. match (value.div(zero)) {
    8. case Err(_) => io.writeLine("division rejected")
    9. case Ok(_) => io.writeLine("accepted")
    10. }
    11. match (value.mod(zero)) {
    12. case Err(_) => io.writeLine("remainder rejected")
    13. case Ok(_) => io.writeLine("accepted")
    14. }
    15. io.writeLine(value.toString(10))
    16. io.writeLine(zero.toString(10))
    Expected outputexit 0
    division rejected
remainder rejected
7
0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. division rejected
    2. remainder rejected
    3. 7
    4. 0

    This exact example has not been executed.

    Source evidence

    Evaluate the receiver before the divisor

    Link

    run · running · Verification: not-run

    main.tpzEvaluate the receiver before the divisorOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.test
    3. import std.io
    5. function receiver() -> BigInt {
    6. io.writeLine("receiver")
    7. return test.assertSome(BigInt.parse("7", 10))
    8. }
    9. function divisor() -> BigInt {
    10. io.writeLine("divisor")
    11. return test.assertSome(BigInt.parse("3", 10))
    12. }
    13. let quotient = test.assertOk(receiver().div(divisor()))
    14. io.writeLine(quotient.toString(10))
    Expected outputexit 0
    receiver
divisor
2
    $ 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. 2

    This exact example has not been executed.

    Source evidence

    Menu

    Download