Skip to content

Commit d734de1

Browse files
committed
[doc] Clarify requirements around Block_Maximum_Size in spec
Clarify that it is legal to send compressed blocks that are larger than the uncompressed size so long as their `Block_Content` is no larger than `Block_Maximum_Size`. See #4667
1 parent 6e1e545 commit d734de1

1 file changed

Lines changed: 11 additions & 6 deletions

File tree

doc/zstd_compression_format.md

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Distribution of this document is unlimited.
1616

1717
### Version
1818

19-
0.4.4 (2025-03-22)
19+
0.4.5 (2026-05-14)
2020

2121

2222
Introduction
@@ -387,20 +387,24 @@ When `Block_Type` is `RLE_Block`, since `Block_Content`’s size is always 1,
387387

388388
__`Block_Content`__ and __`Block_Maximum_Size`__
389389

390-
The size of `Block_Content` is limited by `Block_Maximum_Size`,
391-
which is the smallest of:
390+
The size of `Block_Content` is limited by `Block_Maximum_Size`, which is
391+
determined once for a given frame and is the smallest of:
392392
- `Window_Size`
393393
- 128 KiB (131.072 bytes)
394394

395-
`Block_Maximum_Size` is constant for a given frame.
396-
This maximum is applicable to both the decompressed size
397-
and the compressed size of any block in the frame.
395+
Both the `Block_Content` and the decompressed size of any block in the frame must
396+
be no larger than `Block_Maximum_Size`.
398397

399398
The reasoning for this limit is that a decoder can read this information
400399
at the beginning of a frame and use it to allocate buffers.
401400
The guarantees on the size of blocks ensure that
402401
the buffers will be large enough for any following block of the valid frame.
403402

403+
If a compressed block is larger than its uncompressed content, it is recommended
404+
to send it uncompressed (i.e., a `Raw_Block`). However, as long as
405+
`Block_Content` is no larger than `Block_Maximum_Size`, it is legal to send such
406+
a compressed block, even if it's larger than its uncompressed content.
407+
404408

405409
Compressed Blocks
406410
-----------------
@@ -1742,6 +1746,7 @@ or at least provide a meaningful error code explaining for which reason it canno
17421746

17431747
Version changes
17441748
---------------
1749+
- 0.4.5 : minor clarification regarding Block_Maximum_Size
17451750
- 0.4.4 : minor clarification for block size
17461751
- 0.4.3 : clarifications for Huffman prefix code assignment example
17471752
- 0.4.2 : refactor FSE table construction process, inspired by Donald Pian

0 commit comments

Comments
 (0)