Browse code

Update zstd and lz4 versions

Mike Smith authored on 29/11/2020 12:26:04
Showing1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,2090 @@
1
+/*
2
+ * Copyright (c) 2016-2020, Yann Collet, Facebook, Inc.
3
+ * All rights reserved.
4
+ *
5
+ * This source code is licensed under both the BSD-style license (found in the
6
+ * LICENSE file in the root directory of this source tree) and the GPLv2 (found
7
+ * in the COPYING file in the root directory of this source tree).
8
+ * You may select, at your option, one of the above-listed licenses.
9
+ */
10
+#if defined (__cplusplus)
11
+extern "C" {
12
+#endif
13
+
14
+#ifndef ZSTD_H_235446
15
+#define ZSTD_H_235446
16
+
17
+/* ======   Dependency   ======*/
18
+#include <limits.h>   /* INT_MAX */
19
+#include <stddef.h>   /* size_t */
20
+
21
+
22
+/* =====   ZSTDLIB_API : control library symbols visibility   ===== */
23
+#ifndef ZSTDLIB_VISIBILITY
24
+#  if defined(__GNUC__) && (__GNUC__ >= 4)
25
+#    define ZSTDLIB_VISIBILITY __attribute__ ((visibility ("default")))
26
+#  else
27
+#    define ZSTDLIB_VISIBILITY
28
+#  endif
29
+#endif
30
+#if defined(ZSTD_DLL_EXPORT) && (ZSTD_DLL_EXPORT==1)
31
+#  define ZSTDLIB_API __declspec(dllexport) ZSTDLIB_VISIBILITY
32
+#elif defined(ZSTD_DLL_IMPORT) && (ZSTD_DLL_IMPORT==1)
33
+#  define ZSTDLIB_API __declspec(dllimport) ZSTDLIB_VISIBILITY /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/
34
+#else
35
+#  define ZSTDLIB_API ZSTDLIB_VISIBILITY
36
+#endif
37
+
38
+
39
+/*******************************************************************************
40
+  Introduction
41
+
42
+  zstd, short for Zstandard, is a fast lossless compression algorithm, targeting
43
+  real-time compression scenarios at zlib-level and better compression ratios.
44
+  The zstd compression library provides in-memory compression and decompression
45
+  functions.
46
+
47
+  The library supports regular compression levels from 1 up to ZSTD_maxCLevel(),
48
+  which is currently 22. Levels >= 20, labeled `--ultra`, should be used with
49
+  caution, as they require more memory. The library also offers negative
50
+  compression levels, which extend the range of speed vs. ratio preferences.
51
+  The lower the level, the faster the speed (at the cost of compression).
52
+
53
+  Compression can be done in:
54
+    - a single step (described as Simple API)
55
+    - a single step, reusing a context (described as Explicit context)
56
+    - unbounded multiple steps (described as Streaming compression)
57
+
58
+  The compression ratio achievable on small data can be highly improved using
59
+  a dictionary. Dictionary compression can be performed in:
60
+    - a single step (described as Simple dictionary API)
61
+    - a single step, reusing a dictionary (described as Bulk-processing
62
+      dictionary API)
63
+
64
+  Advanced experimental functions can be accessed using
65
+  `#define ZSTD_STATIC_LINKING_ONLY` before including zstd.h.
66
+
67
+  Advanced experimental APIs should never be used with a dynamically-linked
68
+  library. They are not "stable"; their definitions or signatures may change in
69
+  the future. Only static linking is allowed.
70
+*******************************************************************************/
71
+
72
+/*------   Version   ------*/
73
+#define ZSTD_VERSION_MAJOR    1
74
+#define ZSTD_VERSION_MINOR    4
75
+#define ZSTD_VERSION_RELEASE  5
76
+
77
+#define ZSTD_VERSION_NUMBER  (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE)
78
+ZSTDLIB_API unsigned ZSTD_versionNumber(void);   /**< to check runtime library version */
79
+
80
+#define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE
81
+#define ZSTD_QUOTE(str) #str
82
+#define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str)
83
+#define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)
84
+ZSTDLIB_API const char* ZSTD_versionString(void);   /* requires v1.3.0+ */
85
+
86
+/* *************************************
87
+ *  Default constant
88
+ ***************************************/
89
+#ifndef ZSTD_CLEVEL_DEFAULT
90
+#  define ZSTD_CLEVEL_DEFAULT 3
91
+#endif
92
+
93
+/* *************************************
94
+ *  Constants
95
+ ***************************************/
96
+
97
+/* All magic numbers are supposed read/written to/from files/memory using little-endian convention */
98
+#define ZSTD_MAGICNUMBER            0xFD2FB528    /* valid since v0.8.0 */
99
+#define ZSTD_MAGIC_DICTIONARY       0xEC30A437    /* valid since v0.7.0 */
100
+#define ZSTD_MAGIC_SKIPPABLE_START  0x184D2A50    /* all 16 values, from 0x184D2A50 to 0x184D2A5F, signal the beginning of a skippable frame */
101
+#define ZSTD_MAGIC_SKIPPABLE_MASK   0xFFFFFFF0
102
+
103
+#define ZSTD_BLOCKSIZELOG_MAX  17
104
+#define ZSTD_BLOCKSIZE_MAX     (1<<ZSTD_BLOCKSIZELOG_MAX)
105
+
106
+
107
+
108
+/***************************************
109
+*  Simple API
110
+***************************************/
111
+/*! ZSTD_compress() :
112
+ *  Compresses `src` content as a single zstd compressed frame into already allocated `dst`.
113
+ *  Hint : compression runs faster if `dstCapacity` >=  `ZSTD_compressBound(srcSize)`.
114
+ *  @return : compressed size written into `dst` (<= `dstCapacity),
115
+ *            or an error code if it fails (which can be tested using ZSTD_isError()). */
116
+ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity,
117
+                            const void* src, size_t srcSize,
118
+                                  int compressionLevel);
119
+
120
+/*! ZSTD_decompress() :
121
+ *  `compressedSize` : must be the _exact_ size of some number of compressed and/or skippable frames.
122
+ *  `dstCapacity` is an upper bound of originalSize to regenerate.
123
+ *  If user cannot imply a maximum upper bound, it's better to use streaming mode to decompress data.
124
+ *  @return : the number of bytes decompressed into `dst` (<= `dstCapacity`),
125
+ *            or an errorCode if it fails (which can be tested using ZSTD_isError()). */
126
+ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,
127
+                              const void* src, size_t compressedSize);
128
+
129
+/*! ZSTD_getFrameContentSize() : requires v1.3.0+
130
+ *  `src` should point to the start of a ZSTD encoded frame.
131
+ *  `srcSize` must be at least as large as the frame header.
132
+ *            hint : any size >= `ZSTD_frameHeaderSize_max` is large enough.
133
+ *  @return : - decompressed size of `src` frame content, if known
134
+ *            - ZSTD_CONTENTSIZE_UNKNOWN if the size cannot be determined
135
+ *            - ZSTD_CONTENTSIZE_ERROR if an error occurred (e.g. invalid magic number, srcSize too small)
136
+ *   note 1 : a 0 return value means the frame is valid but "empty".
137
+ *   note 2 : decompressed size is an optional field, it may not be present, typically in streaming mode.
138
+ *            When `return==ZSTD_CONTENTSIZE_UNKNOWN`, data to decompress could be any size.
139
+ *            In which case, it's necessary to use streaming mode to decompress data.
140
+ *            Optionally, application can rely on some implicit limit,
141
+ *            as ZSTD_decompress() only needs an upper bound of decompressed size.
142
+ *            (For example, data could be necessarily cut into blocks <= 16 KB).
143
+ *   note 3 : decompressed size is always present when compression is completed using single-pass functions,
144
+ *            such as ZSTD_compress(), ZSTD_compressCCtx() ZSTD_compress_usingDict() or ZSTD_compress_usingCDict().
145
+ *   note 4 : decompressed size can be very large (64-bits value),
146
+ *            potentially larger than what local system can handle as a single memory segment.
147
+ *            In which case, it's necessary to use streaming mode to decompress data.
148
+ *   note 5 : If source is untrusted, decompressed size could be wrong or intentionally modified.
149
+ *            Always ensure return value fits within application's authorized limits.
150
+ *            Each application can set its own limits.
151
+ *   note 6 : This function replaces ZSTD_getDecompressedSize() */
152
+#define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1)
153
+#define ZSTD_CONTENTSIZE_ERROR   (0ULL - 2)
154
+ZSTDLIB_API unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize);
155
+
156
+/*! ZSTD_getDecompressedSize() :
157
+ *  NOTE: This function is now obsolete, in favor of ZSTD_getFrameContentSize().
158
+ *  Both functions work the same way, but ZSTD_getDecompressedSize() blends
159
+ *  "empty", "unknown" and "error" results to the same return value (0),
160
+ *  while ZSTD_getFrameContentSize() gives them separate return values.
161
+ * @return : decompressed size of `src` frame content _if known and not empty_, 0 otherwise. */
162
+ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);
163
+
164
+/*! ZSTD_findFrameCompressedSize() :
165
+ * `src` should point to the start of a ZSTD frame or skippable frame.
166
+ * `srcSize` must be >= first frame size
167
+ * @return : the compressed size of the first frame starting at `src`,
168
+ *           suitable to pass as `srcSize` to `ZSTD_decompress` or similar,
169
+ *        or an error code if input is invalid */
170
+ZSTDLIB_API size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
171
+
172
+
173
+/*======  Helper functions  ======*/
174
+#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 */
175
+ZSTDLIB_API size_t      ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */
176
+ZSTDLIB_API unsigned    ZSTD_isError(size_t code);          /*!< tells if a `size_t` function result is an error code */
177
+ZSTDLIB_API const char* ZSTD_getErrorName(size_t code);     /*!< provides readable string from an error code */
178
+ZSTDLIB_API int         ZSTD_minCLevel(void);               /*!< minimum negative compression level allowed */
179
+ZSTDLIB_API int         ZSTD_maxCLevel(void);               /*!< maximum compression level available */
180
+
181
+
182
+/***************************************
183
+*  Explicit context
184
+***************************************/
185
+/*= Compression context
186
+ *  When compressing many times,
187
+ *  it is recommended to allocate a context just once,
188
+ *  and re-use it for each successive compression operation.
189
+ *  This will make workload friendlier for system's memory.
190
+ *  Note : re-using context is just a speed / resource optimization.
191
+ *         It doesn't change the compression ratio, which remains identical.
192
+ *  Note 2 : In multi-threaded environments,
193
+ *         use one different context per thread for parallel execution.
194
+ */
195
+typedef struct ZSTD_CCtx_s ZSTD_CCtx;
196
+ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void);
197
+ZSTDLIB_API size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);
198
+
199
+/*! ZSTD_compressCCtx() :
200
+ *  Same as ZSTD_compress(), using an explicit ZSTD_CCtx.
201
+ *  Important : in order to behave similarly to `ZSTD_compress()`,
202
+ *  this function compresses at requested compression level,
203
+ *  __ignoring any other parameter__ .
204
+ *  If any advanced parameter was set using the advanced API,
205
+ *  they will all be reset. Only `compressionLevel` remains.
206
+ */
207
+ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* cctx,
208
+                                     void* dst, size_t dstCapacity,
209
+                               const void* src, size_t srcSize,
210
+                                     int compressionLevel);
211
+
212
+/*= Decompression context
213
+ *  When decompressing many times,
214
+ *  it is recommended to allocate a context only once,
215
+ *  and re-use it for each successive compression operation.
216
+ *  This will make workload friendlier for system's memory.
217
+ *  Use one context per thread for parallel execution. */
218
+typedef struct ZSTD_DCtx_s ZSTD_DCtx;
219
+ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void);
220
+ZSTDLIB_API size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);
221
+
222
+/*! ZSTD_decompressDCtx() :
223
+ *  Same as ZSTD_decompress(),
224
+ *  requires an allocated ZSTD_DCtx.
225
+ *  Compatible with sticky parameters.
226
+ */
227
+ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* dctx,
228
+                                       void* dst, size_t dstCapacity,
229
+                                 const void* src, size_t srcSize);
230
+
231
+
232
+/***************************************
233
+*  Advanced compression API
234
+***************************************/
235
+
236
+/* API design :
237
+ *   Parameters are pushed one by one into an existing context,
238
+ *   using ZSTD_CCtx_set*() functions.
239
+ *   Pushed parameters are sticky : they are valid for next compressed frame, and any subsequent frame.
240
+ *   "sticky" parameters are applicable to `ZSTD_compress2()` and `ZSTD_compressStream*()` !
241
+ *   __They do not apply to "simple" one-shot variants such as ZSTD_compressCCtx()__ .
242
+ *
243
+ *   It's possible to reset all parameters to "default" using ZSTD_CCtx_reset().
244
+ *
245
+ *   This API supercedes all other "advanced" API entry points in the experimental section.
246
+ *   In the future, we expect to remove from experimental API entry points which are redundant with this API.
247
+ */
248
+
249
+
250
+/* Compression strategies, listed from fastest to strongest */
251
+typedef enum { ZSTD_fast=1,
252
+               ZSTD_dfast=2,
253
+               ZSTD_greedy=3,
254
+               ZSTD_lazy=4,
255
+               ZSTD_lazy2=5,
256
+               ZSTD_btlazy2=6,
257
+               ZSTD_btopt=7,
258
+               ZSTD_btultra=8,
259
+               ZSTD_btultra2=9
260
+               /* note : new strategies _might_ be added in the future.
261
+                         Only the order (from fast to strong) is guaranteed */
262
+} ZSTD_strategy;
263
+
264
+
265
+typedef enum {
266
+
267
+    /* compression parameters
268
+     * Note: When compressing with a ZSTD_CDict these parameters are superseded
269
+     * by the parameters used to construct the ZSTD_CDict.
270
+     * See ZSTD_CCtx_refCDict() for more info (superseded-by-cdict). */
271
+    ZSTD_c_compressionLevel=100, /* Set compression parameters according to pre-defined cLevel table.
272
+                              * Note that exact compression parameters are dynamically determined,
273
+                              * depending on both compression level and srcSize (when known).
274
+                              * Default level is ZSTD_CLEVEL_DEFAULT==3.
275
+                              * Special: value 0 means default, which is controlled by ZSTD_CLEVEL_DEFAULT.
276
+                              * Note 1 : it's possible to pass a negative compression level.
277
+                              * Note 2 : setting a level does not automatically set all other compression parameters
278
+                              *   to default. Setting this will however eventually dynamically impact the compression
279
+                              *   parameters which have not been manually set. The manually set
280
+                              *   ones will 'stick'. */
281
+    /* Advanced compression parameters :
282
+     * It's possible to pin down compression parameters to some specific values.
283
+     * In which case, these values are no longer dynamically selected by the compressor */
284
+    ZSTD_c_windowLog=101,    /* Maximum allowed back-reference distance, expressed as power of 2.
285
+                              * This will set a memory budget for streaming decompression,
286
+                              * with larger values requiring more memory
287
+                              * and typically compressing more.
288
+                              * Must be clamped between ZSTD_WINDOWLOG_MIN and ZSTD_WINDOWLOG_MAX.
289
+                              * Special: value 0 means "use default windowLog".
290
+                              * Note: Using a windowLog greater than ZSTD_WINDOWLOG_LIMIT_DEFAULT
291
+                              *       requires explicitly allowing such size at streaming decompression stage. */
292
+    ZSTD_c_hashLog=102,      /* Size of the initial probe table, as a power of 2.
293
+                              * Resulting memory usage is (1 << (hashLog+2)).
294
+                              * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX.
295
+                              * Larger tables improve compression ratio of strategies <= dFast,
296
+                              * and improve speed of strategies > dFast.
297
+                              * Special: value 0 means "use default hashLog". */
298
+    ZSTD_c_chainLog=103,     /* Size of the multi-probe search table, as a power of 2.
299
+                              * Resulting memory usage is (1 << (chainLog+2)).
300
+                              * Must be clamped between ZSTD_CHAINLOG_MIN and ZSTD_CHAINLOG_MAX.
301
+                              * Larger tables result in better and slower compression.
302
+                              * This parameter is useless for "fast" strategy.
303
+                              * It's still useful when using "dfast" strategy,
304
+                              * in which case it defines a secondary probe table.
305
+                              * Special: value 0 means "use default chainLog". */
306
+    ZSTD_c_searchLog=104,    /* Number of search attempts, as a power of 2.
307
+                              * More attempts result in better and slower compression.
308
+                              * This parameter is useless for "fast" and "dFast" strategies.
309
+                              * Special: value 0 means "use default searchLog". */
310
+    ZSTD_c_minMatch=105,     /* Minimum size of searched matches.
311
+                              * Note that Zstandard can still find matches of smaller size,
312
+                              * it just tweaks its search algorithm to look for this size and larger.
313
+                              * Larger values increase compression and decompression speed, but decrease ratio.
314
+                              * Must be clamped between ZSTD_MINMATCH_MIN and ZSTD_MINMATCH_MAX.
315
+                              * Note that currently, for all strategies < btopt, effective minimum is 4.
316
+                              *                    , for all strategies > fast, effective maximum is 6.
317
+                              * Special: value 0 means "use default minMatchLength". */
318
+    ZSTD_c_targetLength=106, /* Impact of this field depends on strategy.
319
+                              * For strategies btopt, btultra & btultra2:
320
+                              *     Length of Match considered "good enough" to stop search.
321
+                              *     Larger values make compression stronger, and slower.
322
+                              * For strategy fast:
323
+                              *     Distance between match sampling.
324
+                              *     Larger values make compression faster, and weaker.
325
+                              * Special: value 0 means "use default targetLength". */
326
+    ZSTD_c_strategy=107,     /* See ZSTD_strategy enum definition.
327
+                              * The higher the value of selected strategy, the more complex it is,
328
+                              * resulting in stronger and slower compression.
329
+                              * Special: value 0 means "use default strategy". */
330
+
331
+    /* LDM mode parameters */
332
+    ZSTD_c_enableLongDistanceMatching=160, /* Enable long distance matching.
333
+                                     * This parameter is designed to improve compression ratio
334
+                                     * for large inputs, by finding large matches at long distance.
335
+                                     * It increases memory usage and window size.
336
+                                     * Note: enabling this parameter increases default ZSTD_c_windowLog to 128 MB
337
+                                     * except when expressly set to a different value. */
338
+    ZSTD_c_ldmHashLog=161,   /* Size of the table for long distance matching, as a power of 2.
339
+                              * Larger values increase memory usage and compression ratio,
340
+                              * but decrease compression speed.
341
+                              * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX
342
+                              * default: windowlog - 7.
343
+                              * Special: value 0 means "automatically determine hashlog". */
344
+    ZSTD_c_ldmMinMatch=162,  /* Minimum match size for long distance matcher.
345
+                              * Larger/too small values usually decrease compression ratio.
346
+                              * Must be clamped between ZSTD_LDM_MINMATCH_MIN and ZSTD_LDM_MINMATCH_MAX.
347
+                              * Special: value 0 means "use default value" (default: 64). */
348
+    ZSTD_c_ldmBucketSizeLog=163, /* Log size of each bucket in the LDM hash table for collision resolution.
349
+                              * Larger values improve collision resolution but decrease compression speed.
350
+                              * The maximum value is ZSTD_LDM_BUCKETSIZELOG_MAX.
351
+                              * Special: value 0 means "use default value" (default: 3). */
352
+    ZSTD_c_ldmHashRateLog=164, /* Frequency of inserting/looking up entries into the LDM hash table.
353
+                              * Must be clamped between 0 and (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN).
354
+                              * Default is MAX(0, (windowLog - ldmHashLog)), optimizing hash table usage.
355
+                              * Larger values improve compression speed.
356
+                              * Deviating far from default value will likely result in a compression ratio decrease.
357
+                              * Special: value 0 means "automatically determine hashRateLog". */
358
+
359
+    /* frame parameters */
360
+    ZSTD_c_contentSizeFlag=200, /* Content size will be written into frame header _whenever known_ (default:1)
361
+                              * Content size must be known at the beginning of compression.
362
+                              * This is automatically the case when using ZSTD_compress2(),
363
+                              * For streaming scenarios, content size must be provided with ZSTD_CCtx_setPledgedSrcSize() */
364
+    ZSTD_c_checksumFlag=201, /* A 32-bits checksum of content is written at end of frame (default:0) */
365
+    ZSTD_c_dictIDFlag=202,   /* When applicable, dictionary's ID is written into frame header (default:1) */
366
+
367
+    /* multi-threading parameters */
368
+    /* These parameters are only useful if multi-threading is enabled (compiled with build macro ZSTD_MULTITHREAD).
369
+     * They return an error otherwise. */
370
+    ZSTD_c_nbWorkers=400,    /* Select how many threads will be spawned to compress in parallel.
371
+                              * When nbWorkers >= 1, triggers asynchronous mode when used with ZSTD_compressStream*() :
372
+                              * ZSTD_compressStream*() consumes input and flush output if possible, but immediately gives back control to caller,
373
+                              * while compression work is performed in parallel, within worker threads.
374
+                              * (note : a strong exception to this rule is when first invocation of ZSTD_compressStream2() sets ZSTD_e_end :
375
+                              *  in which case, ZSTD_compressStream2() delegates to ZSTD_compress2(), which is always a blocking call).
376
+                              * More workers improve speed, but also increase memory usage.
377
+                              * Default value is `0`, aka "single-threaded mode" : no worker is spawned, compression is performed inside Caller's thread, all invocations are blocking */
378
+    ZSTD_c_jobSize=401,      /* Size of a compression job. This value is enforced only when nbWorkers >= 1.
379
+                              * Each compression job is completed in parallel, so this value can indirectly impact the nb of active threads.
380
+                              * 0 means default, which is dynamically determined based on compression parameters.
381
+                              * Job size must be a minimum of overlap size, or 1 MB, whichever is largest.
382
+                              * The minimum size is automatically and transparently enforced. */
383
+    ZSTD_c_overlapLog=402,   /* Control the overlap size, as a fraction of window size.
384
+                              * The overlap size is an amount of data reloaded from previous job at the beginning of a new job.
385
+                              * It helps preserve compression ratio, while each job is compressed in parallel.
386
+                              * This value is enforced only when nbWorkers >= 1.
387
+                              * Larger values increase compression ratio, but decrease speed.
388
+                              * Possible values range from 0 to 9 :
389
+                              * - 0 means "default" : value will be determined by the library, depending on strategy
390
+                              * - 1 means "no overlap"
391
+                              * - 9 means "full overlap", using a full window size.
392
+                              * Each intermediate rank increases/decreases load size by a factor 2 :
393
+                              * 9: full window;  8: w/2;  7: w/4;  6: w/8;  5:w/16;  4: w/32;  3:w/64;  2:w/128;  1:no overlap;  0:default
394
+                              * default value varies between 6 and 9, depending on strategy */
395
+
396
+    /* note : additional experimental parameters are also available
397
+     * within the experimental section of the API.
398
+     * At the time of this writing, they include :
399
+     * ZSTD_c_rsyncable
400
+     * ZSTD_c_format
401
+     * ZSTD_c_forceMaxWindow
402
+     * ZSTD_c_forceAttachDict
403
+     * ZSTD_c_literalCompressionMode
404
+     * ZSTD_c_targetCBlockSize
405
+     * ZSTD_c_srcSizeHint
406
+     * Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
407
+     * note : never ever use experimentalParam? names directly;
408
+     *        also, the enums values themselves are unstable and can still change.
409
+     */
410
+     ZSTD_c_experimentalParam1=500,
411
+     ZSTD_c_experimentalParam2=10,
412
+     ZSTD_c_experimentalParam3=1000,
413
+     ZSTD_c_experimentalParam4=1001,
414
+     ZSTD_c_experimentalParam5=1002,
415
+     ZSTD_c_experimentalParam6=1003,
416
+     ZSTD_c_experimentalParam7=1004
417
+} ZSTD_cParameter;
418
+
419
+typedef struct {
420
+    size_t error;
421
+    int lowerBound;
422
+    int upperBound;
423
+} ZSTD_bounds;
424
+
425
+/*! ZSTD_cParam_getBounds() :
426
+ *  All parameters must belong to an interval with lower and upper bounds,
427
+ *  otherwise they will either trigger an error or be automatically clamped.
428
+ * @return : a structure, ZSTD_bounds, which contains
429
+ *         - an error status field, which must be tested using ZSTD_isError()
430
+ *         - lower and upper bounds, both inclusive
431
+ */
432
+ZSTDLIB_API ZSTD_bounds ZSTD_cParam_getBounds(ZSTD_cParameter cParam);
433
+
434
+/*! ZSTD_CCtx_setParameter() :
435
+ *  Set one compression parameter, selected by enum ZSTD_cParameter.
436
+ *  All parameters have valid bounds. Bounds can be queried using ZSTD_cParam_getBounds().
437
+ *  Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter).
438
+ *  Setting a parameter is generally only possible during frame initialization (before starting compression).
439
+ *  Exception : when using multi-threading mode (nbWorkers >= 1),
440
+ *              the following parameters can be updated _during_ compression (within same frame):
441
+ *              => compressionLevel, hashLog, chainLog, searchLog, minMatch, targetLength and strategy.
442
+ *              new parameters will be active for next job only (after a flush()).
443
+ * @return : an error code (which can be tested using ZSTD_isError()).
444
+ */
445
+ZSTDLIB_API size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, int value);
446
+
447
+/*! ZSTD_CCtx_setPledgedSrcSize() :
448
+ *  Total input data size to be compressed as a single frame.
449
+ *  Value will be written in frame header, unless if explicitly forbidden using ZSTD_c_contentSizeFlag.
450
+ *  This value will also be controlled at end of frame, and trigger an error if not respected.
451
+ * @result : 0, or an error code (which can be tested with ZSTD_isError()).
452
+ *  Note 1 : pledgedSrcSize==0 actually means zero, aka an empty frame.
453
+ *           In order to mean "unknown content size", pass constant ZSTD_CONTENTSIZE_UNKNOWN.
454
+ *           ZSTD_CONTENTSIZE_UNKNOWN is default value for any new frame.
455
+ *  Note 2 : pledgedSrcSize is only valid once, for the next frame.
456
+ *           It's discarded at the end of the frame, and replaced by ZSTD_CONTENTSIZE_UNKNOWN.
457
+ *  Note 3 : Whenever all input data is provided and consumed in a single round,
458
+ *           for example with ZSTD_compress2(),
459
+ *           or invoking immediately ZSTD_compressStream2(,,,ZSTD_e_end),
460
+ *           this value is automatically overridden by srcSize instead.
461
+ */
462
+ZSTDLIB_API size_t ZSTD_CCtx_setPledgedSrcSize(ZSTD_CCtx* cctx, unsigned long long pledgedSrcSize);
463
+
464
+typedef enum {
465
+    ZSTD_reset_session_only = 1,
466
+    ZSTD_reset_parameters = 2,
467
+    ZSTD_reset_session_and_parameters = 3
468
+} ZSTD_ResetDirective;
469
+
470
+/*! ZSTD_CCtx_reset() :
471
+ *  There are 2 different things that can be reset, independently or jointly :
472
+ *  - The session : will stop compressing current frame, and make CCtx ready to start a new one.
473
+ *                  Useful after an error, or to interrupt any ongoing compression.
474
+ *                  Any internal data not yet flushed is cancelled.
475
+ *                  Compression parameters and dictionary remain unchanged.
476
+ *                  They will be used to compress next frame.
477
+ *                  Resetting session never fails.
478
+ *  - The parameters : changes all parameters back to "default".
479
+ *                  This removes any reference to any dictionary too.
480
+ *                  Parameters can only be changed between 2 sessions (i.e. no compression is currently ongoing)
481
+ *                  otherwise the reset fails, and function returns an error value (which can be tested using ZSTD_isError())
482
+ *  - Both : similar to resetting the session, followed by resetting parameters.
483
+ */
484
+ZSTDLIB_API size_t ZSTD_CCtx_reset(ZSTD_CCtx* cctx, ZSTD_ResetDirective reset);
485
+
486
+/*! ZSTD_compress2() :
487
+ *  Behave the same as ZSTD_compressCCtx(), but compression parameters are set using the advanced API.
488
+ *  ZSTD_compress2() always starts a new frame.
489
+ *  Should cctx hold data from a previously unfinished frame, everything about it is forgotten.
490
+ *  - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
491
+ *  - The function is always blocking, returns when compression is completed.
492
+ *  Hint : compression runs faster if `dstCapacity` >=  `ZSTD_compressBound(srcSize)`.
493
+ * @return : compressed size written into `dst` (<= `dstCapacity),
494
+ *           or an error code if it fails (which can be tested using ZSTD_isError()).
495
+ */
496
+ZSTDLIB_API size_t ZSTD_compress2( ZSTD_CCtx* cctx,
497
+                                   void* dst, size_t dstCapacity,
498
+                             const void* src, size_t srcSize);
499
+
500
+
501
+/***************************************
502
+*  Advanced decompression API
503
+***************************************/
504
+
505
+/* The advanced API pushes parameters one by one into an existing DCtx context.
506
+ * Parameters are sticky, and remain valid for all following frames
507
+ * using the same DCtx context.
508
+ * It's possible to reset parameters to default values using ZSTD_DCtx_reset().
509
+ * Note : This API is compatible with existing ZSTD_decompressDCtx() and ZSTD_decompressStream().
510
+ *        Therefore, no new decompression function is necessary.
511
+ */
512
+
513
+typedef enum {
514
+
515
+    ZSTD_d_windowLogMax=100, /* Select a size limit (in power of 2) beyond which
516
+                              * the streaming API will refuse to allocate memory buffer
517
+                              * in order to protect the host from unreasonable memory requirements.
518
+                              * This parameter is only useful in streaming mode, since no internal buffer is allocated in single-pass mode.
519
+                              * By default, a decompression context accepts window sizes <= (1 << ZSTD_WINDOWLOG_LIMIT_DEFAULT).
520
+                              * Special: value 0 means "use default maximum windowLog". */
521
+
522
+    /* note : additional experimental parameters are also available
523
+     * within the experimental section of the API.
524
+     * At the time of this writing, they include :
525
+     * ZSTD_d_format
526
+     * ZSTD_d_stableOutBuffer
527
+     * Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
528
+     * note : never ever use experimentalParam? names directly
529
+     */
530
+     ZSTD_d_experimentalParam1=1000,
531
+     ZSTD_d_experimentalParam2=1001
532
+
533
+} ZSTD_dParameter;
534
+
535
+/*! ZSTD_dParam_getBounds() :
536
+ *  All parameters must belong to an interval with lower and upper bounds,
537
+ *  otherwise they will either trigger an error or be automatically clamped.
538
+ * @return : a structure, ZSTD_bounds, which contains
539
+ *         - an error status field, which must be tested using ZSTD_isError()
540
+ *         - both lower and upper bounds, inclusive
541
+ */
542
+ZSTDLIB_API ZSTD_bounds ZSTD_dParam_getBounds(ZSTD_dParameter dParam);
543
+
544
+/*! ZSTD_DCtx_setParameter() :
545
+ *  Set one compression parameter, selected by enum ZSTD_dParameter.
546
+ *  All parameters have valid bounds. Bounds can be queried using ZSTD_dParam_getBounds().
547
+ *  Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter).
548
+ *  Setting a parameter is only possible during frame initialization (before starting decompression).
549
+ * @return : 0, or an error code (which can be tested using ZSTD_isError()).
550
+ */
551
+ZSTDLIB_API size_t ZSTD_DCtx_setParameter(ZSTD_DCtx* dctx, ZSTD_dParameter param, int value);
552
+
553
+/*! ZSTD_DCtx_reset() :
554
+ *  Return a DCtx to clean state.
555
+ *  Session and parameters can be reset jointly or separately.
556
+ *  Parameters can only be reset when no active frame is being decompressed.
557
+ * @return : 0, or an error code, which can be tested with ZSTD_isError()
558
+ */
559
+ZSTDLIB_API size_t ZSTD_DCtx_reset(ZSTD_DCtx* dctx, ZSTD_ResetDirective reset);
560
+
561
+
562
+/****************************
563
+*  Streaming
564
+****************************/
565
+
566
+typedef struct ZSTD_inBuffer_s {
567
+  const void* src;    /**< start of input buffer */
568
+  size_t size;        /**< size of input buffer */
569
+  size_t pos;         /**< position where reading stopped. Will be updated. Necessarily 0 <= pos <= size */
570
+} ZSTD_inBuffer;
571
+
572
+typedef struct ZSTD_outBuffer_s {
573
+  void*  dst;         /**< start of output buffer */
574
+  size_t size;        /**< size of output buffer */
575
+  size_t pos;         /**< position where writing stopped. Will be updated. Necessarily 0 <= pos <= size */
576
+} ZSTD_outBuffer;
577
+
578
+
579
+
580
+/*-***********************************************************************
581
+*  Streaming compression - HowTo
582
+*
583
+*  A ZSTD_CStream object is required to track streaming operation.
584
+*  Use ZSTD_createCStream() and ZSTD_freeCStream() to create/release resources.
585
+*  ZSTD_CStream objects can be reused multiple times on consecutive compression operations.
586
+*  It is recommended to re-use ZSTD_CStream since it will play nicer with system's memory, by re-using already allocated memory.
587
+*
588
+*  For parallel execution, use one separate ZSTD_CStream per thread.
589
+*
590
+*  note : since v1.3.0, ZSTD_CStream and ZSTD_CCtx are the same thing.
591
+*
592
+*  Parameters are sticky : when starting a new compression on the same context,
593
+*  it will re-use the same sticky parameters as previous compression session.
594
+*  When in doubt, it's recommended to fully initialize the context before usage.
595
+*  Use ZSTD_CCtx_reset() to reset the context and ZSTD_CCtx_setParameter(),
596
+*  ZSTD_CCtx_setPledgedSrcSize(), or ZSTD_CCtx_loadDictionary() and friends to
597
+*  set more specific parameters, the pledged source size, or load a dictionary.
598
+*
599
+*  Use ZSTD_compressStream2() with ZSTD_e_continue as many times as necessary to
600
+*  consume input stream. The function will automatically update both `pos`
601
+*  fields within `input` and `output`.
602
+*  Note that the function may not consume the entire input, for example, because
603
+*  the output buffer is already full, in which case `input.pos < input.size`.
604
+*  The caller must check if input has been entirely consumed.
605
+*  If not, the caller must make some room to receive more compressed data,
606
+*  and then present again remaining input data.
607
+*  note: ZSTD_e_continue is guaranteed to make some forward progress when called,
608
+*        but doesn't guarantee maximal forward progress. This is especially relevant
609
+*        when compressing with multiple threads. The call won't block if it can
610
+*        consume some input, but if it can't it will wait for some, but not all,
611
+*        output to be flushed.
612
+* @return : provides a minimum amount of data remaining to be flushed from internal buffers
613
+*           or an error code, which can be tested using ZSTD_isError().
614
+*
615
+*  At any moment, it's possible to flush whatever data might remain stuck within internal buffer,
616
+*  using ZSTD_compressStream2() with ZSTD_e_flush. `output->pos` will be updated.
617
+*  Note that, if `output->size` is too small, a single invocation with ZSTD_e_flush might not be enough (return code > 0).
618
+*  In which case, make some room to receive more compressed data, and call again ZSTD_compressStream2() with ZSTD_e_flush.
619
+*  You must continue calling ZSTD_compressStream2() with ZSTD_e_flush until it returns 0, at which point you can change the
620
+*  operation.
621
+*  note: ZSTD_e_flush will flush as much output as possible, meaning when compressing with multiple threads, it will
622
+*        block until the flush is complete or the output buffer is full.
623
+*  @return : 0 if internal buffers are entirely flushed,
624
+*            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),
625
+*            or an error code, which can be tested using ZSTD_isError().
626
+*
627
+*  Calling ZSTD_compressStream2() with ZSTD_e_end instructs to finish a frame.
628
+*  It will perform a flush and write frame epilogue.
629
+*  The epilogue is required for decoders to consider a frame completed.
630
+*  flush operation is the same, and follows same rules as calling ZSTD_compressStream2() with ZSTD_e_flush.
631
+*  You must continue calling ZSTD_compressStream2() with ZSTD_e_end until it returns 0, at which point you are free to
632
+*  start a new frame.
633
+*  note: ZSTD_e_end will flush as much output as possible, meaning when compressing with multiple threads, it will
634
+*        block until the flush is complete or the output buffer is full.
635
+*  @return : 0 if frame fully completed and fully flushed,
636
+*            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),
637
+*            or an error code, which can be tested using ZSTD_isError().
638
+*
639
+* *******************************************************************/
640
+
641
+typedef ZSTD_CCtx ZSTD_CStream;  /**< CCtx and CStream are now effectively same object (>= v1.3.0) */
642
+                                 /* Continue to distinguish them for compatibility with older versions <= v1.2.0 */
643
+/*===== ZSTD_CStream management functions =====*/
644
+ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream(void);
645
+ZSTDLIB_API size_t ZSTD_freeCStream(ZSTD_CStream* zcs);
646
+
647
+/*===== Streaming compression functions =====*/
648
+typedef enum {
649
+    ZSTD_e_continue=0, /* collect more data, encoder decides when to output compressed result, for optimal compression ratio */
650
+    ZSTD_e_flush=1,    /* flush any data provided so far,
651
+                        * it creates (at least) one new block, that can be decoded immediately on reception;
652
+                        * frame will continue: any future data can still reference previously compressed data, improving compression.
653
+                        * note : multithreaded compression will block to flush as much output as possible. */
654
+    ZSTD_e_end=2       /* flush any remaining data _and_ close current frame.
655
+                        * note that frame is only closed after compressed data is fully flushed (return value == 0).
656
+                        * After that point, any additional data starts a new frame.
657
+                        * note : each frame is independent (does not reference any content from previous frame).
658
+                        : note : multithreaded compression will block to flush as much output as possible. */
659
+} ZSTD_EndDirective;
660
+
661
+/*! ZSTD_compressStream2() :
662
+ *  Behaves about the same as ZSTD_compressStream, with additional control on end directive.
663
+ *  - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
664
+ *  - Compression parameters cannot be changed once compression is started (save a list of exceptions in multi-threading mode)
665
+ *  - output->pos must be <= dstCapacity, input->pos must be <= srcSize
666
+ *  - output->pos and input->pos will be updated. They are guaranteed to remain below their respective limit.
667
+ *  - When nbWorkers==0 (default), function is blocking : it completes its job before returning to caller.
668
+ *  - 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,
669
+ *                                                  and then immediately returns, just indicating that there is some data remaining to be flushed.
670
+ *                                                  The function nonetheless guarantees forward progress : it will return only after it reads or write at least 1+ byte.
671
+ *  - 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.
672
+ *  - @return provides a minimum amount of data remaining to be flushed from internal buffers
673
+ *            or an error code, which can be tested using ZSTD_isError().
674
+ *            if @return != 0, flush is not fully completed, there is still some data left within internal buffers.
675
+ *            This is useful for ZSTD_e_flush, since in this case more flushes are necessary to empty all buffers.
676
+ *            For ZSTD_e_end, @return == 0 when internal buffers are fully flushed and frame is completed.
677
+ *  - after a ZSTD_e_end directive, if internal buffer is not fully flushed (@return != 0),
678
+ *            only ZSTD_e_end or ZSTD_e_flush operations are allowed.
679
+ *            Before starting a new compression job, or changing compression parameters,
680
+ *            it is required to fully flush internal buffers.
681
+ */
682
+ZSTDLIB_API size_t ZSTD_compressStream2( ZSTD_CCtx* cctx,
683
+                                         ZSTD_outBuffer* output,
684
+                                         ZSTD_inBuffer* input,
685
+                                         ZSTD_EndDirective endOp);
686
+
687
+
688
+/* These buffer sizes are softly recommended.
689
+ * They are not required : ZSTD_compressStream*() happily accepts any buffer size, for both input and output.
690
+ * Respecting the recommended size just makes it a bit easier for ZSTD_compressStream*(),
691
+ * reducing the amount of memory shuffling and buffering, resulting in minor performance savings.
692
+ *
693
+ * However, note that these recommendations are from the perspective of a C caller program.
694
+ * If the streaming interface is invoked from some other language,
695
+ * especially managed ones such as Java or Go, through a foreign function interface such as jni or cgo,
696
+ * a major performance rule is to reduce crossing such interface to an absolute minimum.
697
+ * It's not rare that performance ends being spent more into the interface, rather than compression itself.
698
+ * In which cases, prefer using large buffers, as large as practical,
699
+ * for both input and output, to reduce the nb of roundtrips.
700
+ */
701
+ZSTDLIB_API size_t ZSTD_CStreamInSize(void);    /**< recommended size for input buffer */
702
+ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block. */
703
+
704
+
705
+/* *****************************************************************************
706
+ * This following is a legacy streaming API.
707
+ * It can be replaced by ZSTD_CCtx_reset() and ZSTD_compressStream2().
708
+ * It is redundant, but remains fully supported.
709
+ * Advanced parameters and dictionary compression can only be used through the
710
+ * new API.
711
+ ******************************************************************************/
712
+
713
+/*!
714
+ * Equivalent to:
715
+ *
716
+ *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
717
+ *     ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
718
+ *     ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
719
+ */
720
+ZSTDLIB_API size_t ZSTD_initCStream(ZSTD_CStream* zcs, int compressionLevel);
721
+/*!
722
+ * Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
723
+ * NOTE: The return value is different. ZSTD_compressStream() returns a hint for
724
+ * the next read size (if non-zero and not an error). ZSTD_compressStream2()
725
+ * returns the minimum nb of bytes left to flush (if non-zero and not an error).
726
+ */
727
+ZSTDLIB_API size_t ZSTD_compressStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
728
+/*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush). */
729
+ZSTDLIB_API size_t ZSTD_flushStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
730
+/*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end). */
731
+ZSTDLIB_API size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
732
+
733
+
734
+/*-***************************************************************************
735
+*  Streaming decompression - HowTo
736
+*
737
+*  A ZSTD_DStream object is required to track streaming operations.
738
+*  Use ZSTD_createDStream() and ZSTD_freeDStream() to create/release resources.
739
+*  ZSTD_DStream objects can be re-used multiple times.
740
+*
741
+*  Use ZSTD_initDStream() to start a new decompression operation.
742
+* @return : recommended first input size
743
+*  Alternatively, use advanced API to set specific properties.
744
+*
745
+*  Use ZSTD_decompressStream() repetitively to consume your input.
746
+*  The function will update both `pos` fields.
747
+*  If `input.pos < input.size`, some input has not been consumed.
748
+*  It's up to the caller to present again remaining data.
749
+*  The function tries to flush all data decoded immediately, respecting output buffer size.
750
+*  If `output.pos < output.size`, decoder has flushed everything it could.
751
+*  But if `output.pos == output.size`, there might be some data left within internal buffers.,
752
+*  In which case, call ZSTD_decompressStream() again to flush whatever remains in the buffer.
753
+*  Note : with no additional input provided, amount of data flushed is necessarily <= ZSTD_BLOCKSIZE_MAX.
754
+* @return : 0 when a frame is completely decoded and fully flushed,
755
+*        or an error code, which can be tested using ZSTD_isError(),
756
+*        or any other value > 0, which means there is still some decoding or flushing to do to complete current frame :
757
+*                                the return value is a suggested next input size (just a hint for better latency)
758
+*                                that will never request more than the remaining frame size.
759
+* *******************************************************************************/
760
+
761
+typedef ZSTD_DCtx ZSTD_DStream;  /**< DCtx and DStream are now effectively same object (>= v1.3.0) */
762
+                                 /* For compatibility with versions <= v1.2.0, prefer differentiating them. */
763
+/*===== ZSTD_DStream management functions =====*/
764
+ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream(void);
765
+ZSTDLIB_API size_t ZSTD_freeDStream(ZSTD_DStream* zds);
766
+
767
+/*===== Streaming decompression functions =====*/
768
+
769
+/* This function is redundant with the advanced API and equivalent to:
770
+ *
771
+ *     ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
772
+ *     ZSTD_DCtx_refDDict(zds, NULL);
773
+ */
774
+ZSTDLIB_API size_t ZSTD_initDStream(ZSTD_DStream* zds);
775
+
776
+ZSTDLIB_API size_t ZSTD_decompressStream(ZSTD_DStream* zds, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
777
+
778
+ZSTDLIB_API size_t ZSTD_DStreamInSize(void);    /*!< recommended size for input buffer */
779
+ZSTDLIB_API size_t ZSTD_DStreamOutSize(void);   /*!< recommended size for output buffer. Guarantee to successfully flush at least one complete block in all circumstances. */
780
+
781
+
782
+/**************************
783
+*  Simple dictionary API
784
+***************************/
785
+/*! ZSTD_compress_usingDict() :
786
+ *  Compression at an explicit compression level using a Dictionary.
787
+ *  A dictionary can be any arbitrary data segment (also called a prefix),
788
+ *  or a buffer with specified information (see dictBuilder/zdict.h).
789
+ *  Note : This function loads the dictionary, resulting in significant startup delay.
790
+ *         It's intended for a dictionary used only once.
791
+ *  Note 2 : When `dict == NULL || dictSize < 8` no dictionary is used. */
792
+ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
793
+                                           void* dst, size_t dstCapacity,
794
+                                     const void* src, size_t srcSize,
795
+                                     const void* dict,size_t dictSize,
796
+                                           int compressionLevel);
797
+
798
+/*! ZSTD_decompress_usingDict() :
799
+ *  Decompression using a known Dictionary.
800
+ *  Dictionary must be identical to the one used during compression.
801
+ *  Note : This function loads the dictionary, resulting in significant startup delay.
802
+ *         It's intended for a dictionary used only once.
803
+ *  Note : When `dict == NULL || dictSize < 8` no dictionary is used. */
804
+ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx,
805
+                                             void* dst, size_t dstCapacity,
806
+                                       const void* src, size_t srcSize,
807
+                                       const void* dict,size_t dictSize);
808
+
809
+
810
+/***********************************
811
+ *  Bulk processing dictionary API
812
+ **********************************/
813
+typedef struct ZSTD_CDict_s ZSTD_CDict;
814
+
815
+/*! ZSTD_createCDict() :
816
+ *  When compressing multiple messages or blocks using the same dictionary,
817
+ *  it's recommended to digest the dictionary only once, since it's a costly operation.
818
+ *  ZSTD_createCDict() will create a state from digesting a dictionary.
819
+ *  The resulting state can be used for future compression operations with very limited startup cost.
820
+ *  ZSTD_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only.
821
+ * @dictBuffer can be released after ZSTD_CDict creation, because its content is copied within CDict.
822
+ *  Note 1 : Consider experimental function `ZSTD_createCDict_byReference()` if you prefer to not duplicate @dictBuffer content.
823
+ *  Note 2 : A ZSTD_CDict can be created from an empty @dictBuffer,
824
+ *      in which case the only thing that it transports is the @compressionLevel.
825
+ *      This can be useful in a pipeline featuring ZSTD_compress_usingCDict() exclusively,
826
+ *      expecting a ZSTD_CDict parameter with any data, including those without a known dictionary. */
827
+ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize,
828
+                                         int compressionLevel);
829
+
830
+/*! ZSTD_freeCDict() :
831
+ *  Function frees memory allocated by ZSTD_createCDict(). */
832
+ZSTDLIB_API size_t      ZSTD_freeCDict(ZSTD_CDict* CDict);
833
+
834
+/*! ZSTD_compress_usingCDict() :
835
+ *  Compression using a digested Dictionary.
836
+ *  Recommended when same dictionary is used multiple times.
837
+ *  Note : compression level is _decided at dictionary creation time_,
838
+ *     and frame parameters are hardcoded (dictID=yes, contentSize=yes, checksum=no) */
839
+ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx,
840
+                                            void* dst, size_t dstCapacity,
841
+                                      const void* src, size_t srcSize,
842
+                                      const ZSTD_CDict* cdict);
843
+
844
+
845
+typedef struct ZSTD_DDict_s ZSTD_DDict;
846
+
847
+/*! ZSTD_createDDict() :
848
+ *  Create a digested dictionary, ready to start decompression operation without startup delay.
849
+ *  dictBuffer can be released after DDict creation, as its content is copied inside DDict. */
850
+ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dictBuffer, size_t dictSize);
851
+
852
+/*! ZSTD_freeDDict() :
853
+ *  Function frees memory allocated with ZSTD_createDDict() */
854
+ZSTDLIB_API size_t      ZSTD_freeDDict(ZSTD_DDict* ddict);
855
+
856
+/*! ZSTD_decompress_usingDDict() :
857
+ *  Decompression using a digested Dictionary.
858
+ *  Recommended when same dictionary is used multiple times. */
859
+ZSTDLIB_API size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx,
860
+                                              void* dst, size_t dstCapacity,
861
+                                        const void* src, size_t srcSize,
862
+                                        const ZSTD_DDict* ddict);
863
+
864
+
865
+/********************************
866
+ *  Dictionary helper functions
867
+ *******************************/
868
+
869
+/*! ZSTD_getDictID_fromDict() :
870
+ *  Provides the dictID stored within dictionary.
871
+ *  if @return == 0, the dictionary is not conformant with Zstandard specification.
872
+ *  It can still be loaded, but as a content-only dictionary. */
873
+ZSTDLIB_API unsigned ZSTD_getDictID_fromDict(const void* dict, size_t dictSize);
874
+
875
+/*! ZSTD_getDictID_fromDDict() :
876
+ *  Provides the dictID of the dictionary loaded into `ddict`.
877
+ *  If @return == 0, the dictionary is not conformant to Zstandard specification, or empty.
878
+ *  Non-conformant dictionaries can still be loaded, but as content-only dictionaries. */
879
+ZSTDLIB_API unsigned ZSTD_getDictID_fromDDict(const ZSTD_DDict* ddict);
880
+
881
+/*! ZSTD_getDictID_fromFrame() :
882
+ *  Provides the dictID required to decompressed the frame stored within `src`.
883
+ *  If @return == 0, the dictID could not be decoded.
884
+ *  This could for one of the following reasons :
885
+ *  - The frame does not require a dictionary to be decoded (most common case).
886
+ *  - The frame was built with dictID intentionally removed. Whatever dictionary is necessary is a hidden information.
887
+ *    Note : this use case also happens when using a non-conformant dictionary.
888
+ *  - `srcSize` is too small, and as a result, the frame header could not be decoded (only possible if `srcSize < ZSTD_FRAMEHEADERSIZE_MAX`).
889
+ *  - This is not a Zstandard frame.
890
+ *  When identifying the exact failure cause, it's possible to use ZSTD_getFrameHeader(), which will provide a more precise error code. */
891
+ZSTDLIB_API unsigned ZSTD_getDictID_fromFrame(const void* src, size_t srcSize);
892
+
893
+
894
+/*******************************************************************************
895
+ * Advanced dictionary and prefix API
896
+ *
897
+ * This API allows dictionaries to be used with ZSTD_compress2(),
898
+ * ZSTD_compressStream2(), and ZSTD_decompress(). Dictionaries are sticky, and
899
+ * only reset with the context is reset with ZSTD_reset_parameters or
900
+ * ZSTD_reset_session_and_parameters. Prefixes are single-use.
901
+ ******************************************************************************/
902
+
903
+
904
+/*! ZSTD_CCtx_loadDictionary() :
905
+ *  Create an internal CDict from `dict` buffer.
906
+ *  Decompression will have to use same dictionary.
907
+ * @result : 0, or an error code (which can be tested with ZSTD_isError()).
908
+ *  Special: Loading a NULL (or 0-size) dictionary invalidates previous dictionary,
909
+ *           meaning "return to no-dictionary mode".
910
+ *  Note 1 : Dictionary is sticky, it will be used for all future compressed frames.
911
+ *           To return to "no-dictionary" situation, load a NULL dictionary (or reset parameters).
912
+ *  Note 2 : Loading a dictionary involves building tables.
913
+ *           It's also a CPU consuming operation, with non-negligible impact on latency.
914
+ *           Tables are dependent on compression parameters, and for this reason,
915
+ *           compression parameters can no longer be changed after loading a dictionary.
916
+ *  Note 3 :`dict` content will be copied internally.
917
+ *           Use experimental ZSTD_CCtx_loadDictionary_byReference() to reference content instead.
918
+ *           In such a case, dictionary buffer must outlive its users.
919
+ *  Note 4 : Use ZSTD_CCtx_loadDictionary_advanced()
920
+ *           to precisely select how dictionary content must be interpreted. */
921
+ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary(ZSTD_CCtx* cctx, const void* dict, size_t dictSize);
922
+
923
+/*! ZSTD_CCtx_refCDict() :
924
+ *  Reference a prepared dictionary, to be used for all next compressed frames.
925
+ *  Note that compression parameters are enforced from within CDict,
926
+ *  and supersede any compression parameter previously set within CCtx.
927
+ *  The parameters ignored are labled as "superseded-by-cdict" in the ZSTD_cParameter enum docs.
928
+ *  The ignored parameters will be used again if the CCtx is returned to no-dictionary mode.
929
+ *  The dictionary will remain valid for future compressed frames using same CCtx.
930
+ * @result : 0, or an error code (which can be tested with ZSTD_isError()).
931
+ *  Special : Referencing a NULL CDict means "return to no-dictionary mode".
932
+ *  Note 1 : Currently, only one dictionary can be managed.
933
+ *           Referencing a new dictionary effectively "discards" any previous one.
934
+ *  Note 2 : CDict is just referenced, its lifetime must outlive its usage within CCtx. */
935
+ZSTDLIB_API size_t ZSTD_CCtx_refCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict);
936
+
937
+/*! ZSTD_CCtx_refPrefix() :
938
+ *  Reference a prefix (single-usage dictionary) for next compressed frame.
939
+ *  A prefix is **only used once**. Tables are discarded at end of frame (ZSTD_e_end).
940
+ *  Decompression will need same prefix to properly regenerate data.
941
+ *  Compressing with a prefix is similar in outcome as performing a diff and compressing it,
942
+ *  but performs much faster, especially during decompression (compression speed is tunable with compression level).
943
+ * @result : 0, or an error code (which can be tested with ZSTD_isError()).
944
+ *  Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary
945
+ *  Note 1 : Prefix buffer is referenced. It **must** outlive compression.
946
+ *           Its content must remain unmodified during compression.
947
+ *  Note 2 : If the intention is to diff some large src data blob with some prior version of itself,
948
+ *           ensure that the window size is large enough to contain the entire source.
949
+ *           See ZSTD_c_windowLog.
950
+ *  Note 3 : Referencing a prefix involves building tables, which are dependent on compression parameters.
951
+ *           It's a CPU consuming operation, with non-negligible impact on latency.
952
+ *           If there is a need to use the same prefix multiple times, consider loadDictionary instead.
953
+ *  Note 4 : By default, the prefix is interpreted as raw content (ZSTD_dct_rawContent).
954
+ *           Use experimental ZSTD_CCtx_refPrefix_advanced() to alter dictionary interpretation. */
955
+ZSTDLIB_API size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx,
956
+                                 const void* prefix, size_t prefixSize);
957
+
958
+/*! ZSTD_DCtx_loadDictionary() :
959
+ *  Create an internal DDict from dict buffer,
960
+ *  to be used to decompress next frames.
961
+ *  The dictionary remains valid for all future frames, until explicitly invalidated.
962
+ * @result : 0, or an error code (which can be tested with ZSTD_isError()).
963
+ *  Special : Adding a NULL (or 0-size) dictionary invalidates any previous dictionary,
964
+ *            meaning "return to no-dictionary mode".
965
+ *  Note 1 : Loading a dictionary involves building tables,
966
+ *           which has a non-negligible impact on CPU usage and latency.
967
+ *           It's recommended to "load once, use many times", to amortize the cost
968
+ *  Note 2 :`dict` content will be copied internally, so `dict` can be released after loading.
969
+ *           Use ZSTD_DCtx_loadDictionary_byReference() to reference dictionary content instead.
970
+ *  Note 3 : Use ZSTD_DCtx_loadDictionary_advanced() to take control of
971
+ *           how dictionary content is loaded and interpreted.
972
+ */
973
+ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary(ZSTD_DCtx* dctx, const void* dict, size_t dictSize);
974
+
975
+/*! ZSTD_DCtx_refDDict() :
976
+ *  Reference a prepared dictionary, to be used to decompress next frames.
977
+ *  The dictionary remains active for decompression of future frames using same DCtx.
978
+ * @result : 0, or an error code (which can be tested with ZSTD_isError()).
979
+ *  Note 1 : Currently, only one dictionary can be managed.
980
+ *           Referencing a new dictionary effectively "discards" any previous one.
981
+ *  Special: referencing a NULL DDict means "return to no-dictionary mode".
982
+ *  Note 2 : DDict is just referenced, its lifetime must outlive its usage from DCtx.
983
+ */
984
+ZSTDLIB_API size_t ZSTD_DCtx_refDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict);
985
+
986
+/*! ZSTD_DCtx_refPrefix() :
987
+ *  Reference a prefix (single-usage dictionary) to decompress next frame.
988
+ *  This is the reverse operation of ZSTD_CCtx_refPrefix(),
989
+ *  and must use the same prefix as the one used during compression.
990
+ *  Prefix is **only used once**. Reference is discarded at end of frame.
991
+ *  End of frame is reached when ZSTD_decompressStream() returns 0.
992
+ * @result : 0, or an error code (which can be tested with ZSTD_isError()).
993
+ *  Note 1 : Adding any prefix (including NULL) invalidates any previously set prefix or dictionary
994
+ *  Note 2 : Prefix buffer is referenced. It **must** outlive decompression.
995
+ *           Prefix buffer must remain unmodified up to the end of frame,
996
+ *           reached when ZSTD_decompressStream() returns 0.
997
+ *  Note 3 : By default, the prefix is treated as raw content (ZSTD_dct_rawContent).
998
+ *           Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode (Experimental section)
999
+ *  Note 4 : Referencing a raw content prefix has almost no cpu nor memory cost.
1000
+ *           A full dictionary is more costly, as it requires building tables.
1001
+ */
1002
+ZSTDLIB_API size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx,
1003
+                                 const void* prefix, size_t prefixSize);
1004
+
1005
+/* ===   Memory management   === */
1006
+
1007
+/*! ZSTD_sizeof_*() :
1008
+ *  These functions give the _current_ memory usage of selected object.
1009
+ *  Note that object memory usage can evolve (increase or decrease) over time. */
1010
+ZSTDLIB_API size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx);
1011
+ZSTDLIB_API size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx* dctx);
1012
+ZSTDLIB_API size_t ZSTD_sizeof_CStream(const ZSTD_CStream* zcs);
1013
+ZSTDLIB_API size_t ZSTD_sizeof_DStream(const ZSTD_DStream* zds);
1014
+ZSTDLIB_API size_t ZSTD_sizeof_CDict(const ZSTD_CDict* cdict);
1015
+ZSTDLIB_API size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
1016
+
1017
+#endif  /* ZSTD_H_235446 */
1018
+
1019
+
1020
+/* **************************************************************************************
1021
+ *   ADVANCED AND EXPERIMENTAL FUNCTIONS
1022
+ ****************************************************************************************
1023
+ * The definitions in the following section are considered experimental.
1024
+ * They are provided for advanced scenarios.
1025
+ * They should never be used with a dynamic library, as prototypes may change in the future.
1026
+ * Use them only in association with static linking.
1027
+ * ***************************************************************************************/
1028
+
1029
+#if defined(ZSTD_STATIC_LINKING_ONLY) && !defined(ZSTD_H_ZSTD_STATIC_LINKING_ONLY)
1030
+#define ZSTD_H_ZSTD_STATIC_LINKING_ONLY
1031
+
1032
+/****************************************************************************************
1033
+ *   experimental API (static linking only)
1034
+ ****************************************************************************************
1035
+ * The following symbols and constants
1036
+ * are not planned to join "stable API" status in the near future.
1037
+ * They can still change in future versions.
1038
+ * Some of them are planned to remain in the static_only section indefinitely.
1039
+ * Some of them might be removed in the future (especially when redundant with existing stable functions)
1040
+ * ***************************************************************************************/
1041
+
1042
+#define ZSTD_FRAMEHEADERSIZE_PREFIX(format) ((format) == ZSTD_f_zstd1 ? 5 : 1)   /* minimum input size required to query frame header size */
1043
+#define ZSTD_FRAMEHEADERSIZE_MIN(format)    ((format) == ZSTD_f_zstd1 ? 6 : 2)
1044
+#define ZSTD_FRAMEHEADERSIZE_MAX   18   /* can be useful for static allocation */
1045
+#define ZSTD_SKIPPABLEHEADERSIZE    8
1046
+
1047
+/* compression parameter bounds */
1048
+#define ZSTD_WINDOWLOG_MAX_32    30
1049
+#define ZSTD_WINDOWLOG_MAX_64    31
1050
+#define ZSTD_WINDOWLOG_MAX     ((int)(sizeof(size_t) == 4 ? ZSTD_WINDOWLOG_MAX_32 : ZSTD_WINDOWLOG_MAX_64))
1051
+#define ZSTD_WINDOWLOG_MIN       10
1052
+#define ZSTD_HASHLOG_MAX       ((ZSTD_WINDOWLOG_MAX < 30) ? ZSTD_WINDOWLOG_MAX : 30)
1053
+#define ZSTD_HASHLOG_MIN          6
1054
+#define ZSTD_CHAINLOG_MAX_32     29
1055
+#define ZSTD_CHAINLOG_MAX_64     30
1056
+#define ZSTD_CHAINLOG_MAX      ((int)(sizeof(size_t) == 4 ? ZSTD_CHAINLOG_MAX_32 : ZSTD_CHAINLOG_MAX_64))
1057
+#define ZSTD_CHAINLOG_MIN        ZSTD_HASHLOG_MIN
1058
+#define ZSTD_SEARCHLOG_MAX      (ZSTD_WINDOWLOG_MAX-1)
1059
+#define ZSTD_SEARCHLOG_MIN        1
1060
+#define ZSTD_MINMATCH_MAX         7   /* only for ZSTD_fast, other strategies are limited to 6 */
1061
+#define ZSTD_MINMATCH_MIN         3   /* only for ZSTD_btopt+, faster strategies are limited to 4 */
1062
+#define ZSTD_TARGETLENGTH_MAX    ZSTD_BLOCKSIZE_MAX
1063
+#define ZSTD_TARGETLENGTH_MIN     0   /* note : comparing this constant to an unsigned results in a tautological test */
1064
+#define ZSTD_STRATEGY_MIN        ZSTD_fast
1065
+#define ZSTD_STRATEGY_MAX        ZSTD_btultra2
1066
+
1067
+
1068
+#define ZSTD_OVERLAPLOG_MIN       0
1069
+#define ZSTD_OVERLAPLOG_MAX       9
1070
+
1071
+#define ZSTD_WINDOWLOG_LIMIT_DEFAULT 27   /* by default, the streaming decoder will refuse any frame
1072
+                                           * requiring larger than (1<<ZSTD_WINDOWLOG_LIMIT_DEFAULT) window size,
1073
+                                           * to preserve host's memory from unreasonable requirements.
1074
+                                           * This limit can be overridden using ZSTD_DCtx_setParameter(,ZSTD_d_windowLogMax,).
1075
+                                           * The limit does not apply for one-pass decoders (such as ZSTD_decompress()), since no additional memory is allocated */
1076
+
1077
+
1078
+/* LDM parameter bounds */
1079
+#define ZSTD_LDM_HASHLOG_MIN      ZSTD_HASHLOG_MIN
1080
+#define ZSTD_LDM_HASHLOG_MAX      ZSTD_HASHLOG_MAX
1081
+#define ZSTD_LDM_MINMATCH_MIN        4
1082
+#define ZSTD_LDM_MINMATCH_MAX     4096
1083
+#define ZSTD_LDM_BUCKETSIZELOG_MIN   1
1084
+#define ZSTD_LDM_BUCKETSIZELOG_MAX   8
1085
+#define ZSTD_LDM_HASHRATELOG_MIN     0
1086
+#define ZSTD_LDM_HASHRATELOG_MAX (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN)
1087
+
1088
+/* Advanced parameter bounds */
1089
+#define ZSTD_TARGETCBLOCKSIZE_MIN   64
1090
+#define ZSTD_TARGETCBLOCKSIZE_MAX   ZSTD_BLOCKSIZE_MAX
1091
+#define ZSTD_SRCSIZEHINT_MIN        0
1092
+#define ZSTD_SRCSIZEHINT_MAX        INT_MAX
1093
+
1094
+/* internal */
1095
+#define ZSTD_HASHLOG3_MAX           17
1096
+
1097
+
1098
+/* ---  Advanced types  --- */
1099
+
1100
+typedef struct ZSTD_CCtx_params_s ZSTD_CCtx_params;
1101
+
1102
+typedef struct {
1103
+    unsigned int matchPos; /* Match pos in dst */
1104
+    /* If seqDef.offset > 3, then this is seqDef.offset - 3
1105
+     * If seqDef.offset < 3, then this is the corresponding repeat offset
1106
+     * But if seqDef.offset < 3 and litLength == 0, this is the
1107
+     *   repeat offset before the corresponding repeat offset
1108
+     * And if seqDef.offset == 3 and litLength == 0, this is the
1109
+     *   most recent repeat offset - 1
1110
+     */
1111
+    unsigned int offset;
1112
+    unsigned int litLength; /* Literal length */
1113
+    unsigned int matchLength; /* Match length */
1114
+    /* 0 when seq not rep and seqDef.offset otherwise
1115
+     * when litLength == 0 this will be <= 4, otherwise <= 3 like normal
1116
+     */
1117
+    unsigned int rep;
1118
+} ZSTD_Sequence;
1119
+
1120
+typedef struct {
1121
+    unsigned windowLog;       /**< largest match distance : larger == more compression, more memory needed during decompression */
1122
+    unsigned chainLog;        /**< fully searched segment : larger == more compression, slower, more memory (useless for fast) */
1123
+    unsigned hashLog;         /**< dispatch table : larger == faster, more memory */
1124
+    unsigned searchLog;       /**< nb of searches : larger == more compression, slower */
1125
+    unsigned minMatch;        /**< match length searched : larger == faster decompression, sometimes less compression */
1126
+    unsigned targetLength;    /**< acceptable match size for optimal parser (only) : larger == more compression, slower */
1127
+    ZSTD_strategy strategy;   /**< see ZSTD_strategy definition above */
1128
+} ZSTD_compressionParameters;
1129
+
1130
+typedef struct {
1131
+    int contentSizeFlag; /**< 1: content size will be in frame header (when known) */
1132
+    int checksumFlag;    /**< 1: generate a 32-bits checksum using XXH64 algorithm at end of frame, for error detection */
1133
+    int noDictIDFlag;    /**< 1: no dictID will be saved into frame header (dictID is only useful for dictionary compression) */
1134
+} ZSTD_frameParameters;
1135
+
1136
+typedef struct {
1137
+    ZSTD_compressionParameters cParams;
1138
+    ZSTD_frameParameters fParams;
1139
+} ZSTD_parameters;
1140
+
1141
+typedef enum {
1142
+    ZSTD_dct_auto = 0,       /* dictionary is "full" when starting with ZSTD_MAGIC_DICTIONARY, otherwise it is "rawContent" */
1143
+    ZSTD_dct_rawContent = 1, /* ensures dictionary is always loaded as rawContent, even if it starts with ZSTD_MAGIC_DICTIONARY */
1144
+    ZSTD_dct_fullDict = 2    /* refuses to load a dictionary if it does not respect Zstandard's specification, starting with ZSTD_MAGIC_DICTIONARY */
1145
+} ZSTD_dictContentType_e;
1146
+
1147
+typedef enum {
1148
+    ZSTD_dlm_byCopy = 0,  /**< Copy dictionary content internally */
1149
+    ZSTD_dlm_byRef = 1    /**< Reference dictionary content -- the dictionary buffer must outlive its users. */
1150
+} ZSTD_dictLoadMethod_e;
1151
+
1152
+typedef enum {
1153
+    ZSTD_f_zstd1 = 0,           /* zstd frame format, specified in zstd_compression_format.md (default) */
1154
+    ZSTD_f_zstd1_magicless = 1  /* Variant of zstd frame format, without initial 4-bytes magic number.
1155
+                                 * Useful to save 4 bytes per generated frame.
1156
+                                 * Decoder cannot recognise automatically this format, requiring this instruction. */
1157
+} ZSTD_format_e;
1158
+
1159
+typedef enum {
1160
+    /* Note: this enum and the behavior it controls are effectively internal
1161
+     * implementation details of the compressor. They are expected to continue
1162
+     * to evolve and should be considered only in the context of extremely
1163
+     * advanced performance tuning.
1164
+     *
1165
+     * Zstd currently supports the use of a CDict in three ways:
1166
+     *
1167
+     * - The contents of the CDict can be copied into the working context. This
1168
+     *   means that the compression can search both the dictionary and input
1169
+     *   while operating on a single set of internal tables. This makes
1170
+     *   the compression faster per-byte of input. However, the initial copy of
1171
+     *   the CDict's tables incurs a fixed cost at the beginning of the
1172
+     *   compression. For small compressions (< 8 KB), that copy can dominate
1173
+     *   the cost of the compression.
1174
+     *
1175
+     * - The CDict's tables can be used in-place. In this model, compression is
1176
+     *   slower per input byte, because the compressor has to search two sets of
1177
+     *   tables. However, this model incurs no start-up cost (as long as the
1178
+     *   working context's tables can be reused). For small inputs, this can be
1179
+     *   faster than copying the CDict's tables.
1180
+     *
1181
+     * - The CDict's tables are not used at all, and instead we use the working
1182
+     *   context alone to reload the dictionary and use params based on the source
1183
+     *   size. See ZSTD_compress_insertDictionary() and ZSTD_compress_usingDict().
1184
+     *   This method is effective when the dictionary sizes are very small relative
1185
+     *   to the input size, and the input size is fairly large to begin with.
1186
+     *
1187
+     * Zstd has a simple internal heuristic that selects which strategy to use
1188
+     * at the beginning of a compression. However, if experimentation shows that
1189
+     * Zstd is making poor choices, it is possible to override that choice with
1190
+     * this enum.
1191
+     */
1192
+    ZSTD_dictDefaultAttach = 0, /* Use the default heuristic. */
1193
+    ZSTD_dictForceAttach   = 1, /* Never copy the dictionary. */
1194
+    ZSTD_dictForceCopy     = 2, /* Always copy the dictionary. */
1195
+    ZSTD_dictForceLoad     = 3  /* Always reload the dictionary */
1196
+} ZSTD_dictAttachPref_e;
1197
+
1198
+typedef enum {
1199
+  ZSTD_lcm_auto = 0,          /**< Automatically determine the compression mode based on the compression level.
1200
+                               *   Negative compression levels will be uncompressed, and positive compression
1201
+                               *   levels will be compressed. */
1202
+  ZSTD_lcm_huffman = 1,       /**< Always attempt Huffman compression. Uncompressed literals will still be
1203
+                               *   emitted if Huffman compression is not profitable. */
1204
+  ZSTD_lcm_uncompressed = 2   /**< Always emit uncompressed literals. */
1205
+} ZSTD_literalCompressionMode_e;
1206
+
1207
+
1208
+/***************************************
1209
+*  Frame size functions
1210
+***************************************/
1211
+
1212
+/*! ZSTD_findDecompressedSize() :
1213
+ *  `src` should point to the start of a series of ZSTD encoded and/or skippable frames
1214
+ *  `srcSize` must be the _exact_ size of this series
1215
+ *       (i.e. there should be a frame boundary at `src + srcSize`)
1216
+ *  @return : - decompressed size of all data in all successive frames
1217
+ *            - if the decompressed size cannot be determined: ZSTD_CONTENTSIZE_UNKNOWN
1218
+ *            - if an error occurred: ZSTD_CONTENTSIZE_ERROR
1219
+ *
1220
+ *   note 1 : decompressed size is an optional field, that may not be present, especially in streaming mode.
1221
+ *            When `return==ZSTD_CONTENTSIZE_UNKNOWN`, data to decompress could be any size.
1222
+ *            In which case, it's necessary to use streaming mode to decompress data.
1223
+ *   note 2 : decompressed size is always present when compression is done with ZSTD_compress()
1224
+ *   note 3 : decompressed size can be very large (64-bits value),
1225
+ *            potentially larger than what local system can handle as a single memory segment.
1226
+ *            In which case, it's necessary to use streaming mode to decompress data.
1227
+ *   note 4 : If source is untrusted, decompressed size could be wrong or intentionally modified.
1228
+ *            Always ensure result fits within application's authorized limits.
1229
+ *            Each application can set its own limits.
1230
+ *   note 5 : ZSTD_findDecompressedSize handles multiple frames, and so it must traverse the input to
1231
+ *            read each contained frame header.  This is fast as most of the data is skipped,
1232
+ *            however it does mean that all frame data must be present and valid. */
1233
+ZSTDLIB_API unsigned long long ZSTD_findDecompressedSize(const void* src, size_t srcSize);
1234
+
1235
+/*! ZSTD_decompressBound() :
1236
+ *  `src` should point to the start of a series of ZSTD encoded and/or skippable frames
1237
+ *  `srcSize` must be the _exact_ size of this series
1238
+ *       (i.e. there should be a frame boundary at `src + srcSize`)
1239
+ *  @return : - upper-bound for the decompressed size of all data in all successive frames
1240
+ *            - if an error occured: ZSTD_CONTENTSIZE_ERROR
1241
+ *
1242
+ *  note 1  : an error can occur if `src` contains an invalid or incorrectly formatted frame.
1243
+ *  note 2  : the upper-bound is exact when the decompressed size field is available in every ZSTD encoded frame of `src`.
1244
+ *            in this case, `ZSTD_findDecompressedSize` and `ZSTD_decompressBound` return the same value.
1245
+ *  note 3  : when the decompressed size field isn't available, the upper-bound for that frame is calculated by:
1246
+ *              upper-bound = # blocks * min(128 KB, Window_Size)
1247
+ */
1248
+ZSTDLIB_API unsigned long long ZSTD_decompressBound(const void* src, size_t srcSize);
1249
+
1250
+/*! ZSTD_frameHeaderSize() :
1251
+ *  srcSize must be >= ZSTD_FRAMEHEADERSIZE_PREFIX.
1252
+ * @return : size of the Frame Header,
1253
+ *           or an error code (if srcSize is too small) */
1254
+ZSTDLIB_API size_t ZSTD_frameHeaderSize(const void* src, size_t srcSize);
1255
+
1256
+/*! ZSTD_getSequences() :
1257
+ * Extract sequences from the sequence store
1258
+ * zc can be used to insert custom compression params.
1259
+ * This function invokes ZSTD_compress2
1260
+ * @return : number of sequences extracted
1261
+ */
1262
+ZSTDLIB_API size_t ZSTD_getSequences(ZSTD_CCtx* zc, ZSTD_Sequence* outSeqs,
1263
+    size_t outSeqsSize, const void* src, size_t srcSize);
1264
+
1265
+
1266
+/***************************************
1267
+*  Memory management
1268
+***************************************/
1269
+
1270
+/*! ZSTD_estimate*() :
1271
+ *  These functions make it possible to estimate memory usage
1272
+ *  of a future {D,C}Ctx, before its creation.
1273
+ *
1274
+ *  ZSTD_estimateCCtxSize() will provide a memory budget large enough
1275
+ *  for any compression level up to selected one.
1276
+ *  Note : Unlike ZSTD_estimateCStreamSize*(), this estimate
1277
+ *         does not include space for a window buffer.
1278
+ *         Therefore, the estimation is only guaranteed for single-shot compressions, not streaming.
1279
+ *  The estimate will assume the input may be arbitrarily large,
1280
+ *  which is the worst case.
1281
+ *
1282
+ *  When srcSize can be bound by a known and rather "small" value,
1283
+ *  this fact can be used to provide a tighter estimation
1284
+ *  because the CCtx compression context will need less memory.
1285
+ *  This tighter estimation can be provided by more advanced functions
1286
+ *  ZSTD_estimateCCtxSize_usingCParams(), which can be used in tandem with ZSTD_getCParams(),
1287
+ *  and ZSTD_estimateCCtxSize_usingCCtxParams(), which can be used in tandem with ZSTD_CCtxParams_setParameter().
1288
+ *  Both can be used to estimate memory using custom compression parameters and arbitrary srcSize limits.
1289
+ *
1290
+ *  Note 2 : only single-threaded compression is supported.
1291
+ *  ZSTD_estimateCCtxSize_usingCCtxParams() will return an error code if ZSTD_c_nbWorkers is >= 1.
1292
+ */
1293
+ZSTDLIB_API size_t ZSTD_estimateCCtxSize(int compressionLevel);
1294
+ZSTDLIB_API size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams);
1295
+ZSTDLIB_API size_t ZSTD_estimateCCtxSize_usingCCtxParams(const ZSTD_CCtx_params* params);
1296
+ZSTDLIB_API size_t ZSTD_estimateDCtxSize(void);
1297
+
1298
+/*! ZSTD_estimateCStreamSize() :
1299
+ *  ZSTD_estimateCStreamSize() will provide a budget large enough for any compression level up to selected one.
1300
+ *  It will also consider src size to be arbitrarily "large", which is worst case.
1301
+ *  If srcSize is known to always be small, ZSTD_estimateCStreamSize_usingCParams() can provide a tighter estimation.
1302
+ *  ZSTD_estimateCStreamSize_usingCParams() can be used in tandem with ZSTD_getCParams() to create cParams from compressionLevel.
1303
+ *  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.
1304
+ *  Note : CStream size estimation is only correct for single-threaded compression.
1305
+ *  ZSTD_DStream memory budget depends on window Size.
1306
+ *  This information can be passed manually, using ZSTD_estimateDStreamSize,
1307
+ *  or deducted from a valid frame Header, using ZSTD_estimateDStreamSize_fromFrame();
1308
+ *  Note : if streaming is init with function ZSTD_init?Stream_usingDict(),
1309
+ *         an internal ?Dict will be created, which additional size is not estimated here.
1310
+ *         In this case, get total size by adding ZSTD_estimate?DictSize */
1311
+ZSTDLIB_API size_t ZSTD_estimateCStreamSize(int compressionLevel);
1312
+ZSTDLIB_API size_t ZSTD_estimateCStreamSize_usingCParams(ZSTD_compressionParameters cParams);
1313
+ZSTDLIB_API size_t ZSTD_estimateCStreamSize_usingCCtxParams(const ZSTD_CCtx_params* params);
1314
+ZSTDLIB_API size_t ZSTD_estimateDStreamSize(size_t windowSize);
1315
+ZSTDLIB_API size_t ZSTD_estimateDStreamSize_fromFrame(const void* src, size_t srcSize);
1316
+
1317
+/*! ZSTD_estimate?DictSize() :
1318
+ *  ZSTD_estimateCDictSize() will bet that src size is relatively "small", and content is copied, like ZSTD_createCDict().
1319
+ *  ZSTD_estimateCDictSize_advanced() makes it possible to control compression parameters precisely, like ZSTD_createCDict_advanced().
1320
+ *  Note : dictionaries created by reference (`ZSTD_dlm_byRef`) are logically smaller.
1321
+ */
1322
+ZSTDLIB_API size_t ZSTD_estimateCDictSize(size_t dictSize, int compressionLevel);
1323
+ZSTDLIB_API size_t ZSTD_estimateCDictSize_advanced(size_t dictSize, ZSTD_compressionParameters cParams, ZSTD_dictLoadMethod_e dictLoadMethod);
1324
+ZSTDLIB_API size_t ZSTD_estimateDDictSize(size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod);
1325
+
1326
+/*! ZSTD_initStatic*() :
1327
+ *  Initialize an object using a pre-allocated fixed-size buffer.
1328
+ *  workspace: The memory area to emplace the object into.
1329
+ *             Provided pointer *must be 8-bytes aligned*.
1330
+ *             Buffer must outlive object.
1331
+ *  workspaceSize: Use ZSTD_estimate*Size() to determine
1332
+ *                 how large workspace must be to support target scenario.
1333
+ * @return : pointer to object (same address as workspace, just different type),
1334
+ *           or NULL if error (size too small, incorrect alignment, etc.)
1335
+ *  Note : zstd will never resize nor malloc() when using a static buffer.
1336
+ *         If the object requires more memory than available,
1337
+ *         zstd will just error out (typically ZSTD_error_memory_allocation).
1338
+ *  Note 2 : there is no corresponding "free" function.
1339
+ *           Since workspace is allocated externally, it must be freed externally too.
1340
+ *  Note 3 : cParams : use ZSTD_getCParams() to convert a compression level
1341
+ *           into its associated cParams.
1342
+ *  Limitation 1 : currently not compatible with internal dictionary creation, triggered by
1343
+ *                 ZSTD_CCtx_loadDictionary(), ZSTD_initCStream_usingDict() or ZSTD_initDStream_usingDict().
1344
+ *  Limitation 2 : static cctx currently not compatible with multi-threading.
1345
+ *  Limitation 3 : static dctx is incompatible with legacy support.
1346
+ */
1347
+ZSTDLIB_API ZSTD_CCtx*    ZSTD_initStaticCCtx(void* workspace, size_t workspaceSize);
1348
+ZSTDLIB_API ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize);    /**< same as ZSTD_initStaticCCtx() */
1349
+
1350
+ZSTDLIB_API ZSTD_DCtx*    ZSTD_initStaticDCtx(void* workspace, size_t workspaceSize);
1351
+ZSTDLIB_API ZSTD_DStream* ZSTD_initStaticDStream(void* workspace, size_t workspaceSize);    /**< same as ZSTD_initStaticDCtx() */