Files
wuffs/doc/std/compression-encoders.md
T
Claude 7d58caf91c Merge claude/project-thread-0izcgq (large window at qualities 3 to 9)
Put the q10/q11 variable region before the ring buffer (now the last
region), growing it (and moving the ring buffer) at the first
transform_io call to use a workbuf longer than workbuf_len's minimum.
Large window now also works at qualities 10 and 11.
2026-10-27 04:46:52 +00:00

2.0 KiB

Compression Encoders

Compression encoders read from one input stream (an io_reader called src) and write to an output stream (an io_writer called dst). Like compression decoders, they implement the base.io_transformer interface, whose key method is transform_io. It incrementally compresses the source data.

This method is a coroutine, and does not require either all of the input or all of the output to fit in a single contiguous buffer. It suspends with the $short_read status when it has consumed all of src (and src is not closed) and with $short_write when dst is full. It returns ok once src is closed and all of the compressed data has been written. Encoder parameters (e.g. the compression quality) are set with set_quirk before the first transform_io call.

API Listing

In Wuffs syntax, the base.io_transformer methods are:

  • dst_history_retain_length() u64
  • get_quirk(key: u32) u64
  • set_quirk!(key: u32, value: u64) status
  • transform_io?(dst: io_writer, src: io_reader, workbuf: slice u8)
  • workbuf_len() range_ii_u64

A workbuf of workbuf_len().max_incl bytes always suffices. Some encoders (e.g. brotli at qualities 10 and 11) have a smaller min_incl, which is enough for realistic inputs: with a workbuf shorter than max_incl, an unusual input can make transform_io return "#bad workbuf length".

Encoders may have further, format-specific methods. For example, the brotli encoder has request_flush, request_emit_metadata and max_compressed_size.

Implementations

  • std/brotli (qualities 0 to 11, without encoder dictionaries, including large-window brotli, with windows of up to 1 GiB, at qualities 3 to 11). Its workbuf_len is the worst case for the parameters (more than 2 GiB for large-window brotli at lgwin 30; at qualities 10 and 11, min_incl is a smaller practical bound), but a shorter workbuf works for short inputs: see the README's "Encoder Workbuf Layout" section.