public Class Zstd

Introduction

zstd, short for Zstandard, is a fast lossless compression algorithm, targeting real-time compression scenarios at zlib-level and better compression ratios. The zstd compression library provides in-memory compression and decompression functions.

The library supports regular compression levels from 1 up to maxCLevel, which is currently 22. Levels ≥ 20, labeled --ultra, should be used with caution, as they require more memory. The library also offers negative compression levels, which extend the range of speed vs. ratio preferences. The lower the level, the faster the speed (at the cost of compression).

Compression can be done in:

• a single step (described as Simple API)
• a single step, reusing a context (described as Explicit context)
• unbounded multiple steps (described as Streaming compression)

The compression ratio achievable on small data can be highly improved using a dictionary. Dictionary compression can be performed in:

• a single step (described as Simple dictionary API)
• a single step, reusing a dictionary (described as Bulk-processing dictionary API)

Advanced experimental functions can be accessed using #define ZSTD_STATIC_LINKING_ONLY before including zstd.h. Advanced experimental APIs should never be used with a dynamically-linked library. They are not "stable", their definitions or signatures may change in the future. Only static linking is allowed.

Streaming compression - HowTo

A ZSTD_CStream object is required to track streaming operation.

Use createCStream and freeCStream to create/release resources. ZSTD_CStream objects can be reused multiple times on consecutive compression operations. It is recommended to re-use ZSTD_CStream since it will play nicer with system's memory, by re-using already allocated memory.

For parallel execution, use one separate ZSTD_CStream.

Since v1.3.0, ZSTD_CStream and ZSTD_CCtx are the same thing.

Parameters are sticky: when starting a new compression on the same context, it will re-use the same sticky parameters as previous compression session. When in doubt, it's recommended to fully initialize the context before usage. Use CCtx_reset to reset the context and CCtx_setParameter, CCtx_setPledgedSrcSize, or CCtx_loadDictionary and friends to set more specific parameters, the pledged source size, or load a dictionary.

Use compressStream2 with e_continue as many times as necessary to consume input stream. The function will automatically update both pos fields within input and output. Note that the function may not consume the entire input, for example, because the output buffer is already full, in which case input.pos < input.size. The caller must check if input has been entirely consumed. If not, the caller must make some room to receive more compressed data, and then present again remaining input data.

At any moment, it's possible to flush whatever data might remain stuck within internal buffer, using ZSTD_compressStream2() with e_flush. output->pos will be updated. Note that, if output->size is too small, a single invocation with ZSTD_e_flush might not be enough (return code > 0). In which case, make some room to receive more compressed data, and call again ZSTD_compressStream2() with ZSTD_e_flush. You must continue calling ZSTD_compressStream2() with ZSTD_e_flush until it returns 0, at which point you can change the operation.

Calling ZSTD_compressStream2() with e_end instructs to finish a frame. It will perform a flush and write frame epilogue. The epilogue is required for decoders to consider a frame completed. Flush operation is the same, and follows same rules as calling ZSTD_compressStream2() with ZSTD_e_flush. You must continue calling ZSTD_compressStream2() with ZSTD_e_end until it returns 0, at which point you are free to start a new frame.

Streaming decompression - HowTo

A ZSTD_DStream object is required to track streaming operations.

Use createDStream and freeDStream to create/release resources. ZSTD_DStream objects can be re-used multiple times.

Use DCtx_reset and DCtx_refDDict to start a new decompression operation. Alternatively, use advanced API to set specific properties.

Use decompressStream repetitively to consume your input. The function will update both pos fields. If input.pos < input.size, some input has not been consumed. It's up to the caller to present again remaining data. The function tries to flush all data decoded immediately, respecting output buffer size. If output.pos < output.size, decoder has flushed everything it could. But if output.pos == output.size, there might be some data left within internal buffers. In which case, call ZSTD_decompressStream() again to flush whatever remains in the buffer.