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

    Format an exact integer as lowercase digits in the selected radix.

    toString(radix: int) -> 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.

    BigInt represents signed integers without a fixed bit width. Its text operations preserve the exact integer value and do not use a locale.

    BigInt.parse takes a radix from 2 through 36. Text consists of an optional minus sign followed by at least one ASCII digit or lowercase ASCII letter. Letters a through z have digit values 10 through 35. Every digit must be smaller than the radix.

    Leading zero digits are accepted. Negative zero produces the same zero value as 0. Parsing does not trim whitespace, accept a plus sign, accept uppercase letters, accept separators, or interpret a radix prefix. Characters are interpreted as ordinary digits of the supplied radix.

    Valid text returns Some containing the exact integer. Empty text, a sign without digits, an invalid digit, any extra character, or a radix outside the allowed range returns None(). These input failures do not raise a runtime fault.

    BigInt.toString takes a radix from 2 through 36 and returns lowercase ASCII digits in that radix. A negative nonzero value starts with a minus sign. The output has no radix prefix or leading zero digits. Zero is written as 0.

    An invalid BigInt.toString radix raises TPZ5001 during execution. It does not select a default radix or return empty text.

    Formatting a value and parsing the result with the same radix recovers that value. Parsing and formatting accepted text produces its canonical spelling in the selected radix.

    The receiver and positional arguments are evaluated once in source order before the operation validates their values. An earlier fault prevents later evaluation. The operations do not change their inputs or perform external effects.

    Related rule: Read and write integers in an explicit radix

    Result

    Additional contracts are Pending.

    The declared result type is string.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Radices from 2 through 36 produce a canonical sign and digit sequence. An invalid radix raises TPZ5001.

    Resolved contracts

    Link

    Related entries

    Link

    std.bigint

    Read and write integers in an explicit radix

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

    Read and write integers in an explicit radix

    BigInt represents signed integers without a fixed bit width. Its text operations preserve the exact integer value and do not use a locale.

    BigInt.parse takes a radix from 2 through 36. Text consists of an optional minus sign followed by at least one ASCII digit or lowercase ASCII letter. Letters a through z have digit values 10 through 35. Every digit must be smaller than the radix.

    Leading zero digits are accepted. Negative zero produces the same zero value as 0. Parsing does not trim whitespace, accept a plus sign, accept uppercase letters, accept separators, or interpret a radix prefix. Characters are interpreted as ordinary digits of the supplied radix.

    Valid text returns Some containing the exact integer. Empty text, a sign without digits, an invalid digit, any extra character, or a radix outside the allowed range returns None(). These input failures do not raise a runtime fault.

    BigInt.toString takes a radix from 2 through 36 and returns lowercase ASCII digits in that radix. A negative nonzero value starts with a minus sign. The output has no radix prefix or leading zero digits. Zero is written as 0.

    An invalid BigInt.toString radix raises TPZ5001 during execution. It does not select a default radix or return empty text.

    Formatting a value and parsing the result with the same radix recovers that value. Parsing and formatting accepted text produces its canonical spelling in the selected radix.

    The receiver and positional arguments are evaluated once in source order before the operation validates their values. An earlier fault prevents later evaluation. The operations do not change their inputs or perform external effects.

    Why

    An explicit radix gives each digit one value. Strict input spelling makes accidental whitespace and alternate signs visible to the caller. Canonical output gives stored integer text a predictable form without a locale dependency.

    Examples Parse and format exact integers in explicit radicesReturn None for malformed or out of radix digitsReject parse radices outside two through thirty sixReject surrounding whitespace in integer textReject a leading plus sign in integer textReject uppercase letters in integer textEvaluate parse arguments before validating their valuesReject a formatting radix outside the valid rangeReject a formatting radix outside the valid range

    Diagnostics TPZ5001

    Source evidence

    Parse and format exact integers in explicit radices

    Link

    run · running · Verification: not-run

    main.tpzParse and format exact integers in explicit radicesOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.test
    3. import std.io
    5. let number = test.assertSome(BigInt.parse("ff", 16))
    6. io.writeLine(number.toString(2))
    7. io.writeLine(number.toString(10))
    8. io.writeLine(number.toString(16))
    9. io.writeLine(test.assertSome(BigInt.parse("z", 36)).toString(10))
    10. io.writeLine(test.assertSome(BigInt.parse("-00015", 10)).toString(16))
    11. io.writeLine(test.assertSome(BigInt.parse("-000", 10)).toString(36))
    12. io.writeLine(test.assertSome(BigInt.parse("123456789012345678901234567890", 10)).toString(10))
    Expected outputexit 0
    11111111
255
ff
35
-f
0
123456789012345678901234567890
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 11111111
    2. 255
    3. ff
    4. 35
    5. -f
    6. 0
    7. 123456789012345678901234567890

    This exact example has not been executed.

    Source evidence

    Return None for malformed or out of radix digits

    Link

    run · running · Verification: not-run

    main.tpzReturn None for malformed or out of radix digitsOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.io
    4. for text in (["", "-", "1_0", "0x10", "g", "１２", "1\n2"]) {
    5. match (BigInt.parse(text, 16)) {
    6. case None() => io.writeLine("rejected")
    7. case Some(_) => io.writeLine("accepted")
    8. }
    9. }
    10. match (BigInt.parse("2", 2)) {
    11. case None() => io.writeLine("digit rejected")
    12. case Some(_) => io.writeLine("accepted")
    13. }
    Expected outputexit 0
    rejected
rejected
rejected
rejected
rejected
rejected
rejected
digit rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. rejected
    2. rejected
    3. rejected
    4. rejected
    5. rejected
    6. rejected
    7. rejected
    8. digit rejected

    This exact example has not been executed.

    Source evidence

    Reject parse radices outside two through thirty six

    Link

    run · running · Verification: not-run

    main.tpzReject parse radices outside two through thirty sixOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.io
    4. for radix in ([-1, 0, 1, 37, 9223372036854775807]) {
    5. match (BigInt.parse("10", radix)) {
    6. case None() => io.writeLine("radix rejected")
    7. case Some(_) => io.writeLine("accepted")
    8. }
    9. }
    Expected outputexit 0
    radix rejected
radix rejected
radix rejected
radix rejected
radix rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. radix rejected
    2. radix rejected
    3. radix rejected
    4. radix rejected
    5. radix rejected

    This exact example has not been executed.

    Source evidence

    Reject surrounding whitespace in integer text

    Link

    run · running · Verification: not-run

    main.tpzReject surrounding whitespace in integer textOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.io
    4. match (BigInt.parse(" 10 ", 10)) {
    5. case None() => io.writeLine("whitespace rejected")
    6. case Some(_) => io.writeLine("accepted")
    7. }
    Expected outputexit 0
    whitespace rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. whitespace rejected

    This exact example has not been executed.

    Source evidence

    Reject a leading plus sign in integer text

    Link

    run · running · Verification: not-run

    main.tpzReject a leading plus sign in integer textOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.io
    4. match (BigInt.parse("+10", 10)) {
    5. case None() => io.writeLine("plus rejected")
    6. case Some(_) => io.writeLine("accepted")
    7. }
    Expected outputexit 0
    plus rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. plus rejected

    This exact example has not been executed.

    Source evidence

    Reject uppercase letters in integer text

    Link

    run · running · Verification: not-run

    main.tpzReject uppercase letters in integer textOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.io
    4. match (BigInt.parse("FF", 16)) {
    5. case None() => io.writeLine("uppercase rejected")
    6. case Some(_) => io.writeLine("accepted")
    7. }
    Expected outputexit 0
    uppercase rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. uppercase rejected

    This exact example has not been executed.

    Source evidence

    Evaluate parse arguments before validating their values

    Link

    run · running · Verification: not-run

    main.tpzEvaluate parse arguments before validating their valuesOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.io
    4. function text() -> string {
    5. io.writeLine("text")
    6. return "bad"
    7. }
    8. function radix() -> int {
    9. io.writeLine("radix")
    10. return 10
    11. }
    12. match (BigInt.parse(text(), radix())) {
    13. case None() => io.writeLine("rejected")
    14. case Some(_) => io.writeLine("accepted")
    15. }
    Expected outputexit 0
    text
radix
rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. text
    2. radix
    3. rejected

    This exact example has not been executed.

    Source evidence

    Reject a formatting radix outside the valid range

    Link

    run · running · Verification: not-run

    main.tpzReject a formatting radix outside the valid rangeOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.test
    3. import std.io
    4. let number: BigInt = test.assertSome(BigInt.parse("1", 10))
    5. number.toString(1)
    6. 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-bigint-radix at main.tpz:5:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject a formatting radix outside the valid range

    Link

    run · running · Verification: not-run

    main.tpzReject a formatting radix outside the valid rangeOpen in Playground
    1. import std.bigint { BigInt }
    2. import std.test
    3. import std.io
    4. let number: BigInt = test.assertSome(BigInt.parse("1", 10))
    5. number.toString(37)
    6. 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-bigint-radix at main.tpz:5:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Runtime value guard

    Menu

    Download