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

    Bytes.toHex

    Encodes this byte sequence as hexadecimal text.

    toHex() -> string
    Module
    std.bytes
    Receiver
    Bytes
    Minimum arity
    0
    Maximum arity
    0

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.bytes in language mode 5.21.

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

    Source evidence

    Receiver

    Bytes

    Parameter constraints

    Additional contracts are Pending.

    Bytes.toHex emits two lowercase ASCII hexadecimal digits per byte with the high nibble first. Empty Bytes produces an empty string.

    Bytes.fromHex accepts an even number of digits drawn from 0 through 9 and a through f. Empty text returns Ok with empty Bytes.

    Uppercase letters, prefixes, separators, whitespace, non-ASCII characters, and an odd digit count return Err with a string describing invalid hex input.

    Decoding returns the entire byte sequence in Ok or an error with no decoded prefix. It never mutates an input value.

    Encoding then decoding recovers the bytes exactly. Decoding then encoding preserves every accepted input spelling.

    The input expression evaluates once. These conversions perform no I/O and do not apply Unicode normalization.

    Related rule: Use a canonical hexadecimal spelling

    Result

    Additional contracts are Pending.

    The declared result type is string.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Emit two lowercase hexadecimal digits per byte with no prefix or separators.

    Resolved contracts

    Link

    Related entries

    Link

    std.bytes

    Use a canonical hexadecimal spelling

    Link
    Ruletopaz.stdlib.contract.bytes-hex.rule

    Use a canonical hexadecimal spelling

    Bytes.toHex emits two lowercase ASCII hexadecimal digits per byte with the high nibble first. Empty Bytes produces an empty string.

    Bytes.fromHex accepts an even number of digits drawn from 0 through 9 and a through f. Empty text returns Ok with empty Bytes.

    Uppercase letters, prefixes, separators, whitespace, non-ASCII characters, and an odd digit count return Err with a string describing invalid hex input.

    Decoding returns the entire byte sequence in Ok or an error with no decoded prefix. It never mutates an input value.

    Encoding then decoding recovers the bytes exactly. Decoding then encoding preserves every accepted input spelling.

    The input expression evaluates once. These conversions perform no I/O and do not apply Unicode normalization.

    Why

    One accepted hexadecimal spelling makes serialized byte text stable for comparison and reproduction. Data that uses another spelling can be normalized explicitly before decoding.

    Examples Decode byte pairs and emit lowercase textReject malformed hexadecimal stringsReject uppercase hexadecimal input

    Source evidence

    Decode byte pairs and emit lowercase text

    Link

    run · running · Verification: not-run

    main.tpzDecode byte pairs and emit lowercase textOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    3. import std.test
    5. io.writeLine(test.assertOk(Bytes.fromHex("")).toHex())
    6. io.writeLine(test.assertOk(Bytes.fromHex("000f80ff")).toHex())
    Expected outputexit 0
    
000f80ff
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    2. 000f80ff

    This exact example has not been executed.

    Source evidence

    Reject malformed hexadecimal strings

    Link

    run · running · Verification: not-run

    main.tpzReject malformed hexadecimal stringsOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    4. for text in (["0", "gg", "0x00", "00 11", "００"]) {
    5. match (Bytes.fromHex(text)) {
    6. case Err(_) => io.writeLine("invalid hex")
    7. case Ok(_) => io.writeLine("accepted")
    8. }
    9. }
    Expected outputexit 0
    invalid hex
invalid hex
invalid hex
invalid hex
invalid hex
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. invalid hex
    2. invalid hex
    3. invalid hex
    4. invalid hex
    5. invalid hex

    This exact example has not been executed.

    Source evidence

    Reject uppercase hexadecimal input

    Link

    run · running · Verification: not-run

    main.tpzReject uppercase hexadecimal inputOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    4. match (Bytes.fromHex("CAfe")) {
    5. case Err(_) => io.writeLine("uppercase rejected")
    6. case Ok(_) => 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

    Menu

    Download