size_t ZSTD_CCtx_loadDictionary(ZSTD_CCtx* cctx, const void* dict, size_t dictSize); size_t ZSTD_CCtx_loadDictionary_byReference(ZSTD_CCtx* cctx, const void* dict, size_t dictSize); size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictMode_e dictMode); -Create an internal CDict from dict buffer. - Decompression will have to use same buffer. +
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()). - Special : Adding a NULL (or 0-size) dictionary invalidates any previous dictionary, - meaning "return to no-dictionary mode". - Note 1 : `dict` content will be copied internally. Use - ZSTD_CCtx_loadDictionary_byReference() to reference dictionary - content instead. The dictionary buffer must then outlive its - users. + Special: Adding a NULL (or 0-size) dictionary invalidates previous dictionary, + meaning "return to no-dictionary mode". + Note 1 : Dictionary will be used for all future compression jobs. + To return to "no-dictionary" situation, load a NULL dictionary Note 2 : Loading a dictionary involves building tables, which are dependent on compression parameters. For this reason, compression parameters cannot be changed anymore after loading a dictionary. - It's also a CPU-heavy operation, with non-negligible impact on latency. - Note 3 : Dictionary will be used for all future compression jobs. - To return to "no-dictionary" situation, load a NULL dictionary - Note 5 : Use ZSTD_CCtx_loadDictionary_advanced() to select how dictionary - content will be interpreted. - + It's also a CPU consuming operation, with non-negligible impact on latency. + Note 3 :`dict` content will be copied internally. + Use ZSTD_CCtx_loadDictionary_byReference() to reference dictionary content instead. + In such a case, dictionary buffer must outlive its users. + Note 4 : Use ZSTD_CCtx_loadDictionary_advanced() + to precisely select how dictionary content must be interpreted.
size_t ZSTD_CCtx_refCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict);
@@ -905,8 +917,7 @@ size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void* dict, size
Special : adding a NULL CDict means "return to no-dictionary mode".
Note 1 : Currently, only one dictionary can be managed.
Adding a new dictionary effectively "discards" any previous one.
- Note 2 : CDict is just referenced, its lifetime must outlive CCtx.
-
+ Note 2 : CDict is just referenced, its lifetime must outlive CCtx.
size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize); @@ -917,13 +928,12 @@ size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t Subsequent compression jobs will be done without prefix (if none is explicitly referenced). If there is a need to use same prefix multiple times, consider embedding it into a ZSTD_CDict instead. @result : 0, or an error code (which can be tested with ZSTD_isError()). - Special : Adding any prefix (including NULL) invalidates any previous prefix or dictionary + Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary Note 1 : Prefix buffer is referenced. It must outlive compression job. Note 2 : Referencing a prefix involves building tables, which are dependent on compression parameters. - It's a CPU-heavy operation, with non-negligible impact on latency. - Note 3 : By default, the prefix is treated as raw content - (ZSTD_dm_rawContent). Use ZSTD_CCtx_refPrefix_advanced() to alter - dictMode. + It's a CPU consuming operation, with non-negligible impact on latency. + Note 3 : By default, the prefix is treated as raw content (ZSTD_dm_rawContent). + Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode.
typedef enum {
diff --git a/lib/zstd.h b/lib/zstd.h
index 6cb7da7ab..5a1ad8aaf 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -976,9 +976,13 @@ typedef enum {
* Note that currently, for all strategies < btopt, effective minimum is 4.
* Note that currently, for all strategies > fast, effective maximum is 6.
* Special: value 0 means "do not change minMatchLength". */
- ZSTD_p_targetLength, /* Only useful for strategies >= btopt.
- * Length of Match considered "good enough" to stop search.
- * Larger values make compression stronger and slower.
+ ZSTD_p_targetLength, /* Impact of this field depends on strategy.
+ * For strategies btopt & btultra:
+ * Length of Match considered "good enough" to stop search.
+ * Larger values make compression stronger, and slower.
+ * For strategy fast:
+ * Distance between match sampling.
+ * Larger values make compression faster, and weaker.
* Special: value 0 means "do not change targetLength". */
ZSTD_p_compressionStrategy, /* See ZSTD_strategy enum definition.
* Cast selected strategy as unsigned for ZSTD_CCtx_setParameter() compatibility.
diff --git a/programs/zstd.1.md b/programs/zstd.1.md
index 447ac07fe..2e2dc54f8 100644
--- a/programs/zstd.1.md
+++ b/programs/zstd.1.md
@@ -347,14 +347,21 @@ The list of available _options_:
The minimum _slen_ is 3 and the maximum is 7.
- `targetLen`=_tlen_, `tlen`=_tlen_:
- Specify the minimum match length that causes a match finder to stop
- searching for better matches.
+ The impact of this field vary depending on selected strategy.
- A larger minimum match length usually improves compression ratio but
- decreases compression speed.
- This option is only used with strategies ZSTD_btopt and ZSTD_btultra.
+ For ZSTD\_btopt and ZSTD\_btultra, it specifies the minimum match length
+ that causes match finder to stop searching for better matches.
+ A larger `targetLen` usually improves compression ratio
+ but decreases compression speed.
- The minimum _tlen_ is 4 and the maximum is 999.
+ For ZSTD\_fast, it specifies
+ the amount of data skipped between match sampling.
+ Impact is reversed : a larger `targetLen` increases compression speed
+ but decreases compression ratio.
+
+ For all other strategies, this field has no impact.
+
+ The minimum _tlen_ is 1 and the maximum is 999.
- `overlapLog`=_ovlog_, `ovlog`=_ovlog_:
Determine `overlapSize`, amount of data reloaded from previous job.