Function zstd_sys::ZSTD_getBlockSize

source · 
pub unsafe extern "C" fn ZSTD_getBlockSize(
    cctx: *const ZSTD_CCtx,
) -> usize
Expand description

This API is deprecated in favor of the regular compression API. You can get the frame header down to 2 bytes by setting:

  • ZSTD_c_format = ZSTD_f_zstd1_magicless
  • ZSTD_c_contentSizeFlag = 0
  • ZSTD_c_checksumFlag = 0
  • ZSTD_c_dictIDFlag = 0

This API is not as well tested as our normal API, so we recommend not using it. We will be removing it in a future version. If the normal API doesn’t provide the functionality you need, please open a GitHub issue.

Block functions produce and decode raw zstd blocks, without frame metadata. Frame metadata cost is typically ~12 bytes, which can be non-negligible for very small blocks (< 100 bytes). But users will have to take in charge needed metadata to regenerate data, such as compressed and content sizes.

A few rules to respect :

  • Compressing and decompressing require a context structure
  • Use ZSTD_createCCtx() and ZSTD_createDCtx()
  • It is necessary to init context before starting
  • compression : any ZSTD_compressBegin*() variant, including with dictionary
  • decompression : any ZSTD_decompressBegin*() variant, including with dictionary
  • Block size is limited, it must be <= ZSTD_getBlockSize() <= ZSTD_BLOCKSIZE_MAX == 128 KB
  • If input is larger than a block size, it’s necessary to split input data into multiple blocks
  • For inputs larger than a single block, consider using regular ZSTD_compress() instead. Frame metadata is not that costly, and quickly becomes negligible as source size grows larger than a block.
  • When a block is considered not compressible enough, ZSTD_compressBlock() result will be 0 (zero) ! ===> In which case, nothing is produced into dst !
  • User must test for such outcome and deal directly with uncompressed data
  • A block cannot be declared incompressible if ZSTD_compressBlock() return value was != 0. Doing so would mess up with statistics history, leading to potential data corruption.
  • ZSTD_decompressBlock() doesn’t accept uncompressed data as input !!
  • In case of multiple successive blocks, should some of them be uncompressed, decoder must be informed of their existence in order to follow proper history. Use ZSTD_insertBlock() for such a case.