mercurial-scm/hg: comparison contrib/python-zstandard/zstd/zstd.h

equal deleted inserted replaced

-:2da754532dd3
+:69de49c4e39c
 the future. Only static linking is allowed.
 *******************************************************************************/
 /*------   Version   ------*/
 #define ZSTD_VERSION_MAJOR    1
-#define ZSTD_VERSION_MINOR    3
+#define ZSTD_VERSION_MINOR    4
-#define ZSTD_VERSION_RELEASE  8
+#define ZSTD_VERSION_RELEASE  3
 #define ZSTD_VERSION_NUMBER  (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE)
 ZSTDLIB_API unsigned ZSTD_versionNumber(void);   /**< to check runtime library version */
 #define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE
 #define ZSTD_QUOTE(str) #str
 #define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str)
 #define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)
 ZSTDLIB_API const char* ZSTD_versionString(void);   /* requires v1.3.0+ */
-/***************************************
+/* *************************************
 *  Default constant
 ***************************************/
 #ifndef ZSTD_CLEVEL_DEFAULT
 #  define ZSTD_CLEVEL_DEFAULT 3
 #endif
+/* *************************************
+*  Constants
+***************************************/
+/* All magic numbers are supposed read/written to/from files/memory using little-endian convention */
+#define ZSTD_MAGICNUMBER            0xFD2FB528    /* valid since v0.8.0 */
+#define ZSTD_MAGIC_DICTIONARY       0xEC30A437    /* valid since v0.7.0 */
+#define ZSTD_MAGIC_SKIPPABLE_START  0x184D2A50    /* all 16 values, from 0x184D2A50 to 0x184D2A5F, signal the beginning of a skippable frame */
+#define ZSTD_MAGIC_SKIPPABLE_MASK   0xFFFFFFF0
+#define ZSTD_BLOCKSIZELOG_MAX  17
+#define ZSTD_BLOCKSIZE_MAX     (1<<ZSTD_BLOCKSIZELOG_MAX)
 /***************************************
 *  Simple API
 ***************************************/
 /*! ZSTD_compress() :
 *  "empty", "unknown" and "error" results to the same return value (0),
 *  while ZSTD_getFrameContentSize() gives them separate return values.
 * @return : decompressed size of `src` frame content _if known and not empty_, 0 otherwise. */
 ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);
+/*! ZSTD_findFrameCompressedSize() :
+* `src` should point to the start of a ZSTD frame or skippable frame.
+* `srcSize` must be >= first frame size
+* @return : the compressed size of the first frame starting at `src`,
+*           suitable to pass as `srcSize` to `ZSTD_decompress` or similar,
+*        or an error code if input is invalid */
+ZSTDLIB_API size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
 /*======  Helper functions  ======*/
 #define ZSTD_COMPRESSBOUND(srcSize)   ((srcSize) + ((srcSize)>>8) + (((srcSize) < (128<<10)) ? (((128<<10) - (srcSize)) >> 11) /* margin, from 64 to 0 */ : 0))  /* this formula ensures that bound(A) + bound(B) <= bound(A+B) as long as A and B >= 128 KB */
 ZSTDLIB_API size_t      ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */
 ZSTDLIB_API unsigned    ZSTD_isError(size_t code);          /*!< tells if a `size_t` function result is an error code */
 ZSTDLIB_API const char* ZSTD_getErrorName(size_t code);     /*!< provides readable string from an error code */
+ZSTDLIB_API int         ZSTD_minCLevel(void);               /*!< minimum negative compression level allowed */
 ZSTDLIB_API int         ZSTD_maxCLevel(void);               /*!< maximum compression level available */
 /***************************************
 *  Explicit context
 ***************************************/
 /*= Compression context
 *  When compressing many times,
-*  it is recommended to allocate a context just once, and re-use it for each successive compression operation.
+*  it is recommended to allocate a context just once,
+*  and re-use it for each successive compression operation.
 *  This will make workload friendlier for system's memory.
-*  Use one context per thread for parallel execution in multi-threaded environments. */
+*  Note : re-using context is just a speed / resource optimization.
+*         It doesn't change the compression ratio, which remains identical.
+*  Note 2 : In multi-threaded environments,
+*         use one different context per thread for parallel execution.
+*/
 typedef struct ZSTD_CCtx_s ZSTD_CCtx;
 ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void);
 ZSTDLIB_API size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);
 /*! ZSTD_compressCCtx() :
 *  Compatible with sticky parameters.
 */
 ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* dctx,
 void* dst, size_t dstCapacity,
 const void* src, size_t srcSize);
-/**************************
-*  Simple dictionary API
-***************************/
-/*! ZSTD_compress_usingDict() :
-*  Compression at an explicit compression level using a Dictionary.
-*  A dictionary can be any arbitrary data segment (also called a prefix),
-*  or a buffer with specified information (see dictBuilder/zdict.h).
-*  Note : This function loads the dictionary, resulting in significant startup delay.
-*         It's intended for a dictionary used only once.
-*  Note 2 : When `dict == NULL || dictSize < 8` no dictionary is used. */
-ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
-void* dst, size_t dstCapacity,
-const void* src, size_t srcSize,
-const void* dict,size_t dictSize,
-int compressionLevel);
-/*! ZSTD_decompress_usingDict() :
-*  Decompression using a known Dictionary.
-*  Dictionary must be identical to the one used during compression.
-*  Note : This function loads the dictionary, resulting in significant startup delay.
-*         It's intended for a dictionary used only once.
-*  Note : When `dict == NULL || dictSize < 8` no dictionary is used. */
-ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx,
-void* dst, size_t dstCapacity,
-const void* src, size_t srcSize,
-const void* dict,size_t dictSize);
-/***********************************
-*  Bulk processing dictionary API
-**********************************/
-typedef struct ZSTD_CDict_s ZSTD_CDict;
-/*! ZSTD_createCDict() :
-*  When compressing multiple messages / blocks using the same dictionary, it's recommended to load it only once.
-*  ZSTD_createCDict() will create a digested dictionary, ready to start future compression operations without startup cost.
-*  ZSTD_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only.
-* `dictBuffer` can be released after ZSTD_CDict creation, because its content is copied within CDict.
-*  Consider experimental function `ZSTD_createCDict_byReference()` if you prefer to not duplicate `dictBuffer` content.
-*  Note : A ZSTD_CDict can be created from an empty dictBuffer, but it is inefficient when used to compress small data. */
-ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize,
-int compressionLevel);
-/*! ZSTD_freeCDict() :
-*  Function frees memory allocated by ZSTD_createCDict(). */
-ZSTDLIB_API size_t      ZSTD_freeCDict(ZSTD_CDict* CDict);
-/*! ZSTD_compress_usingCDict() :
-*  Compression using a digested Dictionary.
-*  Recommended when same dictionary is used multiple times.
-*  Note : compression level is _decided at dictionary creation time_,
-*     and frame parameters are hardcoded (dictID=yes, contentSize=yes, checksum=no) */
-ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx,
-void* dst, size_t dstCapacity,
-const void* src, size_t srcSize,
-const ZSTD_CDict* cdict);
-typedef struct ZSTD_DDict_s ZSTD_DDict;
-/*! ZSTD_createDDict() :
-*  Create a digested dictionary, ready to start decompression operation without startup delay.
-*  dictBuffer can be released after DDict creation, as its content is copied inside DDict. */
-ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dictBuffer, size_t dictSize);
-/*! ZSTD_freeDDict() :
-*  Function frees memory allocated with ZSTD_createDDict() */
-ZSTDLIB_API size_t      ZSTD_freeDDict(ZSTD_DDict* ddict);
-/*! ZSTD_decompress_usingDDict() :
-*  Decompression using a digested Dictionary.
-*  Recommended when same dictionary is used multiple times. */
-ZSTDLIB_API size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx,
-void* dst, size_t dstCapacity,
-const void* src, size_t srcSize,
-const ZSTD_DDict* ddict);
-/****************************
-*  Streaming
-****************************/
-typedef struct ZSTD_inBuffer_s {
-const void* src;    /**< start of input buffer */
-size_t size;        /**< size of input buffer */
-size_t pos;         /**< position where reading stopped. Will be updated. Necessarily 0 <= pos <= size */
-} ZSTD_inBuffer;
-typedef struct ZSTD_outBuffer_s {
-void*  dst;         /**< start of output buffer */
-size_t size;        /**< size of output buffer */
-size_t pos;         /**< position where writing stopped. Will be updated. Necessarily 0 <= pos <= size */
-} ZSTD_outBuffer;
-/*-***********************************************************************
-*  Streaming compression - HowTo
-*
-*  A ZSTD_CStream object is required to track streaming operation.
-*  Use ZSTD_createCStream() and ZSTD_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 per thread.
-*
-*  note : 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 ZSTD_initCStream() to set the parameter to a selected compression level.
-*  Use advanced API (ZSTD_CCtx_setParameter(), etc.) to set more specific parameters.
-*
-*  Use ZSTD_compressStream() 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.
-* @return : a size hint, preferred nb of bytes to use as input for next function call
-*           or an error code, which can be tested using ZSTD_isError().
-*           Note 1 : it's just a hint, to help latency a little, any value will work fine.
-*           Note 2 : size hint is guaranteed to be <= ZSTD_CStreamInSize()
-*
-*  At any moment, it's possible to flush whatever data might remain stuck within internal buffer,
-*  using ZSTD_flushStream(). `output->pos` will be updated.
-*  Note that, if `output->size` is too small, a single invocation of ZSTD_flushStream() might not be enough (return code > 0).
-*  In which case, make some room to receive more compressed data, and call again ZSTD_flushStream().
-*  @return : 0 if internal buffers are entirely flushed,
-*            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),
-*            or an error code, which can be tested using ZSTD_isError().
-*
-*  ZSTD_endStream() 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 ZSTD_flushStream().
-*  @return : 0 if frame fully completed and fully flushed,
-*            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),
-*            or an error code, which can be tested using ZSTD_isError().
-*
-* *******************************************************************/
-typedef ZSTD_CCtx ZSTD_CStream;  /**< CCtx and CStream are now effectively same object (>= v1.3.0) */
-/* Continue to distinguish them for compatibility with older versions <= v1.2.0 */
-/*===== ZSTD_CStream management functions =====*/
-ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream(void);
-ZSTDLIB_API size_t ZSTD_freeCStream(ZSTD_CStream* zcs);
-/*===== Streaming compression functions =====*/
-ZSTDLIB_API size_t ZSTD_initCStream(ZSTD_CStream* zcs, int compressionLevel);
-ZSTDLIB_API size_t ZSTD_compressStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
-ZSTDLIB_API size_t ZSTD_flushStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
-ZSTDLIB_API size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
-ZSTDLIB_API size_t ZSTD_CStreamInSize(void);    /**< recommended size for input buffer */
-ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block in all circumstances. */
-/*-***************************************************************************
-*  Streaming decompression - HowTo
-*
-*  A ZSTD_DStream object is required to track streaming operations.
-*  Use ZSTD_createDStream() and ZSTD_freeDStream() to create/release resources.
-*  ZSTD_DStream objects can be re-used multiple times.
-*
-*  Use ZSTD_initDStream() to start a new decompression operation.
-* @return : recommended first input size
-*  Alternatively, use advanced API to set specific properties.
-*
-*  Use ZSTD_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.
-*  Note : with no additional input provided, amount of data flushed is necessarily <= ZSTD_BLOCKSIZE_MAX.
-* @return : 0 when a frame is completely decoded and fully flushed,
-*        or an error code, which can be tested using ZSTD_isError(),
-*        or any other value > 0, which means there is still some decoding or flushing to do to complete current frame :
-*                                the return value is a suggested next input size (just a hint for better latency)
-*                                that will never request more than the remaining frame size.
-* *******************************************************************************/
-typedef ZSTD_DCtx ZSTD_DStream;  /**< DCtx and DStream are now effectively same object (>= v1.3.0) */
-/* For compatibility with versions <= v1.2.0, prefer differentiating them. */
-/*===== ZSTD_DStream management functions =====*/
-ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream(void);
-ZSTDLIB_API size_t ZSTD_freeDStream(ZSTD_DStream* zds);
-/*===== Streaming decompression functions =====*/
-ZSTDLIB_API size_t ZSTD_initDStream(ZSTD_DStream* zds);
-ZSTDLIB_API size_t ZSTD_decompressStream(ZSTD_DStream* zds, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
-ZSTDLIB_API size_t ZSTD_DStreamInSize(void);    /*!< recommended size for input buffer */
-ZSTDLIB_API size_t ZSTD_DStreamOutSize(void);   /*!< recommended size for output buffer. Guarantee to successfully flush at least one complete block in all circumstances. */
-#endif  /* ZSTD_H_235446 */
-/****************************************************************************************
-*   ADVANCED AND EXPERIMENTAL FUNCTIONS
-****************************************************************************************
-* The definitions in the following section are considered experimental.
-* They are provided for advanced scenarios.
-* They should never be used with a dynamic library, as prototypes may change in the future.
-* Use them only in association with static linking.
-* ***************************************************************************************/
-#if defined(ZSTD_STATIC_LINKING_ONLY) && !defined(ZSTD_H_ZSTD_STATIC_LINKING_ONLY)
-#define ZSTD_H_ZSTD_STATIC_LINKING_ONLY
-/****************************************************************************************
-*   Candidate API for promotion to stable status
-****************************************************************************************
-* The following symbols and constants form the "staging area" :
-* they are considered to join "stable API" by v1.4.0.
-* The proposal is written so that it can be made stable "as is",
-* though it's still possible to suggest improvements.
-* Staging is in fact last chance for changes,
-* the API is locked once reaching "stable" status.
-* ***************************************************************************************/
-/* ===  Constants   === */
-/* all magic numbers are supposed read/written to/from files/memory using little-endian convention */
-#define ZSTD_MAGICNUMBER            0xFD2FB528    /* valid since v0.8.0 */
-#define ZSTD_MAGIC_DICTIONARY       0xEC30A437    /* valid since v0.7.0 */
-#define ZSTD_MAGIC_SKIPPABLE_START  0x184D2A50    /* all 16 values, from 0x184D2A50 to 0x184D2A5F, signal the beginning of a skippable frame */
-#define ZSTD_MAGIC_SKIPPABLE_MASK   0xFFFFFFF0
-#define ZSTD_BLOCKSIZELOG_MAX  17
-#define ZSTD_BLOCKSIZE_MAX     (1<<ZSTD_BLOCKSIZELOG_MAX)
-/* ===   query limits   === */
-ZSTDLIB_API int ZSTD_minCLevel(void);  /*!< minimum negative compression level allowed */
-/* ===   frame size   === */
-/*! ZSTD_findFrameCompressedSize() :
-* `src` should point to the start of a ZSTD frame or skippable frame.
-* `srcSize` must be >= first frame size
-* @return : the compressed size of the first frame starting at `src`,
-*           suitable to pass as `srcSize` to `ZSTD_decompress` or similar,
-*        or an error code if input is invalid */
-ZSTDLIB_API size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
-/* ===   Memory management   === */
-/*! ZSTD_sizeof_*() :
-*  These functions give the _current_ memory usage of selected object.
-*  Note that object memory usage can evolve (increase or decrease) over time. */
-ZSTDLIB_API size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx);
-ZSTDLIB_API size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx* dctx);
-ZSTDLIB_API size_t ZSTD_sizeof_CStream(const ZSTD_CStream* zcs);
-ZSTDLIB_API size_t ZSTD_sizeof_DStream(const ZSTD_DStream* zds);
-ZSTDLIB_API size_t ZSTD_sizeof_CDict(const ZSTD_CDict* cdict);
-ZSTDLIB_API size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
 /***************************************
 *  Advanced compression API
 ***************************************/
 } ZSTD_strategy;
 typedef enum {
-/* compression parameters */
+/* compression parameters
+* Note: When compressing with a ZSTD_CDict these parameters are superseded
+* by the parameters used to construct the ZSTD_CDict. See ZSTD_CCtx_refCDict()
+* for more info (superseded-by-cdict). */
 ZSTD_c_compressionLevel=100, /* Update all compression parameters according to pre-defined cLevel table
 * Default level is ZSTD_CLEVEL_DEFAULT==3.
 * Special: value 0 means default, which is controlled by ZSTD_CLEVEL_DEFAULT.
 * Note 1 : it's possible to pass a negative compression level.
 * Note 2 : setting a level sets all default values of other compression parameters */
 * At the time of this writing, they include :
 * ZSTD_c_rsyncable
 * ZSTD_c_format
 * ZSTD_c_forceMaxWindow
 * ZSTD_c_forceAttachDict
+* ZSTD_c_literalCompressionMode
+* ZSTD_c_targetCBlockSize
 * Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
 * note : never ever use experimentalParam? names directly;
 *        also, the enums values themselves are unstable and can still change.
 */
 ZSTD_c_experimentalParam1=500,
 ZSTD_c_experimentalParam2=10,
 ZSTD_c_experimentalParam3=1000,
-ZSTD_c_experimentalParam4=1001
+ZSTD_c_experimentalParam4=1001,
+ZSTD_c_experimentalParam5=1002,
+ZSTD_c_experimentalParam6=1003,
 } ZSTD_cParameter;
 typedef struct {
 size_t error;
 int lowerBound;
 int upperBound;
 *  Note 2 : pledgedSrcSize is only valid once, for the next frame.
 *           It's discarded at the end of the frame, and replaced by ZSTD_CONTENTSIZE_UNKNOWN.
 *  Note 3 : Whenever all input data is provided and consumed in a single round,
 *           for example with ZSTD_compress2(),
 *           or invoking immediately ZSTD_compressStream2(,,,ZSTD_e_end),
-*           this value is automatically overriden by srcSize instead.
+*           this value is automatically overridden by srcSize instead.
 */
 ZSTDLIB_API size_t ZSTD_CCtx_setPledgedSrcSize(ZSTD_CCtx* cctx, unsigned long long pledgedSrcSize);
+typedef enum {
+ZSTD_reset_session_only = 1,
+ZSTD_reset_parameters = 2,
+ZSTD_reset_session_and_parameters = 3
+} ZSTD_ResetDirective;
+/*! ZSTD_CCtx_reset() :
+*  There are 2 different things that can be reset, independently or jointly :
+*  - The session : will stop compressing current frame, and make CCtx ready to start a new one.
+*                  Useful after an error, or to interrupt any ongoing compression.
+*                  Any internal data not yet flushed is cancelled.
+*                  Compression parameters and dictionary remain unchanged.
+*                  They will be used to compress next frame.
+*                  Resetting session never fails.
+*  - The parameters : changes all parameters back to "default".
+*                  This removes any reference to any dictionary too.
+*                  Parameters can only be changed between 2 sessions (i.e. no compression is currently ongoing)
+*                  otherwise the reset fails, and function returns an error value (which can be tested using ZSTD_isError())
+*  - Both : similar to resetting the session, followed by resetting parameters.
+*/
+ZSTDLIB_API size_t ZSTD_CCtx_reset(ZSTD_CCtx* cctx, ZSTD_ResetDirective reset);
+/*! ZSTD_compress2() :
+*  Behave the same as ZSTD_compressCCtx(), but compression parameters are set using the advanced API.
+*  ZSTD_compress2() always starts a new frame.
+*  Should cctx hold data from a previously unfinished frame, everything about it is forgotten.
+*  - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
+*  - The function is always blocking, returns when compression is completed.
+*  Hint : compression runs faster if `dstCapacity` >=  `ZSTD_compressBound(srcSize)`.
+* @return : compressed size written into `dst` (<= `dstCapacity),
+*           or an error code if it fails (which can be tested using ZSTD_isError()).
+*/
+ZSTDLIB_API size_t ZSTD_compress2( ZSTD_CCtx* cctx,
+void* dst, size_t dstCapacity,
+const void* src, size_t srcSize);
+/***************************************
+*  Advanced decompression API
+***************************************/
+/* The advanced API pushes parameters one by one into an existing DCtx context.
+* Parameters are sticky, and remain valid for all following frames
+* using the same DCtx context.
+* It's possible to reset parameters to default values using ZSTD_DCtx_reset().
+* Note : This API is compatible with existing ZSTD_decompressDCtx() and ZSTD_decompressStream().
+*        Therefore, no new decompression function is necessary.
+*/
+typedef enum {
+ZSTD_d_windowLogMax=100, /* Select a size limit (in power of 2) beyond which
+* the streaming API will refuse to allocate memory buffer
+* in order to protect the host from unreasonable memory requirements.
+* This parameter is only useful in streaming mode, since no internal buffer is allocated in single-pass mode.
+* By default, a decompression context accepts window sizes <= (1 << ZSTD_WINDOWLOG_LIMIT_DEFAULT).
+* Special: value 0 means "use default maximum windowLog". */
+/* note : additional experimental parameters are also available
+* within the experimental section of the API.
+* At the time of this writing, they include :
+* ZSTD_c_format
+* Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
+* note : never ever use experimentalParam? names directly
+*/
+ZSTD_d_experimentalParam1=1000
+} ZSTD_dParameter;
+/*! ZSTD_dParam_getBounds() :
+*  All parameters must belong to an interval with lower and upper bounds,
+*  otherwise they will either trigger an error or be automatically clamped.
+* @return : a structure, ZSTD_bounds, which contains
+*         - an error status field, which must be tested using ZSTD_isError()
+*         - both lower and upper bounds, inclusive
+*/
+ZSTDLIB_API ZSTD_bounds ZSTD_dParam_getBounds(ZSTD_dParameter dParam);
+/*! ZSTD_DCtx_setParameter() :
+*  Set one compression parameter, selected by enum ZSTD_dParameter.
+*  All parameters have valid bounds. Bounds can be queried using ZSTD_dParam_getBounds().
+*  Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter).
+*  Setting a parameter is only possible during frame initialization (before starting decompression).
+* @return : 0, or an error code (which can be tested using ZSTD_isError()).
+*/
+ZSTDLIB_API size_t ZSTD_DCtx_setParameter(ZSTD_DCtx* dctx, ZSTD_dParameter param, int value);
+/*! ZSTD_DCtx_reset() :
+*  Return a DCtx to clean state.
+*  Session and parameters can be reset jointly or separately.
+*  Parameters can only be reset when no active frame is being decompressed.
+* @return : 0, or an error code, which can be tested with ZSTD_isError()
+*/
+ZSTDLIB_API size_t ZSTD_DCtx_reset(ZSTD_DCtx* dctx, ZSTD_ResetDirective reset);
+/****************************
+*  Streaming
+****************************/
+typedef struct ZSTD_inBuffer_s {
+const void* src;    /**< start of input buffer */
+size_t size;        /**< size of input buffer */
+size_t pos;         /**< position where reading stopped. Will be updated. Necessarily 0 <= pos <= size */
+} ZSTD_inBuffer;
+typedef struct ZSTD_outBuffer_s {
+void*  dst;         /**< start of output buffer */
+size_t size;        /**< size of output buffer */
+size_t pos;         /**< position where writing stopped. Will be updated. Necessarily 0 <= pos <= size */
+} ZSTD_outBuffer;
+/*-***********************************************************************
+*  Streaming compression - HowTo
+*
+*  A ZSTD_CStream object is required to track streaming operation.
+*  Use ZSTD_createCStream() and ZSTD_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 per thread.
+*
+*  note : 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 ZSTD_CCtx_reset() to reset the context and ZSTD_CCtx_setParameter(),
+*  ZSTD_CCtx_setPledgedSrcSize(), or ZSTD_CCtx_loadDictionary() and friends to
+*  set more specific parameters, the pledged source size, or load a dictionary.
+*
+*  Use ZSTD_compressStream2() with ZSTD_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.
+*  note: ZSTD_e_continue is guaranteed to make some forward progress when called,
+*        but doesn't guarantee maximal forward progress. This is especially relevant
+*        when compressing with multiple threads. The call won't block if it can
+*        consume some input, but if it can't it will wait for some, but not all,
+*        output to be flushed.
+* @return : provides a minimum amount of data remaining to be flushed from internal buffers
+*           or an error code, which can be tested using ZSTD_isError().
+*
+*  At any moment, it's possible to flush whatever data might remain stuck within internal buffer,
+*  using ZSTD_compressStream2() with ZSTD_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.
+*  note: ZSTD_e_flush will flush as much output as possible, meaning when compressing with multiple threads, it will
+*        block until the flush is complete or the output buffer is full.
+*  @return : 0 if internal buffers are entirely flushed,
+*            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),
+*            or an error code, which can be tested using ZSTD_isError().
+*
+*  Calling ZSTD_compressStream2() with ZSTD_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.
+*  note: ZSTD_e_end will flush as much output as possible, meaning when compressing with multiple threads, it will
+*        block until the flush is complete or the output buffer is full.
+*  @return : 0 if frame fully completed and fully flushed,
+*            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),
+*            or an error code, which can be tested using ZSTD_isError().
+*
+* *******************************************************************/
+typedef ZSTD_CCtx ZSTD_CStream;  /**< CCtx and CStream are now effectively same object (>= v1.3.0) */
+/* Continue to distinguish them for compatibility with older versions <= v1.2.0 */
+/*===== ZSTD_CStream management functions =====*/
+ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream(void);
+ZSTDLIB_API size_t ZSTD_freeCStream(ZSTD_CStream* zcs);
+/*===== Streaming compression functions =====*/
+typedef enum {
+ZSTD_e_continue=0, /* collect more data, encoder decides when to output compressed result, for optimal compression ratio */
+ZSTD_e_flush=1,    /* flush any data provided so far,
+* it creates (at least) one new block, that can be decoded immediately on reception;
+* frame will continue: any future data can still reference previously compressed data, improving compression.
+* note : multithreaded compression will block to flush as much output as possible. */
+ZSTD_e_end=2       /* flush any remaining data _and_ close current frame.
+* note that frame is only closed after compressed data is fully flushed (return value == 0).
+* After that point, any additional data starts a new frame.
+* note : each frame is independent (does not reference any content from previous frame).
+: note : multithreaded compression will block to flush as much output as possible. */
+} ZSTD_EndDirective;
+/*! ZSTD_compressStream2() :
+*  Behaves about the same as ZSTD_compressStream, with additional control on end directive.
+*  - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
+*  - Compression parameters cannot be changed once compression is started (save a list of exceptions in multi-threading mode)
+*  - output->pos must be <= dstCapacity, input->pos must be <= srcSize
+*  - output->pos and input->pos will be updated. They are guaranteed to remain below their respective limit.
+*  - When nbWorkers==0 (default), function is blocking : it completes its job before returning to caller.
+*  - When nbWorkers>=1, function is non-blocking : it just acquires a copy of input, and distributes jobs to internal worker threads, flush whatever is available,
+*                                                  and then immediately returns, just indicating that there is some data remaining to be flushed.
+*                                                  The function nonetheless guarantees forward progress : it will return only after it reads or write at least 1+ byte.
+*  - Exception : if the first call requests a ZSTD_e_end directive and provides enough dstCapacity, the function delegates to ZSTD_compress2() which is always blocking.
+*  - @return provides a minimum amount of data remaining to be flushed from internal buffers
+*            or an error code, which can be tested using ZSTD_isError().
+*            if @return != 0, flush is not fully completed, there is still some data left within internal buffers.
+*            This is useful for ZSTD_e_flush, since in this case more flushes are necessary to empty all buffers.
+*            For ZSTD_e_end, @return == 0 when internal buffers are fully flushed and frame is completed.
+*  - after a ZSTD_e_end directive, if internal buffer is not fully flushed (@return != 0),
+*            only ZSTD_e_end or ZSTD_e_flush operations are allowed.
+*            Before starting a new compression job, or changing compression parameters,
+*            it is required to fully flush internal buffers.
+*/
+ZSTDLIB_API size_t ZSTD_compressStream2( ZSTD_CCtx* cctx,
+ZSTD_outBuffer* output,
+ZSTD_inBuffer* input,
+ZSTD_EndDirective endOp);
+/* These buffer sizes are softly recommended.
+* They are not required : ZSTD_compressStream*() happily accepts any buffer size, for both input and output.
+* Respecting the recommended size just makes it a bit easier for ZSTD_compressStream*(),
+* reducing the amount of memory shuffling and buffering, resulting in minor performance savings.
+*
+* However, note that these recommendations are from the perspective of a C caller program.
+* If the streaming interface is invoked from some other language,
+* especially managed ones such as Java or Go, through a foreign function interface such as jni or cgo,
+* a major performance rule is to reduce crossing such interface to an absolute minimum.
+* It's not rare that performance ends being spent more into the interface, rather than compression itself.
+* In which cases, prefer using large buffers, as large as practical,
+* for both input and output, to reduce the nb of roundtrips.
+*/
+ZSTDLIB_API size_t ZSTD_CStreamInSize(void);    /**< recommended size for input buffer */
+ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block. */
+/* *****************************************************************************
+* This following is a legacy streaming API.
+* It can be replaced by ZSTD_CCtx_reset() and ZSTD_compressStream2().
+* It is redundant, but remains fully supported.
+* Advanced parameters and dictionary compression can only be used through the
+* new API.
+******************************************************************************/
+/*!
+* Equivalent to:
+*
+*     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
+*     ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
+*     ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
+*/
+ZSTDLIB_API size_t ZSTD_initCStream(ZSTD_CStream* zcs, int compressionLevel);
+/*!
+* Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
+* NOTE: The return value is different. ZSTD_compressStream() returns a hint for
+* the next read size (if non-zero and not an error). ZSTD_compressStream2()
+* returns the minimum nb of bytes left to flush (if non-zero and not an error).
+*/
+ZSTDLIB_API size_t ZSTD_compressStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
+/*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush). */
+ZSTDLIB_API size_t ZSTD_flushStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
+/*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end). */
+ZSTDLIB_API size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
+/*-***************************************************************************
+*  Streaming decompression - HowTo
+*
+*  A ZSTD_DStream object is required to track streaming operations.
+*  Use ZSTD_createDStream() and ZSTD_freeDStream() to create/release resources.
+*  ZSTD_DStream objects can be re-used multiple times.
+*
+*  Use ZSTD_initDStream() to start a new decompression operation.
+* @return : recommended first input size
+*  Alternatively, use advanced API to set specific properties.
+*
+*  Use ZSTD_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.
+*  Note : with no additional input provided, amount of data flushed is necessarily <= ZSTD_BLOCKSIZE_MAX.
+* @return : 0 when a frame is completely decoded and fully flushed,
+*        or an error code, which can be tested using ZSTD_isError(),
+*        or any other value > 0, which means there is still some decoding or flushing to do to complete current frame :
+*                                the return value is a suggested next input size (just a hint for better latency)
+*                                that will never request more than the remaining frame size.
+* *******************************************************************************/
+typedef ZSTD_DCtx ZSTD_DStream;  /**< DCtx and DStream are now effectively same object (>= v1.3.0) */
+/* For compatibility with versions <= v1.2.0, prefer differentiating them. */
+/*===== ZSTD_DStream management functions =====*/
+ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream(void);
+ZSTDLIB_API size_t ZSTD_freeDStream(ZSTD_DStream* zds);
+/*===== Streaming decompression functions =====*/
+/* This function is redundant with the advanced API and equivalent to:
+*
+*     ZSTD_DCtx_reset(zds);
+*     ZSTD_DCtx_refDDict(zds, NULL);
+*/
+ZSTDLIB_API size_t ZSTD_initDStream(ZSTD_DStream* zds);
+ZSTDLIB_API size_t ZSTD_decompressStream(ZSTD_DStream* zds, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
+ZSTDLIB_API size_t ZSTD_DStreamInSize(void);    /*!< recommended size for input buffer */
+ZSTDLIB_API size_t ZSTD_DStreamOutSize(void);   /*!< recommended size for output buffer. Guarantee to successfully flush at least one complete block in all circumstances. */
+/**************************
+*  Simple dictionary API
+***************************/
+/*! ZSTD_compress_usingDict() :
+*  Compression at an explicit compression level using a Dictionary.
+*  A dictionary can be any arbitrary data segment (also called a prefix),
+*  or a buffer with specified information (see dictBuilder/zdict.h).
+*  Note : This function loads the dictionary, resulting in significant startup delay.
+*         It's intended for a dictionary used only once.
+*  Note 2 : When `dict == NULL || dictSize < 8` no dictionary is used. */
+ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
+void* dst, size_t dstCapacity,
+const void* src, size_t srcSize,
+const void* dict,size_t dictSize,
+int compressionLevel);
+/*! ZSTD_decompress_usingDict() :
+*  Decompression using a known Dictionary.
+*  Dictionary must be identical to the one used during compression.
+*  Note : This function loads the dictionary, resulting in significant startup delay.
+*         It's intended for a dictionary used only once.
+*  Note : When `dict == NULL || dictSize < 8` no dictionary is used. */
+ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx,
+void* dst, size_t dstCapacity,
+const void* src, size_t srcSize,
+const void* dict,size_t dictSize);
+/***********************************
+*  Bulk processing dictionary API
+**********************************/
+typedef struct ZSTD_CDict_s ZSTD_CDict;
+/*! ZSTD_createCDict() :
+*  When compressing multiple messages / blocks using the same dictionary, it's recommended to load it only once.
+*  ZSTD_createCDict() will create a digested dictionary, ready to start future compression operations without startup cost.
+*  ZSTD_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only.
+* `dictBuffer` can be released after ZSTD_CDict creation, because its content is copied within CDict.
+*  Consider experimental function `ZSTD_createCDict_byReference()` if you prefer to not duplicate `dictBuffer` content.
+*  Note : A ZSTD_CDict can be created from an empty dictBuffer, but it is inefficient when used to compress small data. */
+ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize,
+int compressionLevel);
+/*! ZSTD_freeCDict() :
+*  Function frees memory allocated by ZSTD_createCDict(). */
+ZSTDLIB_API size_t      ZSTD_freeCDict(ZSTD_CDict* CDict);
+/*! ZSTD_compress_usingCDict() :
+*  Compression using a digested Dictionary.
+*  Recommended when same dictionary is used multiple times.
+*  Note : compression level is _decided at dictionary creation time_,
+*     and frame parameters are hardcoded (dictID=yes, contentSize=yes, checksum=no) */
+ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx,
+void* dst, size_t dstCapacity,
+const void* src, size_t srcSize,
+const ZSTD_CDict* cdict);
+typedef struct ZSTD_DDict_s ZSTD_DDict;
+/*! ZSTD_createDDict() :
+*  Create a digested dictionary, ready to start decompression operation without startup delay.
+*  dictBuffer can be released after DDict creation, as its content is copied inside DDict. */
+ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dictBuffer, size_t dictSize);
+/*! ZSTD_freeDDict() :
+*  Function frees memory allocated with ZSTD_createDDict() */
+ZSTDLIB_API size_t      ZSTD_freeDDict(ZSTD_DDict* ddict);
+/*! ZSTD_decompress_usingDDict() :
+*  Decompression using a digested Dictionary.
+*  Recommended when same dictionary is used multiple times. */
+ZSTDLIB_API size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx,
+void* dst, size_t dstCapacity,
+const void* src, size_t srcSize,
+const ZSTD_DDict* ddict);
+/********************************
+*  Dictionary helper functions
+*******************************/
+/*! ZSTD_getDictID_fromDict() :
+*  Provides the dictID stored within dictionary.
+*  if @return == 0, the dictionary is not conformant with Zstandard specification.
+*  It can still be loaded, but as a content-only dictionary. */
+ZSTDLIB_API unsigned ZSTD_getDictID_fromDict(const void* dict, size_t dictSize);
+/*! ZSTD_getDictID_fromDDict() :
+*  Provides the dictID of the dictionary loaded into `ddict`.
+*  If @return == 0, the dictionary is not conformant to Zstandard specification, or empty.
+*  Non-conformant dictionaries can still be loaded, but as content-only dictionaries. */
+ZSTDLIB_API unsigned ZSTD_getDictID_fromDDict(const ZSTD_DDict* ddict);
+/*! ZSTD_getDictID_fromFrame() :
+*  Provides the dictID required to decompressed the frame stored within `src`.
+*  If @return == 0, the dictID could not be decoded.
+*  This could for one of the following reasons :
+*  - The frame does not require a dictionary to be decoded (most common case).
+*  - The frame was built with dictID intentionally removed. Whatever dictionary is necessary is a hidden information.
+*    Note : this use case also happens when using a non-conformant dictionary.
+*  - `srcSize` is too small, and as a result, the frame header could not be decoded (only possible if `srcSize < ZSTD_FRAMEHEADERSIZE_MAX`).
+*  - This is not a Zstandard frame.
+*  When identifying the exact failure cause, it's possible to use ZSTD_getFrameHeader(), which will provide a more precise error code. */
+ZSTDLIB_API unsigned ZSTD_getDictID_fromFrame(const void* src, size_t srcSize);
+/*******************************************************************************
+* Advanced dictionary and prefix API
+*
+* This API allows dictionaries to be used with ZSTD_compress2(),
+* ZSTD_compressStream2(), and ZSTD_decompress(). Dictionaries are sticky, and
+* only reset with the context is reset with ZSTD_reset_parameters or
+* ZSTD_reset_session_and_parameters. Prefixes are single-use.
+******************************************************************************/
 /*! ZSTD_CCtx_loadDictionary() :
 *  Create an internal CDict from `dict` buffer.
 *  Decompression will have to use same dictionary.
 * @result : 0, or an error code (which can be tested with ZSTD_isError()).
 ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary(ZSTD_CCtx* cctx, const void* dict, size_t dictSize);
 /*! ZSTD_CCtx_refCDict() :
 *  Reference a prepared dictionary, to be used for all next compressed frames.
 *  Note that compression parameters are enforced from within CDict,
-*  and supercede any compression parameter previously set within CCtx.
+*  and supersede any compression parameter previously set within CCtx.
+*  The parameters ignored are labled as "superseded-by-cdict" in the ZSTD_cParameter enum docs.
+*  The ignored parameters will be used again if the CCtx is returned to no-dictionary mode.
 *  The dictionary will remain valid for future compressed frames using same CCtx.
 * @result : 0, or an error code (which can be tested with ZSTD_isError()).
 *  Special : Referencing a NULL CDict means "return to no-dictionary mode".
 *  Note 1 : Currently, only one dictionary can be managed.
 *           Referencing a new dictionary effectively "discards" any previous one.
 *  Note 4 : By default, the prefix is interpreted as raw content (ZSTD_dm_rawContent).
 *           Use experimental ZSTD_CCtx_refPrefix_advanced() to alter dictionary interpretation. */
 ZSTDLIB_API size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx,
 const void* prefix, size_t prefixSize);
-typedef enum {
-ZSTD_reset_session_only = 1,
-ZSTD_reset_parameters = 2,
-ZSTD_reset_session_and_parameters = 3
-} ZSTD_ResetDirective;
-/*! ZSTD_CCtx_reset() :
-*  There are 2 different things that can be reset, independently or jointly :
-*  - The session : will stop compressing current frame, and make CCtx ready to start a new one.
-*                  Useful after an error, or to interrupt any ongoing compression.
-*                  Any internal data not yet flushed is cancelled.
-*                  Compression parameters and dictionary remain unchanged.
-*                  They will be used to compress next frame.
-*                  Resetting session never fails.
-*  - The parameters : changes all parameters back to "default".
-*                  This removes any reference to any dictionary too.
-*                  Parameters can only be changed between 2 sessions (i.e. no compression is currently ongoing)
-*                  otherwise the reset fails, and function returns an error value (which can be tested using ZSTD_isError())
-*  - Both : similar to resetting the session, followed by resetting parameters.
-*/
-ZSTDLIB_API size_t ZSTD_CCtx_reset(ZSTD_CCtx* cctx, ZSTD_ResetDirective reset);
-/*! ZSTD_compress2() :
-*  Behave the same as ZSTD_compressCCtx(), but compression parameters are set using the advanced API.
-*  ZSTD_compress2() always starts a new frame.
-*  Should cctx hold data from a previously unfinished frame, everything about it is forgotten.
-*  - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
-*  - The function is always blocking, returns when compression is completed.
-*  Hint : compression runs faster if `dstCapacity` >=  `ZSTD_compressBound(srcSize)`.
-* @return : compressed size written into `dst` (<= `dstCapacity),
-*           or an error code if it fails (which can be tested using ZSTD_isError()).
-*/
-ZSTDLIB_API size_t ZSTD_compress2( ZSTD_CCtx* cctx,
-void* dst, size_t dstCapacity,
-const void* src, size_t srcSize);
-typedef enum {
-ZSTD_e_continue=0, /* collect more data, encoder decides when to output compressed result, for optimal compression ratio */
-ZSTD_e_flush=1,    /* flush any data provided so far,
-* it creates (at least) one new block, that can be decoded immediately on reception;
-* frame will continue: any future data can still reference previously compressed data, improving compression. */
-ZSTD_e_end=2       /* flush any remaining data _and_ close current frame.
-* note that frame is only closed after compressed data is fully flushed (return value == 0).
-* After that point, any additional data starts a new frame.
-* note : each frame is independent (does not reference any content from previous frame). */
-} ZSTD_EndDirective;
-/*! ZSTD_compressStream2() :
-*  Behaves about the same as ZSTD_compressStream, with additional control on end directive.
-*  - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
-*  - Compression parameters cannot be changed once compression is started (save a list of exceptions in multi-threading mode)
-*  - outpot->pos must be <= dstCapacity, input->pos must be <= srcSize
-*  - outpot->pos and input->pos will be updated. They are guaranteed to remain below their respective limit.
-*  - When nbWorkers==0 (default), function is blocking : it completes its job before returning to caller.
-*  - When nbWorkers>=1, function is non-blocking : it just acquires a copy of input, and distributes jobs to internal worker threads, flush whatever is available,
-*                                                  and then immediately returns, just indicating that there is some data remaining to be flushed.
-*                                                  The function nonetheless guarantees forward progress : it will return only after it reads or write at least 1+ byte.
-*  - Exception : if the first call requests a ZSTD_e_end directive and provides enough dstCapacity, the function delegates to ZSTD_compress2() which is always blocking.
-*  - @return provides a minimum amount of data remaining to be flushed from internal buffers
-*            or an error code, which can be tested using ZSTD_isError().
-*            if @return != 0, flush is not fully completed, there is still some data left within internal buffers.
-*            This is useful for ZSTD_e_flush, since in this case more flushes are necessary to empty all buffers.
-*            For ZSTD_e_end, @return == 0 when internal buffers are fully flushed and frame is completed.
-*  - after a ZSTD_e_end directive, if internal buffer is not fully flushed (@return != 0),
-*            only ZSTD_e_end or ZSTD_e_flush operations are allowed.
-*            Before starting a new compression job, or changing compression parameters,
-*            it is required to fully flush internal buffers.
-*/
-ZSTDLIB_API size_t ZSTD_compressStream2( ZSTD_CCtx* cctx,
-ZSTD_outBuffer* output,
-ZSTD_inBuffer* input,
-ZSTD_EndDirective endOp);
-/* ============================== */
-/*   Advanced decompression API   */
-/* ============================== */
-/* The advanced API pushes parameters one by one into an existing DCtx context.
-* Parameters are sticky, and remain valid for all following frames
-* using the same DCtx context.
-* It's possible to reset parameters to default values using ZSTD_DCtx_reset().
-* Note : This API is compatible with existing ZSTD_decompressDCtx() and ZSTD_decompressStream().
-*        Therefore, no new decompression function is necessary.
-*/
-typedef enum {
-ZSTD_d_windowLogMax=100, /* Select a size limit (in power of 2) beyond which
-* the streaming API will refuse to allocate memory buffer
-* in order to protect the host from unreasonable memory requirements.
-* This parameter is only useful in streaming mode, since no internal buffer is allocated in single-pass mode.
-* By default, a decompression context accepts window sizes <= (1 << ZSTD_WINDOWLOG_LIMIT_DEFAULT) */
-/* note : additional experimental parameters are also available
-* within the experimental section of the API.
-* At the time of this writing, they include :
-* ZSTD_c_format
-* Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
-* note : never ever use experimentalParam? names directly
-*/
-ZSTD_d_experimentalParam1=1000
-} ZSTD_dParameter;
-/*! ZSTD_dParam_getBounds() :
-*  All parameters must belong to an interval with lower and upper bounds,
-*  otherwise they will either trigger an error or be automatically clamped.
-* @return : a structure, ZSTD_bounds, which contains
-*         - an error status field, which must be tested using ZSTD_isError()
-*         - both lower and upper bounds, inclusive
-*/
-ZSTDLIB_API ZSTD_bounds ZSTD_dParam_getBounds(ZSTD_dParameter dParam);
-/*! ZSTD_DCtx_setParameter() :
-*  Set one compression parameter, selected by enum ZSTD_dParameter.
-*  All parameters have valid bounds. Bounds can be queried using ZSTD_dParam_getBounds().
-*  Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter).
-*  Setting a parameter is only possible during frame initialization (before starting decompression).
-* @return : 0, or an error code (which can be tested using ZSTD_isError()).
-*/
-ZSTDLIB_API size_t ZSTD_DCtx_setParameter(ZSTD_DCtx* dctx, ZSTD_dParameter param, int value);
 /*! ZSTD_DCtx_loadDictionary() :
 *  Create an internal DDict from dict buffer,
 *  to be used to decompress next frames.
 *  The dictionary remains valid for all future frames, until explicitly invalidated.
 * @result : 0, or an error code (which can be tested with ZSTD_isError()).
 *           A full dictionary is more costly, as it requires building tables.
 */
 ZSTDLIB_API size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx,
 const void* prefix, size_t prefixSize);
-/*! ZSTD_DCtx_reset() :
+/* ===   Memory management   === */
-*  Return a DCtx to clean state.
-*  Session and parameters can be reset jointly or separately.
+/*! ZSTD_sizeof_*() :
-*  Parameters can only be reset when no active frame is being decompressed.
+*  These functions give the _current_ memory usage of selected object.
-* @return : 0, or an error code, which can be tested with ZSTD_isError()
+*  Note that object memory usage can evolve (increase or decrease) over time. */
-*/
+ZSTDLIB_API size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx);
-ZSTDLIB_API size_t ZSTD_DCtx_reset(ZSTD_DCtx* dctx, ZSTD_ResetDirective reset);
+ZSTDLIB_API size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx* dctx);
+ZSTDLIB_API size_t ZSTD_sizeof_CStream(const ZSTD_CStream* zcs);
+ZSTDLIB_API size_t ZSTD_sizeof_DStream(const ZSTD_DStream* zds);
+ZSTDLIB_API size_t ZSTD_sizeof_CDict(const ZSTD_CDict* cdict);
+ZSTDLIB_API size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
+#endif  /* ZSTD_H_235446 */
+/* **************************************************************************************
+*   ADVANCED AND EXPERIMENTAL FUNCTIONS
+****************************************************************************************
+* The definitions in the following section are considered experimental.
+* They are provided for advanced scenarios.
+* They should never be used with a dynamic library, as prototypes may change in the future.
+* Use them only in association with static linking.
+* ***************************************************************************************/
+#if defined(ZSTD_STATIC_LINKING_ONLY) && !defined(ZSTD_H_ZSTD_STATIC_LINKING_ONLY)
+#define ZSTD_H_ZSTD_STATIC_LINKING_ONLY
 /****************************************************************************************
 *   experimental API (static linking only)
 ****************************************************************************************
 * The following symbols and constants
 #define ZSTD_OVERLAPLOG_MAX       9
 #define ZSTD_WINDOWLOG_LIMIT_DEFAULT 27   /* by default, the streaming decoder will refuse any frame
 * requiring larger than (1<<ZSTD_WINDOWLOG_LIMIT_DEFAULT) window size,
 * to preserve host's memory from unreasonable requirements.
-* This limit can be overriden using ZSTD_DCtx_setParameter(,ZSTD_d_windowLogMax,).
+* This limit can be overridden using ZSTD_DCtx_setParameter(,ZSTD_d_windowLogMax,).
 * The limit does not apply for one-pass decoders (such as ZSTD_decompress()), since no additional memory is allocated */
 /* LDM parameter bounds */
 #define ZSTD_LDM_HASHLOG_MIN      ZSTD_HASHLOG_MIN
 #define ZSTD_LDM_MINMATCH_MAX     4096
 #define ZSTD_LDM_BUCKETSIZELOG_MIN   1
 #define ZSTD_LDM_BUCKETSIZELOG_MAX   8
 #define ZSTD_LDM_HASHRATELOG_MIN     0
 #define ZSTD_LDM_HASHRATELOG_MAX (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN)
+/* Advanced parameter bounds */
+#define ZSTD_TARGETCBLOCKSIZE_MIN   64
+#define ZSTD_TARGETCBLOCKSIZE_MAX   ZSTD_BLOCKSIZE_MAX
 /* internal */
 #define ZSTD_HASHLOG3_MAX           17
 ZSTD_dictDefaultAttach = 0, /* Use the default heuristic. */
 ZSTD_dictForceAttach   = 1, /* Never copy the dictionary. */
 ZSTD_dictForceCopy     = 2, /* Always copy the dictionary. */
 } ZSTD_dictAttachPref_e;
+typedef enum {
+ZSTD_lcm_auto = 0,          /**< Automatically determine the compression mode based on the compression level.
+*   Negative compression levels will be uncompressed, and positive compression
+*   levels will be compressed. */
+ZSTD_lcm_huffman = 1,       /**< Always attempt Huffman compression. Uncompressed literals will still be
+*   emitted if Huffman compression is not profitable. */
+ZSTD_lcm_uncompressed = 2,  /**< Always emit uncompressed literals. */
+} ZSTD_literalCompressionMode_e;
 /***************************************
 *  Frame size functions
 ***************************************/
 /*! ZSTD_findDecompressedSize() :
-*  `src` should point the start of a series of ZSTD encoded and/or skippable frames
+*  `src` should point to the start of a series of ZSTD encoded and/or skippable frames
 *  `srcSize` must be the _exact_ size of this series
-*       (i.e. there should be a frame boundary exactly at `srcSize` bytes after `src`)
+*       (i.e. there should be a frame boundary at `src + srcSize`)
 *  @return : - decompressed size of all data in all successive frames
 *            - if the decompressed size cannot be determined: ZSTD_CONTENTSIZE_UNKNOWN
 *            - if an error occurred: ZSTD_CONTENTSIZE_ERROR
 *
 *   note 1 : decompressed size is an optional field, that may not be present, especially in streaming mode.
 *   note 5 : ZSTD_findDecompressedSize handles multiple frames, and so it must traverse the input to
 *            read each contained frame header.  This is fast as most of the data is skipped,
 *            however it does mean that all frame data must be present and valid. */
 ZSTDLIB_API unsigned long long ZSTD_findDecompressedSize(const void* src, size_t srcSize);
+/*! ZSTD_decompressBound() :
+*  `src` should point to the start of a series of ZSTD encoded and/or skippable frames
+*  `srcSize` must be the _exact_ size of this series
+*       (i.e. there should be a frame boundary at `src + srcSize`)
+*  @return : - upper-bound for the decompressed size of all data in all successive frames
+*            - if an error occured: ZSTD_CONTENTSIZE_ERROR
+*
+*  note 1  : an error can occur if `src` contains an invalid or incorrectly formatted frame.
+*  note 2  : the upper-bound is exact when the decompressed size field is available in every ZSTD encoded frame of `src`.
+*            in this case, `ZSTD_findDecompressedSize` and `ZSTD_decompressBound` return the same value.
+*  note 3  : when the decompressed size field isn't available, the upper-bound for that frame is calculated by:
+*              upper-bound = # blocks * min(128 KB, Window_Size)
+*/
+ZSTDLIB_API unsigned long long ZSTD_decompressBound(const void* src, size_t srcSize);
 /*! ZSTD_frameHeaderSize() :
 *  srcSize must be >= ZSTD_FRAMEHEADERSIZE_PREFIX.
 * @return : size of the Frame Header,
 *           or an error code (if srcSize is too small) */
 ZSTDLIB_API size_t ZSTD_frameHeaderSize(const void* src, size_t srcSize);
 *  of a future {D,C}Ctx, before its creation.
 *  ZSTD_estimateCCtxSize() will provide a budget large enough for any compression level up to selected one.
 *  It will also consider src size to be arbitrarily "large", which is worst case.
 *  If srcSize is known to always be small, ZSTD_estimateCCtxSize_usingCParams() can provide a tighter estimation.
 *  ZSTD_estimateCCtxSize_usingCParams() can be used in tandem with ZSTD_getCParams() to create cParams from compressionLevel.
-*  ZSTD_estimateCCtxSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParam_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_c_nbWorkers is >= 1.
+*  ZSTD_estimateCCtxSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParams_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_c_nbWorkers is >= 1.
 *  Note : CCtx size estimation is only correct for single-threaded compression. */
 ZSTDLIB_API size_t ZSTD_estimateCCtxSize(int compressionLevel);
 ZSTDLIB_API size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams);
 ZSTDLIB_API size_t ZSTD_estimateCCtxSize_usingCCtxParams(const ZSTD_CCtx_params* params);
 ZSTDLIB_API size_t ZSTD_estimateDCtxSize(void);
 /*! ZSTD_estimateCStreamSize() :
 *  ZSTD_estimateCStreamSize() will provide a budget large enough for any compression level up to selected one.
 *  It will also consider src size to be arbitrarily "large", which is worst case.
 *  If srcSize is known to always be small, ZSTD_estimateCStreamSize_usingCParams() can provide a tighter estimation.
 *  ZSTD_estimateCStreamSize_usingCParams() can be used in tandem with ZSTD_getCParams() to create cParams from compressionLevel.
-*  ZSTD_estimateCStreamSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParam_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_c_nbWorkers is >= 1.
+*  ZSTD_estimateCStreamSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParams_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_c_nbWorkers is >= 1.
 *  Note : CStream size estimation is only correct for single-threaded compression.
 *  ZSTD_DStream memory budget depends on window Size.
 *  This information can be passed manually, using ZSTD_estimateDStreamSize,
 *  or deducted from a valid frame Header, using ZSTD_estimateDStreamSize_fromFrame();
 *  Note : if streaming is init with function ZSTD_init?Stream_usingDict(),
 *  As a consequence, `dictBuffer` **must** outlive CDict,
 *  and its content must remain unmodified throughout the lifetime of CDict. */
 ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel);
 /*! ZSTD_getCParams() :
-*   @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize.
+* @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize.
-*   `estimatedSrcSize` value is optional, select 0 if not known */
+* `estimatedSrcSize` value is optional, select 0 if not known */
 ZSTDLIB_API ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize);
 /*! ZSTD_getParams() :
-*   same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of sub-component `ZSTD_compressionParameters`.
+*  same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of sub-component `ZSTD_compressionParameters`.
-*   All fields of `ZSTD_frameParameters` are set to default : contentSize=1, checksum=0, noDictID=0 */
+*  All fields of `ZSTD_frameParameters` are set to default : contentSize=1, checksum=0, noDictID=0 */
 ZSTDLIB_API ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize);
 /*! ZSTD_checkCParams() :
-*   Ensure param values remain within authorized range */
+*  Ensure param values remain within authorized range.
+* @return 0 on success, or an error code (can be checked with ZSTD_isError()) */
 ZSTDLIB_API size_t ZSTD_checkCParams(ZSTD_compressionParameters params);
 /*! ZSTD_adjustCParams() :
 *  optimize params for a given `srcSize` and `dictSize`.
-*  both values are optional, select `0` if unknown. */
+* `srcSize` can be unknown, in which case use ZSTD_CONTENTSIZE_UNKNOWN.
+* `dictSize` must be `0` when there is no dictionary.
+*  cPar can be invalid : all parameters will be clamped within valid range in the @return struct.
+*  This function never fails (wide contract) */
 ZSTDLIB_API ZSTD_compressionParameters ZSTD_adjustCParams(ZSTD_compressionParameters cPar, unsigned long long srcSize, size_t dictSize);
 /*! ZSTD_compress_advanced() :
 *  Same as ZSTD_compress_usingDict(), with fine-tune control over compression parameters (by structure) */
 ZSTDLIB_API size_t ZSTD_compress_advanced(ZSTD_CCtx* cctx,
 * are used in place, or copied into the working context.
 * Accepts values from the ZSTD_dictAttachPref_e enum.
 * See the comments on that enum for an explanation of the feature. */
 #define ZSTD_c_forceAttachDict ZSTD_c_experimentalParam4
+/* Controls how the literals are compressed (default is auto).
+* The value must be of type ZSTD_literalCompressionMode_e.
+* See ZSTD_literalCompressionMode_t enum definition for details.
+*/
+#define ZSTD_c_literalCompressionMode ZSTD_c_experimentalParam5
+/* Tries to fit compressed block size to be around targetCBlockSize.
+* No target when targetCBlockSize == 0.
+* There is no guarantee on compressed block size (default:0) */
+#define ZSTD_c_targetCBlockSize ZSTD_c_experimentalParam6
 /*! ZSTD_CCtx_getParameter() :
 *  Get the requested compression parameter value, selected by enum ZSTD_cParameter,
 *  and store it into int* value.
 * @return : 0, or an error code (which can be tested with ZSTD_isError()).
 */
 /*! ZSTD_CCtx_params :
 *  Quick howto :
 *  - ZSTD_createCCtxParams() : Create a ZSTD_CCtx_params structure
-*  - ZSTD_CCtxParam_setParameter() : Push parameters one by one into
+*  - ZSTD_CCtxParams_setParameter() : Push parameters one by one into
-*                                    an existing ZSTD_CCtx_params structure.
+*                                     an existing ZSTD_CCtx_params structure.
-*                                    This is similar to
+*                                     This is similar to
-*                                    ZSTD_CCtx_setParameter().
+*                                     ZSTD_CCtx_setParameter().
 *  - ZSTD_CCtx_setParametersUsingCCtxParams() : Apply parameters to
 *                                    an existing CCtx.
 *                                    These parameters will be applied to
 *                                    all subsequent frames.
 *  - ZSTD_compressStream2() : Do compression using the CCtx.
 *  Initializes the compression and frame parameters of cctxParams according to
 *  params. All other parameters are reset to their default values.
 */
 ZSTDLIB_API size_t ZSTD_CCtxParams_init_advanced(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params);
-/*! ZSTD_CCtxParam_setParameter() :
+/*! ZSTD_CCtxParams_setParameter() :
 *  Similar to ZSTD_CCtx_setParameter.
 *  Set one compression parameter, selected by enum ZSTD_cParameter.
 *  Parameters must be applied to a ZSTD_CCtx using ZSTD_CCtx_setParametersUsingCCtxParams().
 * @result : 0, or an error code (which can be tested with ZSTD_isError()).
 */
-ZSTDLIB_API size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value);
+ZSTDLIB_API size_t ZSTD_CCtxParams_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value);
-/*! ZSTD_CCtxParam_getParameter() :
+/*! ZSTD_CCtxParams_getParameter() :
 * Similar to ZSTD_CCtx_getParameter.
 * Get the requested value of one compression parameter, selected by enum ZSTD_cParameter.
 * @result : 0, or an error code (which can be tested with ZSTD_isError()).
 */
-ZSTDLIB_API size_t ZSTD_CCtxParam_getParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int* value);
+ZSTDLIB_API size_t ZSTD_CCtxParams_getParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int* value);
 /*! ZSTD_CCtx_setParametersUsingCCtxParams() :
 *  Apply a set of ZSTD_CCtx_params to the compression context.
 *  This can be done even after compression is started,
 *    if nbWorkers==0, this will have no impact until a new compression is started.
 *  Dictionary content is referenced, and therefore stays in dictBuffer.
 *  It is important that dictBuffer outlives DDict,
 *  it must remain read accessible throughout the lifetime of DDict */
 ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict_byReference(const void* dictBuffer, size_t dictSize);
-/*! ZSTD_getDictID_fromDict() :
-*  Provides the dictID stored within dictionary.
-*  if @return == 0, the dictionary is not conformant with Zstandard specification.
-*  It can still be loaded, but as a content-only dictionary. */
-ZSTDLIB_API unsigned ZSTD_getDictID_fromDict(const void* dict, size_t dictSize);
-/*! ZSTD_getDictID_fromDDict() :
-*  Provides the dictID of the dictionary loaded into `ddict`.
-*  If @return == 0, the dictionary is not conformant to Zstandard specification, or empty.
-*  Non-conformant dictionaries can still be loaded, but as content-only dictionaries. */
-ZSTDLIB_API unsigned ZSTD_getDictID_fromDDict(const ZSTD_DDict* ddict);
-/*! ZSTD_getDictID_fromFrame() :
-*  Provides the dictID required to decompressed the frame stored within `src`.
-*  If @return == 0, the dictID could not be decoded.
-*  This could for one of the following reasons :
-*  - The frame does not require a dictionary to be decoded (most common case).
-*  - The frame was built with dictID intentionally removed. Whatever dictionary is necessary is a hidden information.
-*    Note : this use case also happens when using a non-conformant dictionary.
-*  - `srcSize` is too small, and as a result, the frame header could not be decoded (only possible if `srcSize < ZSTD_FRAMEHEADERSIZE_MAX`).
-*  - This is not a Zstandard frame.
-*  When identifying the exact failure cause, it's possible to use ZSTD_getFrameHeader(), which will provide a more precise error code. */
-ZSTDLIB_API unsigned ZSTD_getDictID_fromFrame(const void* src, size_t srcSize);
 /*! ZSTD_DCtx_loadDictionary_byReference() :
 *  Same as ZSTD_DCtx_loadDictionary(),
 *  but references `dict` content instead of copying it into `dctx`.
 *  This saves memory if `dict` remains around.,
 *  However, it's imperative that `dict` remains accessible (and unmodified) while being used, so it must outlive decompression. */
 *  Once Advanced API reaches "stable" status,
 *  redundant functions will be deprecated, and then at some point removed.
 ********************************************************************/
 /*=====   Advanced Streaming compression functions  =====*/
-ZSTDLIB_API size_t ZSTD_initCStream_srcSize(ZSTD_CStream* zcs, int compressionLevel, unsigned long long pledgedSrcSize);   /**< pledgedSrcSize must be correct. If it is not known at init time, use ZSTD_CONTENTSIZE_UNKNOWN. Note that, for compatibility with older programs, "0" also disables frame content size field. It may be enabled in the future. */
+/**! ZSTD_initCStream_srcSize() :
-ZSTDLIB_API size_t ZSTD_initCStream_usingDict(ZSTD_CStream* zcs, const void* dict, size_t dictSize, int compressionLevel); /**< creates of an internal CDict (incompatible with static CCtx), except if dict == NULL or dictSize < 8, in which case no dict is used. Note: dict is loaded with ZSTD_dm_auto (treated as a full zstd dictionary if it begins with ZSTD_MAGIC_DICTIONARY, else as raw content) and ZSTD_dlm_byCopy.*/
+* This function is deprecated, and equivalent to:
+*     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
+*     ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
+*     ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
+*     ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
+*
+* pledgedSrcSize must be correct. If it is not known at init time, use
+* ZSTD_CONTENTSIZE_UNKNOWN. Note that, for compatibility with older programs,
+* "0" also disables frame content size field. It may be enabled in the future.
+*/
+ZSTDLIB_API size_t ZSTD_initCStream_srcSize(ZSTD_CStream* zcs, int compressionLevel, unsigned long long pledgedSrcSize);
+/**! ZSTD_initCStream_usingDict() :
+* This function is deprecated, and is equivalent to:
+*     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
+*     ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
+*     ZSTD_CCtx_loadDictionary(zcs, dict, dictSize);
+*
+* Creates of an internal CDict (incompatible with static CCtx), except if
+* dict == NULL or dictSize < 8, in which case no dict is used.
+* Note: dict is loaded with ZSTD_dm_auto (treated as a full zstd dictionary if
+* it begins with ZSTD_MAGIC_DICTIONARY, else as raw content) and ZSTD_dlm_byCopy.
+*/
+ZSTDLIB_API size_t ZSTD_initCStream_usingDict(ZSTD_CStream* zcs, const void* dict, size_t dictSize, int compressionLevel);
+/**! ZSTD_initCStream_advanced() :
+* This function is deprecated, and is approximately equivalent to:
+*     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
+*     ZSTD_CCtx_setZstdParams(zcs, params); // Set the zstd params and leave the rest as-is
+*     ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
+*     ZSTD_CCtx_loadDictionary(zcs, dict, dictSize);
+*
+* pledgedSrcSize must be correct. If srcSize is not known at init time, use
+* value ZSTD_CONTENTSIZE_UNKNOWN. dict is loaded with ZSTD_dm_auto and ZSTD_dlm_byCopy.
+*/
 ZSTDLIB_API size_t ZSTD_initCStream_advanced(ZSTD_CStream* zcs, const void* dict, size_t dictSize,
-ZSTD_parameters params, unsigned long long pledgedSrcSize);  /**< pledgedSrcSize must be correct. If srcSize is not known at init time, use value ZSTD_CONTENTSIZE_UNKNOWN. dict is loaded with ZSTD_dm_auto and ZSTD_dlm_byCopy. */
+ZSTD_parameters params, unsigned long long pledgedSrcSize);
-ZSTDLIB_API size_t ZSTD_initCStream_usingCDict(ZSTD_CStream* zcs, const ZSTD_CDict* cdict);  /**< note : cdict will just be referenced, and must outlive compression session */
+/**! ZSTD_initCStream_usingCDict() :
-ZSTDLIB_API size_t ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, const ZSTD_CDict* cdict, ZSTD_frameParameters fParams, unsigned long long pledgedSrcSize);  /**< same as ZSTD_initCStream_usingCDict(), with control over frame parameters. pledgedSrcSize must be correct. If srcSize is not known at init time, use value ZSTD_CONTENTSIZE_UNKNOWN. */
+* This function is deprecated, and equivalent to:
+*     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
+*     ZSTD_CCtx_refCDict(zcs, cdict);
+*
+* note : cdict will just be referenced, and must outlive compression session
+*/
+ZSTDLIB_API size_t ZSTD_initCStream_usingCDict(ZSTD_CStream* zcs, const ZSTD_CDict* cdict);
+/**! ZSTD_initCStream_usingCDict_advanced() :
+* This function is deprecated, and is approximately equivalent to:
+*     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
+*     ZSTD_CCtx_setZstdFrameParams(zcs, fParams); // Set the zstd frame params and leave the rest as-is
+*     ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
+*     ZSTD_CCtx_refCDict(zcs, cdict);
+*
+* same as ZSTD_initCStream_usingCDict(), with control over frame parameters.
+* pledgedSrcSize must be correct. If srcSize is not known at init time, use
+* value ZSTD_CONTENTSIZE_UNKNOWN.
+*/
+ZSTDLIB_API size_t ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, const ZSTD_CDict* cdict, ZSTD_frameParameters fParams, unsigned long long pledgedSrcSize);
 /*! ZSTD_resetCStream() :
+* This function is deprecated, and is equivalent to:
+*     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
+*     ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
+*
 *  start a new frame, using same parameters from previous frame.
 *  This is typically useful to skip dictionary loading stage, since it will re-use it in-place.
 *  Note that zcs must be init at least once before using ZSTD_resetCStream().
 *  If pledgedSrcSize is not known at reset time, use macro ZSTD_CONTENTSIZE_UNKNOWN.
 *  If pledgedSrcSize > 0, its value must be correct, as it will be written in header, and controlled at the end.
 */
 ZSTDLIB_API size_t ZSTD_toFlushNow(ZSTD_CCtx* cctx);
 /*=====   Advanced Streaming decompression functions  =====*/
-ZSTDLIB_API size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize); /**< note: no dictionary will be used if dict == NULL or dictSize < 8 */
+/**
-ZSTDLIB_API size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict);  /**< note : ddict is referenced, it must outlive decompression session */
+* This function is deprecated, and is equivalent to:
-ZSTDLIB_API size_t ZSTD_resetDStream(ZSTD_DStream* zds);  /**< re-use decompression parameters from previous init; saves dictionary loading */
+*
+*     ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
+*     ZSTD_DCtx_loadDictionary(zds, dict, dictSize);
+*
+* note: no dictionary will be used if dict == NULL or dictSize < 8
+*/
+ZSTDLIB_API size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize);
+/**
+* This function is deprecated, and is equivalent to:
+*
+*     ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
+*     ZSTD_DCtx_refDDict(zds, ddict);
+*
+* note : ddict is referenced, it must outlive decompression session
+*/
+ZSTDLIB_API size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict);
+/**
+* This function is deprecated, and is equivalent to:
+*
+*     ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
+*
+* re-use decompression parameters from previous init; saves dictionary loading
+*/
+ZSTDLIB_API size_t ZSTD_resetDStream(ZSTD_DStream* zds);
 /*********************************************************************
 *  Buffer-less and synchronous inner streaming functions
 *
 unsigned headerSize;
 unsigned dictID;
 unsigned checksumFlag;
 } ZSTD_frameHeader;
-/** ZSTD_getFrameHeader() :
+/*! ZSTD_getFrameHeader() :
 *  decode Frame Header, or requires larger `srcSize`.
 * @return : 0, `zfhPtr` is correctly filled,
 *          >0, `srcSize` is too small, value is wanted `srcSize` amount,
 *           or an error code, which can be tested using ZSTD_isError() */
 ZSTDLIB_API size_t ZSTD_getFrameHeader(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize);   /**< doesn't consume input */
 /* ============================ */
 /*!
 Block functions produce and decode raw zstd blocks, without frame metadata.
 Frame metadata cost is typically ~18 bytes, which can be non-negligible for very small blocks (< 100 bytes).
-User will have to take in charge required information to regenerate data, such as compressed and content sizes.
+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
 + copyCCtx() and copyDCtx() can be used too
 - 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, really consider using regular ZSTD_compress() instead.
++ 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.
+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 zero.
+- When a block is considered not compressible enough, ZSTD_compressBlock() result will be 0 (zero) !
-In which case, nothing is produced into `dst` !
+===> In which case, nothing is produced into `dst` !
-+ User must test for such outcome and deal directly with uncompressed data
++ User __must__ test for such outcome and deal directly with uncompressed data
-+ ZSTD_decompressBlock() doesn't accept uncompressed data as input !!!
++ 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.
 */

changeset 42937	69de49c4e39c
parent 42070	675775c33ab6
child 43994	de7838053207