Standard Library: std.compress
● Intermediate5 min
Every type, method and function of std.compress: what the spec lists, then each declaration in its source, with its examples and the line that declares it.
Spec 14.21 · learn it in Compression.
A declaration below shows what a program writes against: a type's fields, a function's parameters, what it gives, its contracts (require, ensure) and its examples. kavach test runs every example, so each one is true of the code.
What the spec lists
| Function | Gives |
|---|---|
compress.encode(data, format, level: none) -> Bytes | data (Bytes) compressed in format, at level, or the format's usual level when none |
compress.decode(data, format, most: 64_000_000) -> Bytes ! CompressError | The bytes data holds, which must be in format; at most most of them |
compress.level_fits(format, level) -> Bool | Whether level is one of format's levels (below); none always is |
compress.from_name(name) -> Format? | The format a name in an HTTP header stands for: gzip (or x-gzip), deflate, zstd, br or lz4, in any case; none for any other |
format.name() -> String | The format's name in a header: Format.Brotli.name() is br |
Format is Gzip | Deflate | Zstd | Brotli | Lz4. Each format has its own levels; a higher one is smaller and slower:
Format | Levels | Usual level |
|---|---|---|
Gzip, Deflate | 0 (stored, not compressed) to 9 | 6 |
Zstd | 1 to 22 | 3 |
Brotli | 0 to 11 | 5 |
Lz4 | one level: level must be none or 0 | 0 |
Decoding stops at most bytes, 64 MB unless the call says otherwise. A small input can expand to gigabytes (a "zip bomb"); past most, decoding fails with TooLarge instead of filling memory. The errors:
CompressError | When |
|---|---|
TooLarge(most: Int) | The data holds more than most bytes |
Corrupt(reason: String) | The data isn't in format, or was cut short |
std.compress · compress.kav
use std.compress: 2 types and 4 functions. stdlib/compress/compress.kav
Format type
A way of compressing, as HTTP's content-encoding names them.
pub type Format = Gzip | Deflate | Zstd | Brotli | Lz4name method
The format's name in an HTTP header: gzip, deflate, zstd, br or lz4.
pub fn name(self) -> String
example Format.Brotli.name() == "br"CompressError type
Why data couldn't be decoded: it holds more than most bytes, or it isn't in the format, or was cut short.
pub type CompressError = TooLarge(most: Int) | Corrupt(reason: String)level_fits function
Whether level is one of format's levels; none, the usual one, always is.
pub fn level_fits(format: Format, level: Int?) -> Bool
example level_fits(Format.Gzip, 9)
example not level_fits(Format.Gzip, 12)
example level_fits(Format.Lz4, none)encode function
data compressed in format, at level or the format's usual one.
pub fn encode(data: Bytes, format: Format, level: Int? = none) -> Bytes
require level_fits(format, level)
ensure result.len() > 0decode function
The bytes data holds in format; at most most of them.
pub fn decode(data: Bytes, format: Format, most: Int = 64_000_000) -> Bytes ! CompressError
require most >= 0
ensure result.len() <= mostfrom_name function
The format name stands for in an HTTP header, none for any other.
pub fn from_name(name: String) -> Format?
example from_name(" BR ") == Format.Brotli
example from_name("compress") == none