Function zstd_sys::ZSTD_compressSequences

source · [−]
pub unsafe extern "C" fn ZSTD_compressSequences(
    cctx: *mut ZSTD_CCtx, 
    dst: *mut c_void, 
    dstSize: usize, 
    inSeqs: *const ZSTD_Sequence, 
    inSeqsSize: usize, 
    src: *const c_void, 
    srcSize: usize
) -> usize
Expand description

ZSTD_compressSequences() : Compress an array of ZSTD_Sequence, generated from the original source buffer, into dst. If a dictionary is included, then the cctx should reference the dict. (see: ZSTD_CCtx_refCDict(), ZSTD_CCtx_loadDictionary(), etc.) The entire source is compressed into a single frame.

The compression behavior changes based on cctx params. In particular: If ZSTD_c_blockDelimiters == ZSTD_sf_noBlockDelimiters, the array of ZSTD_Sequence is expected to contain no block delimiters (defined in ZSTD_Sequence). Block boundaries are roughly determined based on the block size derived from the cctx, and sequences may be split. This is the default setting.

If ZSTD_c_blockDelimiters == ZSTD_sf_explicitBlockDelimiters, the array of ZSTD_Sequence is expected to contain block delimiters (defined in ZSTD_Sequence). Behavior is undefined if no block delimiters are provided.

If ZSTD_c_validateSequences == 0, this function will blindly accept the sequences provided. Invalid sequences cause undefined behavior. If ZSTD_c_validateSequences == 1, then if sequence is invalid (see doc/zstd_compression_format.md for specifics regarding offset/matchlength requirements) then the function will bail out and return an error.

In addition to the two adjustable experimental params, there are other important cctx params.

  • ZSTD_c_minMatch MUST be set as less than or equal to the smallest match generated by the match finder. It has a minimum value of ZSTD_MINMATCH_MIN.
  • ZSTD_c_compressionLevel accordingly adjusts the strength of the entropy coder, as it would in typical compression.
  • ZSTD_c_windowLog affects offset validation: this function will return an error at higher debug levels if a provided offset is larger than what the spec allows for a given window log and dictionary (if present). See: doc/zstd_compression_format.md

Note: Repcodes are, as of now, always re-calculated within this function, so ZSTD_Sequence::rep is unused. Note 2: Once we integrate ability to ingest repcodes, the explicit block delims mode must respect those repcodes exactly, and cannot emit an RLE block that disagrees with the repcode history @return : final compressed size or a ZSTD error.