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

    Convert an exact integral Decimal within the signed int range.

    toInt() -> Option<int>
    Receiver
    Decimal
    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

    Decimal

    Parameter constraints

    Additional contracts are Pending.

    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.

    Related rule: Convert numeric values explicitly and without truncation

    Result

    Additional contracts are Pending.

    The declared result type is Option<int>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Return Some for an integral value from -9223372036854775808 through 9223372036854775807. Return None() for a fraction or a value outside that range without changing the receiver.

    Why

    Link

    Checked narrowing preserves the value instead of choosing a rounding or overflow policy implicitly.

    Resolved contracts

    Link

    Related entries

    Link

    std.decimal

    Convert numeric values explicitly and without truncation

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

    Convert numeric values explicitly and without truncation

    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.

    Why

    Exact integer conversion and checked narrowing communicate different intentions. Option exposes fractions and overflow without selecting a rounding policy for the caller. Explicit text composition handles arbitrary precision integer exchange through the existing parsers without adding another conversion API.

    Examples Convert both int endpoints and reject fractions or overflowConvert int values to exact scale zero decimalsExchange arbitrary precision integers through explicit decimal text

    Source evidence

    Convert both int endpoints and reject fractions or overflow

    Link

    run · running · Verification: not-run

    main.tpzConvert both int endpoints and reject fractions or overflowOpen 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. for text in (["-9223372036854775808", "9223372036854775807", "-9223372036854775809", "9223372036854775808", "1.000", "1.001", "-1.001", "-0.000"]) {
    12. let value: Decimal = read(text)
    13. match (value.toInt()) {
    14. case Some(integer) => io.writeLine("{integer}")
    15. case None() => io.writeLine("not an int")
    16. }
    17. }
    18. let large: Decimal = read("1000000000000000000000000000000")
    19. let narrowed: Option<int> = large.toInt()
    20. test.assertNone(narrowed)
    21. io.writeLine(large.toString())
    Expected outputexit 0
    -9223372036854775808
9223372036854775807
not an int
not an int
1
not an int
not an int
0
1000000000000000000000000000000
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. -9223372036854775808
    2. 9223372036854775807
    3. not an int
    4. not an int
    5. 1
    6. not an int
    7. not an int
    8. 0
    9. 1000000000000000000000000000000

    This exact example has not been executed.

    Source evidence

    Convert int values to exact scale zero decimals

    Link

    run · running · Verification: not-run

    main.tpzConvert int values to exact scale zero decimalsOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.test
    3. import std.io
    5. let integers: Array<int> = [-9223372036854775807 - 1, -1, 0, 1, 9223372036854775807]
    6. for integer in (integers) {
    7. let value: Decimal = integer.toDecimal()
    8. let narrowed: Option<int> = value.toInt()
    9. let recovered: int = test.assertSome(narrowed)
    10. test.assertEq(recovered, integer)
    11. io.writeLine("{value.toString()} {value.scale()}")
    12. }
    Expected outputexit 0
    -9223372036854775808 0
-1 0
0 0
1 0
9223372036854775807 0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. -9223372036854775808 0
    2. -1 0
    3. 0 0
    4. 1 0
    5. 9223372036854775807 0

    This exact example has not been executed.

    Source evidence

    Exchange arbitrary precision integers through explicit decimal text

    Link

    run · running · Verification: not-run

    main.tpzExchange arbitrary precision integers through explicit decimal textOpen in Playground
    1. import std.decimal { Decimal }
    2. import std.bigint { BigInt }
    3. import std.test
    4. import std.io
    6. let parsedInteger: Option<BigInt> = BigInt.parse("123456789012345678901234567890", 10)
    7. let integer: BigInt = test.assertSome(parsedInteger)
    8. let parsedDecimal: Option<Decimal> = Decimal.parse(integer.toString(10))
    9. let value: Decimal = test.assertSome(parsedDecimal)
    10. io.writeLine(value.toString())
    11. let parsedAgain: Option<BigInt> = BigInt.parse(value.toString(), 10)
    12. let recovered: BigInt = test.assertSome(parsedAgain)
    13. let equal = recovered == integer
    14. io.writeLine("{equal}")
    15. let parsedFraction: Option<Decimal> = Decimal.parse("1.5")
    16. let fraction: Decimal = test.assertSome(parsedFraction)
    17. let integral: Option<BigInt> = BigInt.parse(fraction.toString(), 10)
    18. match (integral) {
    19. case None() => io.writeLine("fraction rejected")
    20. case Some(_) => io.writeLine("converted")
    21. }
    Expected outputexit 0
    123456789012345678901234567890
true
fraction rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 123456789012345678901234567890
    2. true
    3. fraction rejected

    This exact example has not been executed.

    Source evidence

    Menu

    Download