packages/@greenpandastudios/aug-zlib/0.2.0/api.aug

Compression with zlib · Dependency source and specification

This is the exact dependency version used by this example.

Code

Indentation

// Generated by aug spec. This is a copy of the installed dependency source.
// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
import CompressionError from contracts
Explanation 1Explanation 2
extern C _compress(Bytes input) returns Bytes unless CompressionError
Explanation 1Explanation 2
extern C _decompress(Bytes input, int maximumOutput) returns Bytes unless CompressionError
/** Compress bytes with the standard zlib framing. */
Explanation 1Explanation 2
compress(Bytes input) returns Bytes:
    unsafe:
        return _compress(input)
/** Decompress at most maximumOutput bytes (maximum 256 MiB). */
Explanation 1Explanation 2
decompress(Bytes input, int maximumOutput) returns Bytes:
    unsafe:
        return _decompress(input, maximumOutput)
test compress:
    when "compression":
        it "preserves_bytes":
            Bytes input = "The world runs on language".bytes()
            Bytes packed = compress(input)
            Bytes restored = decompress(input=packed, maximumOutput=4096)
            assert(restored.text() == "The world runs on language")
        it "checks_output_limit":
            Bytes packed = compress(input="length limit".bytes())
            bool rejected = false
            try:
                decompress(input=packed, maximumOutput=1)
            catch CompressionError error:
                rejected = true
            assert(rejected)

Braces

// Generated by aug spec. This is a copy of the installed dependency source.
// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
import CompressionError from contracts
Explanation 1Explanation 2
extern C _compress(Bytes input) returns Bytes unless CompressionError
Explanation 1Explanation 2
extern C _decompress(Bytes input, int maximumOutput) returns Bytes unless CompressionError
/** Compress bytes with the standard zlib framing. */
Explanation 1Explanation 2
compress(Bytes input) returns Bytes {
    unsafe {
        return _compress(input)
    }
}
/** Decompress at most maximumOutput bytes (maximum 256 MiB). */
Explanation 1Explanation 2
decompress(Bytes input, int maximumOutput) returns Bytes {
    unsafe {
        return _decompress(input, maximumOutput)
    }
}
test compress {
    when "compression" {
        it "preserves_bytes" {
            Bytes input = "The world runs on language".bytes()
            Bytes packed = compress(input)
            Bytes restored = decompress(input=packed, maximumOutput=4096)
            assert(restored.text() == "The world runs on language")
        }
        it "checks_output_limit" {
            Bytes packed = compress(input="length limit".bytes())
            bool rejected = false
            try {
                decompress(input=packed, maximumOutput=1)
            }
            catch CompressionError error {
                rejected = true
            }
            assert(rejected)
        }
    }
}

Compiled specification

Interactions and sequences

compress · source

Compress bytes with the standard zlib framing. It takes input as Bytes. Failures can raise CompressionError.

Within an unsafe block, it returns _compress with input. Native operations must satisfy their declared C contracts. source

Checked interface

compress(Bytes input) returns Bytes unless CompressionError

It takes input as Bytes. Failures can raise CompressionError.

decompress · source

Decompress at most maximumOutput bytes (maximum 256 MiB). It takes input as Bytes and maximumOutput as an integer. Failures can raise CompressionError.

Within an unsafe block, it returns _decompress with input and maximumOutput. Native operations must satisfy their declared C contracts. source

Checked interface

decompress(Bytes input, int maximumOutput) returns Bytes unless CompressionError

It takes input as Bytes and maximumOutput as an integer. Failures can raise CompressionError.

_compress · source

It is private to its defining scope. It takes input as Bytes. It returns Bytes. Failures can raise CompressionError.

Native implementation: @greenpandastudios/aug-zlib@0.2.0, 1.3.2. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: native.abi.json (SHA-256 c3d4b36eadcccd13caff71597ed77a8e7307f0cfe3d13660a8e9127efe942b3d). It calls aug_zlib_compress_v1 through the C ABI on the caller thread; a blocking native call blocks that thread. August copies the returned buffer, then calls aug_zlib_release_v1 to release it. Its contract does not permit worker entry. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.

_decompress · source

It is private to its defining scope. It takes input as Bytes and maximumOutput as an integer. It returns Bytes. Failures can raise CompressionError.

Native implementation: @greenpandastudios/aug-zlib@0.2.0, 1.3.2. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: native.abi.json (SHA-256 c3d4b36eadcccd13caff71597ed77a8e7307f0cfe3d13660a8e9127efe942b3d). It calls aug_zlib_decompress_v1 through the C ABI on the caller thread; a blocking native call blocks that thread. August copies the returned buffer, then calls aug_zlib_release_v1 to release it. Its contract does not permit worker entry. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.

test compress · source

Tests compress. Each case gets fresh setup and dependencies.

compression

preserves_bytes · source

It sets input of type Bytes to bytes on "The world runs on language". It sets packed of type Bytes to compress with input. It sets restored of type Bytes to decompress with input from packed and maximumOutput 4096. The test requires restored.text equals "The world runs on language". source

checks_output_limit · source

It sets packed of type Bytes to compress with input from bytes on "length limit". It sets rejected to false. source

It tries to call decompress with input from packed and maximumOutput 1. If this work raises CompressionError, it sets rejected to true. The test requires rejected is true. source

Dependencies

It uses CompressionError from contracts.

Built-in operations follow the language reference.