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

    Compresses this byte sequence using Zstandard and the supplied level.

    zstdCompress(level: int = 3) -> Result<Bytes, string>
    Module
    std.bytes
    Receiver
    Bytes
    Minimum arity
    0
    Maximum arity
    1

    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.zstdCompress accepts an int level from 1 through 22. The default is 3 and other values return Err with a string.

    The level is a compression effort hint. The API does not promise a size ratio, execution time, or different bytes for every pair of levels.

    A successful call returns Ok with one RFC 8878 frame requiring no external dictionary. Empty input is valid.

    Bytes.zstdDecompress accepts one standard frame containing raw, RLE, or compressed blocks, with valid frame parameters and an optional content checksum.

    A frame requiring an unavailable dictionary, a malformed header or block, a size or checksum mismatch, and truncation return Err with a string.

    Skippable frames, additional frames, and other trailing bytes return Err. The entire input must represent one data frame.

    Decompression returns all uncompressed bytes in Ok or an error without a partial output. Compressing then decompressing preserves the input bytes.

    The receiver and explicit level expression evaluate once in that order. The input remains unchanged and the operation performs no I/O.

    Related rule: Use Zstandard frames and explicit effort levels

    Result

    Additional contracts are Pending.

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

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Return one Zstandard frame in Ok. The level ranges from 1 through 22 and defaults to 3.

    Resolved contracts

    Link

    Related entries

    Link

    std.bytes

    Use Zstandard frames and explicit effort levels

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

    Use Zstandard frames and explicit effort levels

    Bytes.zstdCompress accepts an int level from 1 through 22. The default is 3 and other values return Err with a string.

    The level is a compression effort hint. The API does not promise a size ratio, execution time, or different bytes for every pair of levels.

    A successful call returns Ok with one RFC 8878 frame requiring no external dictionary. Empty input is valid.

    Bytes.zstdDecompress accepts one standard frame containing raw, RLE, or compressed blocks, with valid frame parameters and an optional content checksum.

    A frame requiring an unavailable dictionary, a malformed header or block, a size or checksum mismatch, and truncation return Err with a string.

    Skippable frames, additional frames, and other trailing bytes return Err. The entire input must represent one data frame.

    Decompression returns all uncompressed bytes in Ok or an error without a partial output. Compressing then decompressing preserves the input bytes.

    The receiver and explicit level expression evaluate once in that order. The input remains unchanged and the operation performs no I/O.

    Why

    A bounded level range keeps calls portable. A complete frame boundary and explicit dictionary failure make the returned bytes independent of hidden decoder state.

    Examples Use the default and both supported level boundariesDecode a valid Zstandard RLE blockDecode short nonfinal Zstandard raw blocksReject missing block data and trailing bytes

    Source evidence

    Use the default and both supported level boundaries

    Link

    run · running · Verification: not-run

    main.tpzUse the default and both supported level boundariesOpen in Playground
    1. import std.io
    2. import std.test
    4. let source = "hello".encodeUtf8()
    5. io.writeLine(test.assertOk(test.assertOk(source.zstdCompress()).zstdDecompress()).toHex())
    6. for level in ([1, 22]) {
    7. io.writeLine(test.assertOk(test.assertOk(source.zstdCompress(level)).zstdDecompress()).toHex())
    8. }
    9. for level in ([0, 23]) {
    10. match (source.zstdCompress(level)) {
    11. case Err(_) => io.writeLine("invalid level")
    12. case Ok(_) => io.writeLine("accepted")
    13. }
    14. }
    Expected outputexit 0
    68656c6c6f
68656c6c6f
68656c6c6f
invalid level
invalid level
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 68656c6c6f
    2. 68656c6c6f
    3. 68656c6c6f
    4. invalid level
    5. invalid level

    This exact example has not been executed.

    Source evidence

    Decode a valid Zstandard RLE block

    Link

    run · running · Verification: not-run

    main.tpzDecode a valid Zstandard RLE blockOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    3. import std.test
    5. let encoded = test.assertOk(Bytes.fromHex("28b52ffd20052b000041"))
    6. match (encoded.zstdDecompress()) {
    7. case Ok(bytes) => io.writeLine(bytes.toHex())
    8. case Err(_) => io.writeLine("rejected")
    9. }
    Expected outputexit 0
    4141414141
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 4141414141

    This exact example has not been executed.

    Source evidence

    Decode short nonfinal Zstandard raw blocks

    Link

    run · running · Verification: not-run

    main.tpzDecode short nonfinal Zstandard raw blocksOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    3. import std.test
    5. let encoded = test.assertOk(Bytes.fromHex("28b52ffd20020800004109000042"))
    6. match (encoded.zstdDecompress()) {
    7. case Ok(bytes) => io.writeLine(bytes.toHex())
    8. case Err(_) => io.writeLine("rejected")
    9. }
    Expected outputexit 0
    4142
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 4142

    This exact example has not been executed.

    Source evidence

    Reject missing block data and trailing bytes

    Link

    run · running · Verification: not-run

    main.tpzReject missing block data and trailing bytesOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    3. import std.test
    5. for hex in (["", "28b52ffd20052900006869", "28b52ffd200001000000"]) {
    6. match (test.assertOk(Bytes.fromHex(hex)).zstdDecompress()) {
    7. case Err(_) => io.writeLine("invalid Zstandard")
    8. case Ok(_) => io.writeLine("accepted")
    9. }
    10. }
    Expected outputexit 0
    invalid Zstandard
invalid Zstandard
invalid Zstandard
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. invalid Zstandard
    2. invalid Zstandard
    3. invalid Zstandard

    This exact example has not been executed.

    Source evidence

    Menu

    Download