zstd-ruby 1.3.3.0 → 1.3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. checksums.yaml +5 -5
  2. data/README.md +1 -1
  3. data/ext/zstdruby/libzstd/BUCK +13 -0
  4. data/ext/zstdruby/libzstd/README.md +32 -25
  5. data/ext/zstdruby/libzstd/common/bitstream.h +1 -1
  6. data/ext/zstdruby/libzstd/common/compiler.h +25 -0
  7. data/ext/zstdruby/libzstd/common/cpu.h +216 -0
  8. data/ext/zstdruby/libzstd/common/error_private.c +1 -0
  9. data/ext/zstdruby/libzstd/common/fse.h +1 -1
  10. data/ext/zstdruby/libzstd/common/fse_decompress.c +2 -2
  11. data/ext/zstdruby/libzstd/common/huf.h +114 -89
  12. data/ext/zstdruby/libzstd/common/pool.c +46 -17
  13. data/ext/zstdruby/libzstd/common/pool.h +18 -9
  14. data/ext/zstdruby/libzstd/common/threading.h +12 -12
  15. data/ext/zstdruby/libzstd/common/zstd_errors.h +16 -7
  16. data/ext/zstdruby/libzstd/common/zstd_internal.h +4 -5
  17. data/ext/zstdruby/libzstd/compress/fse_compress.c +19 -11
  18. data/ext/zstdruby/libzstd/compress/huf_compress.c +160 -62
  19. data/ext/zstdruby/libzstd/compress/zstd_compress.c +973 -644
  20. data/ext/zstdruby/libzstd/compress/zstd_compress_internal.h +281 -34
  21. data/ext/zstdruby/libzstd/compress/zstd_double_fast.c +80 -62
  22. data/ext/zstdruby/libzstd/compress/zstd_double_fast.h +11 -4
  23. data/ext/zstdruby/libzstd/compress/zstd_fast.c +87 -71
  24. data/ext/zstdruby/libzstd/compress/zstd_fast.h +10 -6
  25. data/ext/zstdruby/libzstd/compress/zstd_lazy.c +333 -274
  26. data/ext/zstdruby/libzstd/compress/zstd_lazy.h +33 -16
  27. data/ext/zstdruby/libzstd/compress/zstd_ldm.c +305 -359
  28. data/ext/zstdruby/libzstd/compress/zstd_ldm.h +64 -21
  29. data/ext/zstdruby/libzstd/compress/zstd_opt.c +194 -56
  30. data/ext/zstdruby/libzstd/compress/zstd_opt.h +17 -5
  31. data/ext/zstdruby/libzstd/compress/zstdmt_compress.c +1131 -449
  32. data/ext/zstdruby/libzstd/compress/zstdmt_compress.h +32 -16
  33. data/ext/zstdruby/libzstd/decompress/huf_decompress.c +390 -290
  34. data/ext/zstdruby/libzstd/decompress/zstd_decompress.c +777 -439
  35. data/ext/zstdruby/libzstd/dictBuilder/cover.c +11 -8
  36. data/ext/zstdruby/libzstd/dictBuilder/zdict.c +83 -50
  37. data/ext/zstdruby/libzstd/dictBuilder/zdict.h +44 -43
  38. data/ext/zstdruby/libzstd/legacy/zstd_legacy.h +2 -0
  39. data/ext/zstdruby/libzstd/legacy/zstd_v04.c +42 -118
  40. data/ext/zstdruby/libzstd/legacy/zstd_v06.c +2 -2
  41. data/ext/zstdruby/libzstd/legacy/zstd_v07.c +2 -2
  42. data/ext/zstdruby/libzstd/zstd.h +254 -254
  43. data/lib/zstd-ruby/version.rb +1 -1
  44. metadata +4 -3
@@ -16,37 +16,6 @@
16
16
 
17
17
  /* ******************************************************************
18
18
  mem.h
19
- low-level memory access routines
20
- Copyright (C) 2013-2015, Yann Collet.
21
-
22
- BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
23
-
24
- Redistribution and use in source and binary forms, with or without
25
- modification, are permitted provided that the following conditions are
26
- met:
27
-
28
- * Redistributions of source code must retain the above copyright
29
- notice, this list of conditions and the following disclaimer.
30
- * Redistributions in binary form must reproduce the above
31
- copyright notice, this list of conditions and the following disclaimer
32
- in the documentation and/or other materials provided with the
33
- distribution.
34
-
35
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
36
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
37
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
38
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
39
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
42
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
43
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
44
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
45
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
46
-
47
- You can contact the author at :
48
- - FSE source repository : https://github.com/Cyan4973/FiniteStateEntropy
49
- - Public forum : https://groups.google.com/forum/#!forum/lz4c
50
19
  ****************************************************************** */
51
20
  #ifndef MEM_H_MODULE
52
21
  #define MEM_H_MODULE
@@ -103,6 +72,44 @@ extern "C" {
103
72
  #endif
104
73
 
105
74
 
75
+ /*-*************************************
76
+ * Debug
77
+ ***************************************/
78
+ #if defined(ZSTD_DEBUG) && (ZSTD_DEBUG>=1)
79
+ # include <assert.h>
80
+ #else
81
+ # ifndef assert
82
+ # define assert(condition) ((void)0)
83
+ # endif
84
+ #endif
85
+
86
+ #define ZSTD_STATIC_ASSERT(c) { enum { ZSTD_static_assert = 1/(int)(!!(c)) }; }
87
+
88
+ #if defined(ZSTD_DEBUG) && (ZSTD_DEBUG>=2)
89
+ # include <stdio.h>
90
+ extern int g_debuglog_enable;
91
+ /* recommended values for ZSTD_DEBUG display levels :
92
+ * 1 : no display, enables assert() only
93
+ * 2 : reserved for currently active debug path
94
+ * 3 : events once per object lifetime (CCtx, CDict, etc.)
95
+ * 4 : events once per frame
96
+ * 5 : events once per block
97
+ * 6 : events once per sequence (*very* verbose) */
98
+ # define RAWLOG(l, ...) { \
99
+ if ((g_debuglog_enable) & (l<=ZSTD_DEBUG)) { \
100
+ fprintf(stderr, __VA_ARGS__); \
101
+ } }
102
+ # define DEBUGLOG(l, ...) { \
103
+ if ((g_debuglog_enable) & (l<=ZSTD_DEBUG)) { \
104
+ fprintf(stderr, __FILE__ ": " __VA_ARGS__); \
105
+ fprintf(stderr, " \n"); \
106
+ } }
107
+ #else
108
+ # define RAWLOG(l, ...) {} /* disabled */
109
+ # define DEBUGLOG(l, ...) {} /* disabled */
110
+ #endif
111
+
112
+
106
113
  /****************************************************************
107
114
  * Memory I/O
108
115
  *****************************************************************/
@@ -255,34 +262,6 @@ MEM_STATIC size_t MEM_readLEST(const void* memPtr)
255
262
  /*
256
263
  zstd - standard compression library
257
264
  Header File for static linking only
258
- Copyright (C) 2014-2015, Yann Collet.
259
-
260
- BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
261
-
262
- Redistribution and use in source and binary forms, with or without
263
- modification, are permitted provided that the following conditions are
264
- met:
265
- * Redistributions of source code must retain the above copyright
266
- notice, this list of conditions and the following disclaimer.
267
- * Redistributions in binary form must reproduce the above
268
- copyright notice, this list of conditions and the following disclaimer
269
- in the documentation and/or other materials provided with the
270
- distribution.
271
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
272
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
273
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
274
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
275
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
276
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
277
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
278
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
279
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
280
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
281
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
282
-
283
- You can contact the author at :
284
- - zstd source repository : https://github.com/Cyan4973/zstd
285
- - ztsd public forum : https://groups.google.com/forum/#!forum/lz4c
286
265
  */
287
266
  #ifndef ZSTD_STATIC_H
288
267
  #define ZSTD_STATIC_H
@@ -392,34 +371,6 @@ static size_t ZSTD_decompressContinue(ZSTD_DCtx* dctx, void* dst, size_t maxDstS
392
371
  /*
393
372
  zstd_internal - common functions to include
394
373
  Header File for include
395
- Copyright (C) 2014-2015, Yann Collet.
396
-
397
- BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
398
-
399
- Redistribution and use in source and binary forms, with or without
400
- modification, are permitted provided that the following conditions are
401
- met:
402
- * Redistributions of source code must retain the above copyright
403
- notice, this list of conditions and the following disclaimer.
404
- * Redistributions in binary form must reproduce the above
405
- copyright notice, this list of conditions and the following disclaimer
406
- in the documentation and/or other materials provided with the
407
- distribution.
408
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
409
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
410
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
411
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
412
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
413
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
414
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
415
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
416
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
417
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
418
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
419
-
420
- You can contact the author at :
421
- - zstd source repository : https://github.com/Cyan4973/zstd
422
- - ztsd public forum : https://groups.google.com/forum/#!forum/lz4c
423
374
  */
424
375
  #ifndef ZSTD_CCOMMON_H_MODULE
425
376
  #define ZSTD_CCOMMON_H_MODULE
@@ -507,36 +458,6 @@ static void ZSTD_wildcopy(void* dst, const void* src, ptrdiff_t length)
507
458
  /* ******************************************************************
508
459
  FSE : Finite State Entropy coder
509
460
  header file
510
- Copyright (C) 2013-2015, Yann Collet.
511
-
512
- BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
513
-
514
- Redistribution and use in source and binary forms, with or without
515
- modification, are permitted provided that the following conditions are
516
- met:
517
-
518
- * Redistributions of source code must retain the above copyright
519
- notice, this list of conditions and the following disclaimer.
520
- * Redistributions in binary form must reproduce the above
521
- copyright notice, this list of conditions and the following disclaimer
522
- in the documentation and/or other materials provided with the
523
- distribution.
524
-
525
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
526
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
527
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
528
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
529
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
530
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
531
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
532
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
533
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
534
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
535
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
536
-
537
- You can contact the author at :
538
- - Source repository : https://github.com/Cyan4973/FiniteStateEntropy
539
- - Public forum : https://groups.google.com/forum/#!forum/lz4c
540
461
  ****************************************************************** */
541
462
  #ifndef FSE_H
542
463
  #define FSE_H
@@ -3528,12 +3449,14 @@ static size_t ZBUFF_decompressContinue(ZBUFF_DCtx* zbc, void* dst, size_t* maxDs
3528
3449
  char* const oend = ostart + *maxDstSizePtr;
3529
3450
  U32 notDone = 1;
3530
3451
 
3452
+ DEBUGLOG(5, "ZBUFF_decompressContinue");
3531
3453
  while (notDone)
3532
3454
  {
3533
3455
  switch(zbc->stage)
3534
3456
  {
3535
3457
 
3536
3458
  case ZBUFFds_init :
3459
+ DEBUGLOG(5, "ZBUFF_decompressContinue: stage==ZBUFFds_init => ERROR(init_missing)");
3537
3460
  return ERROR(init_missing);
3538
3461
 
3539
3462
  case ZBUFFds_readHeader :
@@ -3733,7 +3656,7 @@ size_t ZSTDv04_decompressContinue(ZSTDv04_Dctx* dctx, void* dst, size_t maxDstSi
3733
3656
 
3734
3657
 
3735
3658
  ZBUFFv04_DCtx* ZBUFFv04_createDCtx(void) { return ZBUFF_createDCtx(); }
3736
- size_t ZBUFFv04_freeDCtx(ZBUFFv04_DCtx* dctx) { return ZBUFF_freeDCtx(dctx); }
3659
+ size_t ZBUFFv04_freeDCtx(ZBUFFv04_DCtx* dctx) { return ZBUFF_freeDCtx(dctx); }
3737
3660
 
3738
3661
  size_t ZBUFFv04_decompressInit(ZBUFFv04_DCtx* dctx) { return ZBUFF_decompressInit(dctx); }
3739
3662
  size_t ZBUFFv04_decompressWithDictionary(ZBUFFv04_DCtx* dctx, const void* src, size_t srcSize)
@@ -3741,6 +3664,7 @@ size_t ZBUFFv04_decompressWithDictionary(ZBUFFv04_DCtx* dctx, const void* src, s
3741
3664
 
3742
3665
  size_t ZBUFFv04_decompressContinue(ZBUFFv04_DCtx* dctx, void* dst, size_t* maxDstSizePtr, const void* src, size_t* srcSizePtr)
3743
3666
  {
3667
+ DEBUGLOG(5, "ZBUFFv04_decompressContinue");
3744
3668
  return ZBUFF_decompressContinue(dctx, dst, maxDstSizePtr, src, srcSizePtr);
3745
3669
  }
3746
3670
 
@@ -189,7 +189,7 @@ MEM_STATIC U32 MEM_swap32(U32 in)
189
189
  {
190
190
  #if defined(_MSC_VER) /* Visual Studio */
191
191
  return _byteswap_ulong(in);
192
- #elif defined (__GNUC__)
192
+ #elif defined (__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ >= 403)
193
193
  return __builtin_bswap32(in);
194
194
  #else
195
195
  return ((in << 24) & 0xff000000 ) |
@@ -203,7 +203,7 @@ MEM_STATIC U64 MEM_swap64(U64 in)
203
203
  {
204
204
  #if defined(_MSC_VER) /* Visual Studio */
205
205
  return _byteswap_uint64(in);
206
- #elif defined (__GNUC__)
206
+ #elif defined (__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ >= 403)
207
207
  return __builtin_bswap64(in);
208
208
  #else
209
209
  return ((in << 56) & 0xff00000000000000ULL) |
@@ -348,7 +348,7 @@ MEM_STATIC U32 MEM_swap32(U32 in)
348
348
  {
349
349
  #if defined(_MSC_VER) /* Visual Studio */
350
350
  return _byteswap_ulong(in);
351
- #elif defined (__GNUC__)
351
+ #elif defined (__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ >= 403)
352
352
  return __builtin_bswap32(in);
353
353
  #else
354
354
  return ((in << 24) & 0xff000000 ) |
@@ -362,7 +362,7 @@ MEM_STATIC U64 MEM_swap64(U64 in)
362
362
  {
363
363
  #if defined(_MSC_VER) /* Visual Studio */
364
364
  return _byteswap_uint64(in);
365
- #elif defined (__GNUC__)
365
+ #elif defined (__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ >= 403)
366
366
  return __builtin_bswap64(in);
367
367
  #else
368
368
  return ((in << 56) & 0xff00000000000000ULL) |
@@ -45,11 +45,11 @@ extern "C" {
45
45
  Levels >= 20, labeled `--ultra`, should be used with caution, as they require more memory.
46
46
  Compression can be done in:
47
47
  - a single step (described as Simple API)
48
- - a single step, reusing a context (described as Explicit memory management)
48
+ - a single step, reusing a context (described as Explicit context)
49
49
  - unbounded multiple steps (described as Streaming compression)
50
50
  The compression ratio achievable on small data can be highly improved using a dictionary in:
51
51
  - a single step (described as Simple dictionary API)
52
- - a single step, reusing a dictionary (described as Fast dictionary API)
52
+ - a single step, reusing a dictionary (described as Bulk-processing dictionary API)
53
53
 
54
54
  Advanced experimental functions can be accessed using #define ZSTD_STATIC_LINKING_ONLY before including zstd.h.
55
55
  Advanced experimental APIs shall never be used with a dynamic library.
@@ -59,7 +59,7 @@ extern "C" {
59
59
  /*------ Version ------*/
60
60
  #define ZSTD_VERSION_MAJOR 1
61
61
  #define ZSTD_VERSION_MINOR 3
62
- #define ZSTD_VERSION_RELEASE 3
62
+ #define ZSTD_VERSION_RELEASE 4
63
63
 
64
64
  #define ZSTD_VERSION_NUMBER (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE)
65
65
  ZSTDLIB_API unsigned ZSTD_versionNumber(void); /**< useful to check dll version */
@@ -68,7 +68,7 @@ ZSTDLIB_API unsigned ZSTD_versionNumber(void); /**< useful to check dll versio
68
68
  #define ZSTD_QUOTE(str) #str
69
69
  #define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str)
70
70
  #define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)
71
- ZSTDLIB_API const char* ZSTD_versionString(void); /* v1.3.0 */
71
+ ZSTDLIB_API const char* ZSTD_versionString(void); /* added in v1.3.0 */
72
72
 
73
73
 
74
74
  /***************************************
@@ -92,7 +92,7 @@ ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity,
92
92
  ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,
93
93
  const void* src, size_t compressedSize);
94
94
 
95
- /*! ZSTD_getFrameContentSize() : v1.3.0
95
+ /*! ZSTD_getFrameContentSize() : added in v1.3.0
96
96
  * `src` should point to the start of a ZSTD encoded frame.
97
97
  * `srcSize` must be at least as large as the frame header.
98
98
  * hint : any size >= `ZSTD_frameHeaderSize_max` is large enough.
@@ -120,26 +120,24 @@ ZSTDLIB_API unsigned long long ZSTD_getFrameContentSize(const void *src, size_t
120
120
 
121
121
  /*! ZSTD_getDecompressedSize() :
122
122
  * NOTE: This function is now obsolete, in favor of ZSTD_getFrameContentSize().
123
- * Both functions work the same way,
124
- * but ZSTD_getDecompressedSize() blends
125
- * "empty", "unknown" and "error" results in the same return value (0),
126
- * while ZSTD_getFrameContentSize() distinguishes them.
127
- *
128
- * 'src' is the start of a zstd compressed frame.
129
- * @return : content size to be decompressed, as a 64-bits value _if known and not empty_, 0 otherwise. */
123
+ * Both functions work the same way, but ZSTD_getDecompressedSize() blends
124
+ * "empty", "unknown" and "error" results to the same return value (0),
125
+ * while ZSTD_getFrameContentSize() gives them separate return values.
126
+ * `src` is the start of a zstd compressed frame.
127
+ * @return : content size to be decompressed, as a 64-bits value _if known and not empty_, 0 otherwise. */
130
128
  ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);
131
129
 
132
130
 
133
131
  /*====== Helper functions ======*/
134
132
  #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 */
135
- ZSTDLIB_API size_t ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case scenario */
133
+ ZSTDLIB_API size_t ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */
136
134
  ZSTDLIB_API unsigned ZSTD_isError(size_t code); /*!< tells if a `size_t` function result is an error code */
137
135
  ZSTDLIB_API const char* ZSTD_getErrorName(size_t code); /*!< provides readable string from an error code */
138
136
  ZSTDLIB_API int ZSTD_maxCLevel(void); /*!< maximum compression level available */
139
137
 
140
138
 
141
139
  /***************************************
142
- * Explicit memory management
140
+ * Explicit context
143
141
  ***************************************/
144
142
  /*= Compression context
145
143
  * When compressing many times,
@@ -345,7 +343,7 @@ ZSTDLIB_API size_t ZSTD_CStreamOutSize(void); /**< recommended size for output
345
343
  * *******************************************************************************/
346
344
 
347
345
  typedef ZSTD_DCtx ZSTD_DStream; /**< DCtx and DStream are now effectively same object (>= v1.3.0) */
348
- /* Continue to distinguish them for compatibility with versions <= v1.2.0 */
346
+ /* For compatibility with versions <= v1.2.0, continue to consider them separated. */
349
347
  /*===== ZSTD_DStream management functions =====*/
350
348
  ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream(void);
351
349
  ZSTDLIB_API size_t ZSTD_freeDStream(ZSTD_DStream* zds);
@@ -375,23 +373,24 @@ ZSTDLIB_API size_t ZSTD_DStreamOutSize(void); /*!< recommended size for output
375
373
  /* --- Constants ---*/
376
374
  #define ZSTD_MAGICNUMBER 0xFD2FB528 /* >= v0.8.0 */
377
375
  #define ZSTD_MAGIC_SKIPPABLE_START 0x184D2A50U
378
- #define ZSTD_MAGIC_DICTIONARY 0xEC30A437 /* v0.7+ */
376
+ #define ZSTD_MAGIC_DICTIONARY 0xEC30A437 /* >= v0.7.0 */
379
377
 
380
378
  #define ZSTD_WINDOWLOG_MAX_32 30
381
379
  #define ZSTD_WINDOWLOG_MAX_64 31
382
380
  #define ZSTD_WINDOWLOG_MAX ((unsigned)(sizeof(size_t) == 4 ? ZSTD_WINDOWLOG_MAX_32 : ZSTD_WINDOWLOG_MAX_64))
383
381
  #define ZSTD_WINDOWLOG_MIN 10
384
- #define ZSTD_HASHLOG_MAX MIN(ZSTD_WINDOWLOG_MAX, 30)
382
+ #define ZSTD_HASHLOG_MAX ((ZSTD_WINDOWLOG_MAX < 30) ? ZSTD_WINDOWLOG_MAX : 30)
385
383
  #define ZSTD_HASHLOG_MIN 6
386
- #define ZSTD_CHAINLOG_MAX MIN(ZSTD_WINDOWLOG_MAX+1, 30)
384
+ #define ZSTD_CHAINLOG_MAX_32 29
385
+ #define ZSTD_CHAINLOG_MAX_64 30
386
+ #define ZSTD_CHAINLOG_MAX ((unsigned)(sizeof(size_t) == 4 ? ZSTD_CHAINLOG_MAX_32 : ZSTD_CHAINLOG_MAX_64))
387
387
  #define ZSTD_CHAINLOG_MIN ZSTD_HASHLOG_MIN
388
388
  #define ZSTD_HASHLOG3_MAX 17
389
389
  #define ZSTD_SEARCHLOG_MAX (ZSTD_WINDOWLOG_MAX-1)
390
390
  #define ZSTD_SEARCHLOG_MIN 1
391
391
  #define ZSTD_SEARCHLENGTH_MAX 7 /* only for ZSTD_fast, other strategies are limited to 6 */
392
392
  #define ZSTD_SEARCHLENGTH_MIN 3 /* only for ZSTD_btopt, other strategies are limited to 4 */
393
- #define ZSTD_TARGETLENGTH_MIN 4 /* only useful for btopt */
394
- #define ZSTD_TARGETLENGTH_MAX 999 /* only useful for btopt */
393
+ #define ZSTD_TARGETLENGTH_MIN 1 /* only used by btopt, btultra and btfast */
395
394
  #define ZSTD_LDM_MINMATCH_MIN 4
396
395
  #define ZSTD_LDM_MINMATCH_MAX 4096
397
396
  #define ZSTD_LDM_BUCKETSIZELOG_MAX 8
@@ -432,12 +431,17 @@ typedef struct {
432
431
 
433
432
  typedef struct ZSTD_CCtx_params_s ZSTD_CCtx_params;
434
433
 
435
- /*--- Custom memory allocation functions ---*/
436
- typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size);
437
- typedef void (*ZSTD_freeFunction) (void* opaque, void* address);
438
- typedef struct { ZSTD_allocFunction customAlloc; ZSTD_freeFunction customFree; void* opaque; } ZSTD_customMem;
439
- /* use this constant to defer to stdlib's functions */
440
- static ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL };
434
+ typedef enum {
435
+ ZSTD_dct_auto=0, /* dictionary is "full" when starting with ZSTD_MAGIC_DICTIONARY, otherwise it is "rawContent" */
436
+ ZSTD_dct_rawContent, /* ensures dictionary is always loaded as rawContent, even if it starts with ZSTD_MAGIC_DICTIONARY */
437
+ ZSTD_dct_fullDict /* refuses to load a dictionary if it does not respect Zstandard's specification */
438
+ } ZSTD_dictContentType_e;
439
+
440
+ typedef enum {
441
+ ZSTD_dlm_byCopy = 0, /**< Copy dictionary content internally */
442
+ ZSTD_dlm_byRef, /**< Reference dictionary content -- the dictionary buffer must outlive its users. */
443
+ } ZSTD_dictLoadMethod_e;
444
+
441
445
 
442
446
 
443
447
  /***************************************
@@ -483,12 +487,12 @@ ZSTDLIB_API size_t ZSTD_frameHeaderSize(const void* src, size_t srcSize);
483
487
 
484
488
 
485
489
  /***************************************
486
- * Context memory usage
490
+ * Memory management
487
491
  ***************************************/
488
492
 
489
493
  /*! ZSTD_sizeof_*() :
490
494
  * These functions give the current memory usage of selected object.
491
- * Object memory usage can evolve when re-used multiple times. */
495
+ * Object memory usage can evolve when re-used. */
492
496
  ZSTDLIB_API size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx);
493
497
  ZSTDLIB_API size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx* dctx);
494
498
  ZSTDLIB_API size_t ZSTD_sizeof_CStream(const ZSTD_CStream* zcs);
@@ -503,8 +507,8 @@ ZSTDLIB_API size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
503
507
  * It will also consider src size to be arbitrarily "large", which is worst case.
504
508
  * If srcSize is known to always be small, ZSTD_estimateCCtxSize_usingCParams() can provide a tighter estimation.
505
509
  * ZSTD_estimateCCtxSize_usingCParams() can be used in tandem with ZSTD_getCParams() to create cParams from compressionLevel.
506
- * ZSTD_estimateCCtxSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParam_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_p_nbThreads is > 1.
507
- * Note : CCtx estimation is only correct for single-threaded compression */
510
+ * ZSTD_estimateCCtxSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParam_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_p_nbWorkers is >= 1.
511
+ * Note : CCtx size estimation is only correct for single-threaded compression. */
508
512
  ZSTDLIB_API size_t ZSTD_estimateCCtxSize(int compressionLevel);
509
513
  ZSTDLIB_API size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams);
510
514
  ZSTDLIB_API size_t ZSTD_estimateCCtxSize_usingCCtxParams(const ZSTD_CCtx_params* params);
@@ -515,8 +519,8 @@ ZSTDLIB_API size_t ZSTD_estimateDCtxSize(void);
515
519
  * It will also consider src size to be arbitrarily "large", which is worst case.
516
520
  * If srcSize is known to always be small, ZSTD_estimateCStreamSize_usingCParams() can provide a tighter estimation.
517
521
  * ZSTD_estimateCStreamSize_usingCParams() can be used in tandem with ZSTD_getCParams() to create cParams from compressionLevel.
518
- * ZSTD_estimateCStreamSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParam_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_p_nbThreads is set to a value > 1.
519
- * Note : CStream estimation is only correct for single-threaded compression.
522
+ * ZSTD_estimateCStreamSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParam_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_p_nbWorkers is >= 1.
523
+ * Note : CStream size estimation is only correct for single-threaded compression.
520
524
  * ZSTD_DStream memory budget depends on window Size.
521
525
  * This information can be passed manually, using ZSTD_estimateDStreamSize,
522
526
  * or deducted from a valid frame Header, using ZSTD_estimateDStreamSize_fromFrame();
@@ -529,84 +533,92 @@ ZSTDLIB_API size_t ZSTD_estimateCStreamSize_usingCCtxParams(const ZSTD_CCtx_para
529
533
  ZSTDLIB_API size_t ZSTD_estimateDStreamSize(size_t windowSize);
530
534
  ZSTDLIB_API size_t ZSTD_estimateDStreamSize_fromFrame(const void* src, size_t srcSize);
531
535
 
532
- typedef enum {
533
- ZSTD_dlm_byCopy = 0, /**< Copy dictionary content internally */
534
- ZSTD_dlm_byRef, /**< Reference dictionary content -- the dictionary buffer must outlive its users. */
535
- } ZSTD_dictLoadMethod_e;
536
-
537
536
  /*! ZSTD_estimate?DictSize() :
538
537
  * ZSTD_estimateCDictSize() will bet that src size is relatively "small", and content is copied, like ZSTD_createCDict().
539
- * ZSTD_estimateCStreamSize_advanced_usingCParams() makes it possible to control precisely compression parameters, like ZSTD_createCDict_advanced().
540
- * Note : dictionary created by reference using ZSTD_dlm_byRef are smaller
538
+ * ZSTD_estimateCDictSize_advanced() makes it possible to control compression parameters precisely, like ZSTD_createCDict_advanced().
539
+ * Note : dictionaries created by reference (`ZSTD_dlm_byRef`) are logically smaller.
541
540
  */
542
541
  ZSTDLIB_API size_t ZSTD_estimateCDictSize(size_t dictSize, int compressionLevel);
543
542
  ZSTDLIB_API size_t ZSTD_estimateCDictSize_advanced(size_t dictSize, ZSTD_compressionParameters cParams, ZSTD_dictLoadMethod_e dictLoadMethod);
544
543
  ZSTDLIB_API size_t ZSTD_estimateDDictSize(size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod);
545
544
 
546
-
547
- /***************************************
548
- * Advanced compression functions
549
- ***************************************/
550
- /*! ZSTD_createCCtx_advanced() :
551
- * Create a ZSTD compression context using external alloc and free functions */
552
- ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx_advanced(ZSTD_customMem customMem);
553
-
554
- /*! ZSTD_initStaticCCtx() : initialize a fixed-size zstd compression context
555
- * workspace: The memory area to emplace the context into.
556
- * Provided pointer must 8-bytes aligned.
557
- * It must outlive context usage.
558
- * workspaceSize: Use ZSTD_estimateCCtxSize() or ZSTD_estimateCStreamSize()
559
- * to determine how large workspace must be to support scenario.
560
- * @return : pointer to ZSTD_CCtx* (same address as workspace, but different type),
561
- * or NULL if error (typically size too small)
562
- * Note : zstd will never resize nor malloc() when using a static cctx.
563
- * If it needs more memory than available, it will simply error out.
545
+ /*! ZSTD_initStatic*() :
546
+ * Initialize an object using a pre-allocated fixed-size buffer.
547
+ * workspace: The memory area to emplace the object into.
548
+ * Provided pointer *must be 8-bytes aligned*.
549
+ * Buffer must outlive object.
550
+ * workspaceSize: Use ZSTD_estimate*Size() to determine
551
+ * how large workspace must be to support target scenario.
552
+ * @return : pointer to object (same address as workspace, just different type),
553
+ * or NULL if error (size too small, incorrect alignment, etc.)
554
+ * Note : zstd will never resize nor malloc() when using a static buffer.
555
+ * If the object requires more memory than available,
556
+ * zstd will just error out (typically ZSTD_error_memory_allocation).
564
557
  * Note 2 : there is no corresponding "free" function.
565
- * Since workspace was allocated externally, it must be freed externally too.
566
- * Limitation 1 : currently not compatible with internal CDict creation, such as
567
- * ZSTD_CCtx_loadDictionary() or ZSTD_initCStream_usingDict().
568
- * Limitation 2 : currently not compatible with multi-threading
558
+ * Since workspace is allocated externally, it must be freed externally too.
559
+ * Note 3 : cParams : use ZSTD_getCParams() to convert a compression level
560
+ * into its associated cParams.
561
+ * Limitation 1 : currently not compatible with internal dictionary creation, triggered by
562
+ * ZSTD_CCtx_loadDictionary(), ZSTD_initCStream_usingDict() or ZSTD_initDStream_usingDict().
563
+ * Limitation 2 : static cctx currently not compatible with multi-threading.
564
+ * Limitation 3 : static dctx is incompatible with legacy support.
569
565
  */
570
- ZSTDLIB_API ZSTD_CCtx* ZSTD_initStaticCCtx(void* workspace, size_t workspaceSize);
566
+ ZSTDLIB_API ZSTD_CCtx* ZSTD_initStaticCCtx(void* workspace, size_t workspaceSize);
567
+ ZSTDLIB_API ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize); /**< same as ZSTD_initStaticCCtx() */
571
568
 
569
+ ZSTDLIB_API ZSTD_DCtx* ZSTD_initStaticDCtx(void* workspace, size_t workspaceSize);
570
+ ZSTDLIB_API ZSTD_DStream* ZSTD_initStaticDStream(void* workspace, size_t workspaceSize); /**< same as ZSTD_initStaticDCtx() */
572
571
 
573
- /*! ZSTD_createCDict_byReference() :
574
- * Create a digested dictionary for compression
575
- * Dictionary content is simply referenced, and therefore stays in dictBuffer.
576
- * It is important that dictBuffer outlives CDict, it must remain read accessible throughout the lifetime of CDict */
577
- ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel);
572
+ ZSTDLIB_API const ZSTD_CDict* ZSTD_initStaticCDict(
573
+ void* workspace, size_t workspaceSize,
574
+ const void* dict, size_t dictSize,
575
+ ZSTD_dictLoadMethod_e dictLoadMethod,
576
+ ZSTD_dictContentType_e dictContentType,
577
+ ZSTD_compressionParameters cParams);
578
+
579
+ ZSTDLIB_API const ZSTD_DDict* ZSTD_initStaticDDict(
580
+ void* workspace, size_t workspaceSize,
581
+ const void* dict, size_t dictSize,
582
+ ZSTD_dictLoadMethod_e dictLoadMethod,
583
+ ZSTD_dictContentType_e dictContentType);
584
+
585
+ /*! Custom memory allocation :
586
+ * These prototypes make it possible to pass your own allocation/free functions.
587
+ * ZSTD_customMem is provided at creation time, using ZSTD_create*_advanced() variants listed below.
588
+ * All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones.
589
+ */
590
+ typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size);
591
+ typedef void (*ZSTD_freeFunction) (void* opaque, void* address);
592
+ typedef struct { ZSTD_allocFunction customAlloc; ZSTD_freeFunction customFree; void* opaque; } ZSTD_customMem;
593
+ static ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL }; /**< this constant defers to stdlib's functions */
594
+
595
+ ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx_advanced(ZSTD_customMem customMem);
596
+ ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream_advanced(ZSTD_customMem customMem);
597
+ ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx_advanced(ZSTD_customMem customMem);
598
+ ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream_advanced(ZSTD_customMem customMem);
578
599
 
579
- typedef enum { ZSTD_dm_auto=0, /* dictionary is "full" if it starts with ZSTD_MAGIC_DICTIONARY, otherwise it is "rawContent" */
580
- ZSTD_dm_rawContent, /* ensures dictionary is always loaded as rawContent, even if it starts with ZSTD_MAGIC_DICTIONARY */
581
- ZSTD_dm_fullDict /* refuses to load a dictionary if it does not respect Zstandard's specification */
582
- } ZSTD_dictMode_e;
583
- /*! ZSTD_createCDict_advanced() :
584
- * Create a ZSTD_CDict using external alloc and free, and customized compression parameters */
585
600
  ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_advanced(const void* dict, size_t dictSize,
586
601
  ZSTD_dictLoadMethod_e dictLoadMethod,
587
- ZSTD_dictMode_e dictMode,
602
+ ZSTD_dictContentType_e dictContentType,
588
603
  ZSTD_compressionParameters cParams,
589
604
  ZSTD_customMem customMem);
590
605
 
591
- /*! ZSTD_initStaticCDict() :
592
- * Generate a digested dictionary in provided memory area.
593
- * workspace: The memory area to emplace the dictionary into.
594
- * Provided pointer must 8-bytes aligned.
595
- * It must outlive dictionary usage.
596
- * workspaceSize: Use ZSTD_estimateCDictSize()
597
- * to determine how large workspace must be.
598
- * cParams : use ZSTD_getCParams() to transform a compression level
599
- * into its relevants cParams.
600
- * @return : pointer to ZSTD_CDict* (same address as workspace, but different type),
601
- * or NULL if error (typically, size too small).
602
- * Note : there is no corresponding "free" function.
603
- * Since workspace was allocated externally, it must be freed externally.
604
- */
605
- ZSTDLIB_API ZSTD_CDict* ZSTD_initStaticCDict(
606
- void* workspace, size_t workspaceSize,
607
- const void* dict, size_t dictSize,
608
- ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictMode_e dictMode,
609
- ZSTD_compressionParameters cParams);
606
+ ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict_advanced(const void* dict, size_t dictSize,
607
+ ZSTD_dictLoadMethod_e dictLoadMethod,
608
+ ZSTD_dictContentType_e dictContentType,
609
+ ZSTD_customMem customMem);
610
+
611
+
612
+
613
+ /***************************************
614
+ * Advanced compression functions
615
+ ***************************************/
616
+
617
+ /*! ZSTD_createCDict_byReference() :
618
+ * Create a digested dictionary for compression
619
+ * Dictionary content is simply referenced, and therefore stays in dictBuffer.
620
+ * It is important that dictBuffer outlives CDict, it must remain read accessible throughout the lifetime of CDict */
621
+ ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel);
610
622
 
611
623
  /*! ZSTD_getCParams() :
612
624
  * @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize.
@@ -652,28 +664,6 @@ ZSTDLIB_API size_t ZSTD_compress_usingCDict_advanced(ZSTD_CCtx* cctx,
652
664
  * Note 3 : Skippable Frame Identifiers are considered valid. */
653
665
  ZSTDLIB_API unsigned ZSTD_isFrame(const void* buffer, size_t size);
654
666
 
655
- /*! ZSTD_createDCtx_advanced() :
656
- * Create a ZSTD decompression context using external alloc and free functions */
657
- ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx_advanced(ZSTD_customMem customMem);
658
-
659
- /*! ZSTD_initStaticDCtx() : initialize a fixed-size zstd decompression context
660
- * workspace: The memory area to emplace the context into.
661
- * Provided pointer must 8-bytes aligned.
662
- * It must outlive context usage.
663
- * workspaceSize: Use ZSTD_estimateDCtxSize() or ZSTD_estimateDStreamSize()
664
- * to determine how large workspace must be to support scenario.
665
- * @return : pointer to ZSTD_DCtx* (same address as workspace, but different type),
666
- * or NULL if error (typically size too small)
667
- * Note : zstd will never resize nor malloc() when using a static dctx.
668
- * If it needs more memory than available, it will simply error out.
669
- * Note 2 : static dctx is incompatible with legacy support
670
- * Note 3 : there is no corresponding "free" function.
671
- * Since workspace was allocated externally, it must be freed externally.
672
- * Limitation : currently not compatible with internal DDict creation,
673
- * such as ZSTD_initDStream_usingDict().
674
- */
675
- ZSTDLIB_API ZSTD_DCtx* ZSTD_initStaticDCtx(void* workspace, size_t workspaceSize);
676
-
677
667
  /*! ZSTD_createDDict_byReference() :
678
668
  * Create a digested dictionary, ready to start decompression operation without startup delay.
679
669
  * Dictionary content is referenced, and therefore stays in dictBuffer.
@@ -681,26 +671,6 @@ ZSTDLIB_API ZSTD_DCtx* ZSTD_initStaticDCtx(void* workspace, size_t workspaceSize
681
671
  * it must remain read accessible throughout the lifetime of DDict */
682
672
  ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict_byReference(const void* dictBuffer, size_t dictSize);
683
673
 
684
- /*! ZSTD_createDDict_advanced() :
685
- * Create a ZSTD_DDict using external alloc and free, optionally by reference */
686
- ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict_advanced(const void* dict, size_t dictSize,
687
- ZSTD_dictLoadMethod_e dictLoadMethod,
688
- ZSTD_customMem customMem);
689
-
690
- /*! ZSTD_initStaticDDict() :
691
- * Generate a digested dictionary in provided memory area.
692
- * workspace: The memory area to emplace the dictionary into.
693
- * Provided pointer must 8-bytes aligned.
694
- * It must outlive dictionary usage.
695
- * workspaceSize: Use ZSTD_estimateDDictSize()
696
- * to determine how large workspace must be.
697
- * @return : pointer to ZSTD_DDict*, or NULL if error (size too small)
698
- * Note : there is no corresponding "free" function.
699
- * Since workspace was allocated externally, it must be freed externally.
700
- */
701
- ZSTDLIB_API ZSTD_DDict* ZSTD_initStaticDDict(void* workspace, size_t workspaceSize,
702
- const void* dict, size_t dictSize,
703
- ZSTD_dictLoadMethod_e dictLoadMethod);
704
674
 
705
675
  /*! ZSTD_getDictID_fromDict() :
706
676
  * Provides the dictID stored within dictionary.
@@ -732,8 +702,6 @@ ZSTDLIB_API unsigned ZSTD_getDictID_fromFrame(const void* src, size_t srcSize);
732
702
  ********************************************************************/
733
703
 
734
704
  /*===== Advanced Streaming compression functions =====*/
735
- ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream_advanced(ZSTD_customMem customMem);
736
- ZSTDLIB_API ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize); /**< same as ZSTD_initStaticCCtx() */
737
705
  ZSTDLIB_API size_t ZSTD_initCStream_srcSize(ZSTD_CStream* zcs, int compressionLevel, unsigned long long pledgedSrcSize); /**< pledgedSrcSize must be correct. If it is not known at init time, use ZSTD_CONTENTSIZE_UNKNOWN. Note that, for compatibility with older programs, "0" also disables frame content size field. It may be enabled in the future. */
738
706
  ZSTDLIB_API size_t ZSTD_initCStream_usingDict(ZSTD_CStream* zcs, const void* dict, size_t dictSize, int compressionLevel); /**< creates of an internal CDict (incompatible with static CCtx), except if dict == NULL or dictSize < 8, in which case no dict is used. Note: dict is loaded with ZSTD_dm_auto (treated as a full zstd dictionary if it begins with ZSTD_MAGIC_DICTIONARY, else as raw content) and ZSTD_dlm_byCopy.*/
739
707
  ZSTDLIB_API size_t ZSTD_initCStream_advanced(ZSTD_CStream* zcs, const void* dict, size_t dictSize,
@@ -748,14 +716,28 @@ ZSTDLIB_API size_t ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, const
748
716
  * If pledgedSrcSize is not known at reset time, use macro ZSTD_CONTENTSIZE_UNKNOWN.
749
717
  * If pledgedSrcSize > 0, its value must be correct, as it will be written in header, and controlled at the end.
750
718
  * For the time being, pledgedSrcSize==0 is interpreted as "srcSize unknown" for compatibility with older programs,
751
- * but it may change to mean "empty" in some future version, so prefer using macro ZSTD_CONTENTSIZE_UNKNOWN.
719
+ * but it will change to mean "empty" in future version, so use macro ZSTD_CONTENTSIZE_UNKNOWN instead.
752
720
  * @return : 0, or an error code (which can be tested using ZSTD_isError()) */
753
721
  ZSTDLIB_API size_t ZSTD_resetCStream(ZSTD_CStream* zcs, unsigned long long pledgedSrcSize);
754
722
 
755
723
 
724
+ typedef struct {
725
+ unsigned long long ingested;
726
+ unsigned long long consumed;
727
+ unsigned long long produced;
728
+ } ZSTD_frameProgression;
729
+
730
+ /* ZSTD_getFrameProgression():
731
+ * tells how much data has been ingested (read from input)
732
+ * consumed (input actually compressed) and produced (output) for current frame.
733
+ * Therefore, (ingested - consumed) is amount of input data buffered internally, not yet compressed.
734
+ * Can report progression inside worker threads (multi-threading and non-blocking mode).
735
+ */
736
+ ZSTD_frameProgression ZSTD_getFrameProgression(const ZSTD_CCtx* cctx);
737
+
738
+
739
+
756
740
  /*===== Advanced Streaming decompression functions =====*/
757
- ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream_advanced(ZSTD_customMem customMem);
758
- ZSTDLIB_API ZSTD_DStream* ZSTD_initStaticDStream(void* workspace, size_t workspaceSize); /**< same as ZSTD_initStaticDCtx() */
759
741
  typedef enum { DStream_p_maxWindowSize } ZSTD_DStreamParameter_e;
760
742
  ZSTDLIB_API size_t ZSTD_setDStreamParameter(ZSTD_DStream* zds, ZSTD_DStreamParameter_e paramType, unsigned paramValue); /* obsolete : this API will be removed in a future version */
761
743
  ZSTDLIB_API size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize); /**< note: no dictionary will be used if dict == NULL or dictSize < 8 */
@@ -924,10 +906,8 @@ ZSTDLIB_API ZSTD_nextInputType_e ZSTD_nextInputType(ZSTD_DCtx* dctx);
924
906
  * and then applied on all subsequent compression jobs.
925
907
  * When no parameter is ever provided, CCtx is created with compression level ZSTD_CLEVEL_DEFAULT.
926
908
  *
927
- * This API is intended to replace all others experimental API.
928
- * It can basically do all other use cases, and even new ones.
929
- * In constrast with _advanced() variants, it stands a reasonable chance to become "stable",
930
- * after a good testing period.
909
+ * This API is intended to replace all others advanced / experimental API entry points.
910
+ * But it stands a reasonable chance to become "stable", after a reasonable testing period.
931
911
  */
932
912
 
933
913
  /* note on naming convention :
@@ -944,12 +924,12 @@ ZSTDLIB_API ZSTD_nextInputType_e ZSTD_nextInputType(ZSTD_DCtx* dctx);
944
924
  * All enum will be pinned to explicit values before reaching "stable API" status */
945
925
 
946
926
  typedef enum {
947
- /* Question : should we have a format ZSTD_f_auto ?
948
- * For the time being, it would mean exactly the same as ZSTD_f_zstd1.
949
- * But, in the future, should several formats be supported,
927
+ /* Opened question : should we have a format ZSTD_f_auto ?
928
+ * Today, it would mean exactly the same as ZSTD_f_zstd1.
929
+ * But, in the future, should several formats become supported,
950
930
  * on the compression side, it would mean "default format".
951
- * On the decompression side, it would mean "multi format",
952
- * and ZSTD_f_zstd1 could be reserved to mean "accept *only* zstd frames".
931
+ * On the decompression side, it would mean "automatic format detection",
932
+ * so that ZSTD_f_zstd1 would mean "accept *only* zstd frames".
953
933
  * Since meaning is a little different, another option could be to define different enums for compression and decompression.
954
934
  * This question could be kept for later, when there are actually multiple formats to support,
955
935
  * but there is also the question of pinning enum values, and pinning value `0` is especially important */
@@ -967,42 +947,76 @@ typedef enum {
967
947
  /* compression parameters */
968
948
  ZSTD_p_compressionLevel=100, /* Update all compression parameters according to pre-defined cLevel table
969
949
  * Default level is ZSTD_CLEVEL_DEFAULT==3.
970
- * Special: value 0 means "do not change cLevel". */
950
+ * Special: value 0 means "do not change cLevel".
951
+ * Note 1 : it's possible to pass a negative compression level by casting it to unsigned type.
952
+ * Note 2 : setting a level sets all default values of other compression parameters.
953
+ * Note 3 : setting compressionLevel automatically updates ZSTD_p_compressLiterals. */
971
954
  ZSTD_p_windowLog, /* Maximum allowed back-reference distance, expressed as power of 2.
972
955
  * Must be clamped between ZSTD_WINDOWLOG_MIN and ZSTD_WINDOWLOG_MAX.
973
- * Special: value 0 means "do not change windowLog".
956
+ * Special: value 0 means "use default windowLog".
974
957
  * Note: Using a window size greater than ZSTD_MAXWINDOWSIZE_DEFAULT (default: 2^27)
975
- * requires setting the maximum window size at least as large during decompression. */
958
+ * requires explicitly allowing such window size during decompression stage. */
976
959
  ZSTD_p_hashLog, /* Size of the probe table, as a power of 2.
977
960
  * Resulting table size is (1 << (hashLog+2)).
978
961
  * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX.
979
962
  * Larger tables improve compression ratio of strategies <= dFast,
980
963
  * and improve speed of strategies > dFast.
981
- * Special: value 0 means "do not change hashLog". */
964
+ * Special: value 0 means "use default hashLog". */
982
965
  ZSTD_p_chainLog, /* Size of the full-search table, as a power of 2.
983
966
  * Resulting table size is (1 << (chainLog+2)).
984
967
  * Larger tables result in better and slower compression.
985
968
  * This parameter is useless when using "fast" strategy.
986
- * Special: value 0 means "do not change chainLog". */
969
+ * Special: value 0 means "use default chainLog". */
987
970
  ZSTD_p_searchLog, /* Number of search attempts, as a power of 2.
988
971
  * More attempts result in better and slower compression.
989
972
  * This parameter is useless when using "fast" and "dFast" strategies.
990
- * Special: value 0 means "do not change searchLog". */
973
+ * Special: value 0 means "use default searchLog". */
991
974
  ZSTD_p_minMatch, /* Minimum size of searched matches (note : repCode matches can be smaller).
992
975
  * Larger values make faster compression and decompression, but decrease ratio.
993
976
  * Must be clamped between ZSTD_SEARCHLENGTH_MIN and ZSTD_SEARCHLENGTH_MAX.
994
977
  * Note that currently, for all strategies < btopt, effective minimum is 4.
995
- * Note that currently, for all strategies > fast, effective maximum is 6.
996
- * Special: value 0 means "do not change minMatchLength". */
997
- ZSTD_p_targetLength, /* Only useful for strategies >= btopt.
998
- * Length of Match considered "good enough" to stop search.
999
- * Larger values make compression stronger and slower.
1000
- * Special: value 0 means "do not change targetLength". */
978
+ * , for all strategies > fast, effective maximum is 6.
979
+ * Special: value 0 means "use default minMatchLength". */
980
+ ZSTD_p_targetLength, /* Impact of this field depends on strategy.
981
+ * For strategies btopt & btultra:
982
+ * Length of Match considered "good enough" to stop search.
983
+ * Larger values make compression stronger, and slower.
984
+ * For strategy fast:
985
+ * Distance between match sampling.
986
+ * Larger values make compression faster, and weaker.
987
+ * Special: value 0 means "use default targetLength". */
1001
988
  ZSTD_p_compressionStrategy, /* See ZSTD_strategy enum definition.
1002
989
  * Cast selected strategy as unsigned for ZSTD_CCtx_setParameter() compatibility.
1003
990
  * The higher the value of selected strategy, the more complex it is,
1004
991
  * resulting in stronger and slower compression.
1005
- * Special: value 0 means "do not change strategy". */
992
+ * Special: value 0 means "use default strategy". */
993
+
994
+ ZSTD_p_enableLongDistanceMatching=160, /* Enable long distance matching.
995
+ * This parameter is designed to improve compression ratio
996
+ * for large inputs, by finding large matches at long distance.
997
+ * It increases memory usage and window size.
998
+ * Note: enabling this parameter increases ZSTD_p_windowLog to 128 MB
999
+ * except when expressly set to a different value. */
1000
+ ZSTD_p_ldmHashLog, /* Size of the table for long distance matching, as a power of 2.
1001
+ * Larger values increase memory usage and compression ratio,
1002
+ * but decrease compression speed.
1003
+ * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX
1004
+ * default: windowlog - 7.
1005
+ * Special: value 0 means "automatically determine hashlog". */
1006
+ ZSTD_p_ldmMinMatch, /* Minimum match size for long distance matcher.
1007
+ * Larger/too small values usually decrease compression ratio.
1008
+ * Must be clamped between ZSTD_LDM_MINMATCH_MIN and ZSTD_LDM_MINMATCH_MAX.
1009
+ * Special: value 0 means "use default value" (default: 64). */
1010
+ ZSTD_p_ldmBucketSizeLog, /* Log size of each bucket in the LDM hash table for collision resolution.
1011
+ * Larger values improve collision resolution but decrease compression speed.
1012
+ * The maximum value is ZSTD_LDM_BUCKETSIZELOG_MAX .
1013
+ * Special: value 0 means "use default value" (default: 3). */
1014
+ ZSTD_p_ldmHashEveryLog, /* Frequency of inserting/looking up entries in the LDM hash table.
1015
+ * Must be clamped between 0 and (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN).
1016
+ * Default is MAX(0, (windowLog - ldmHashLog)), optimizing hash table usage.
1017
+ * Larger values improve compression speed.
1018
+ * Deviating far from default value will likely result in a compression ratio decrease.
1019
+ * Special: value 0 means "automatically determine hashEveryLog". */
1006
1020
 
1007
1021
  /* frame parameters */
1008
1022
  ZSTD_p_contentSizeFlag=200, /* Content size will be written into frame header _whenever known_ (default:1)
@@ -1012,58 +1026,45 @@ typedef enum {
1012
1026
  ZSTD_p_dictIDFlag, /* When applicable, dictionary's ID is written into frame header (default:1) */
1013
1027
 
1014
1028
  /* multi-threading parameters */
1015
- ZSTD_p_nbThreads=400, /* Select how many threads a compression job can spawn (default:1)
1016
- * More threads improve speed, but also increase memory usage.
1017
- * Can only receive a value > 1 if ZSTD_MULTITHREAD is enabled.
1018
- * Special: value 0 means "do not change nbThreads" */
1019
- ZSTD_p_jobSize, /* Size of a compression job. This value is only enforced in streaming (non-blocking) mode.
1020
- * Each compression job is completed in parallel, so indirectly controls the nb of active threads.
1029
+ /* These parameters are only useful if multi-threading is enabled (ZSTD_MULTITHREAD).
1030
+ * They return an error otherwise. */
1031
+ ZSTD_p_nbWorkers=400, /* Select how many threads will be spawned to compress in parallel.
1032
+ * When nbWorkers >= 1, triggers asynchronous mode :
1033
+ * ZSTD_compress_generic() consumes some input, flush some output if possible, and immediately gives back control to caller,
1034
+ * while compression work is performed in parallel, within worker threads.
1035
+ * (note : a strong exception to this rule is when first invocation sets ZSTD_e_end : it becomes a blocking call).
1036
+ * More workers improve speed, but also increase memory usage.
1037
+ * Default value is `0`, aka "single-threaded mode" : no worker is spawned, compression is performed inside Caller's thread, all invocations are blocking */
1038
+ ZSTD_p_jobSize, /* Size of a compression job. This value is enforced only in non-blocking mode.
1039
+ * Each compression job is completed in parallel, so this value indirectly controls the nb of active threads.
1021
1040
  * 0 means default, which is dynamically determined based on compression parameters.
1022
- * Job size must be a minimum of overlapSize, or 1 KB, whichever is largest
1041
+ * Job size must be a minimum of overlapSize, or 1 MB, whichever is largest.
1023
1042
  * The minimum size is automatically and transparently enforced */
1024
1043
  ZSTD_p_overlapSizeLog, /* Size of previous input reloaded at the beginning of each job.
1025
1044
  * 0 => no overlap, 6(default) => use 1/8th of windowSize, >=9 => use full windowSize */
1026
1045
 
1027
- /* advanced parameters - may not remain available after API update */
1046
+ /* =================================================================== */
1047
+ /* experimental parameters - no stability guaranteed */
1048
+ /* =================================================================== */
1049
+
1050
+ ZSTD_p_compressLiterals=1000, /* control huffman compression of literals (enabled) by default.
1051
+ * disabling it improves speed and decreases compression ratio by a large amount.
1052
+ * note : this setting is automatically updated when changing compression level.
1053
+ * positive compression levels set ZSTD_p_compressLiterals to 1.
1054
+ * negative compression levels set ZSTD_p_compressLiterals to 0. */
1055
+
1028
1056
  ZSTD_p_forceMaxWindow=1100, /* Force back-reference distances to remain < windowSize,
1029
1057
  * even when referencing into Dictionary content (default:0) */
1030
- ZSTD_p_enableLongDistanceMatching=1200, /* Enable long distance matching.
1031
- * This parameter is designed to improve the compression
1032
- * ratio for large inputs with long distance matches.
1033
- * This increases the memory usage as well as window size.
1034
- * Note: setting this parameter sets all the LDM parameters
1035
- * as well as ZSTD_p_windowLog. It should be set after
1036
- * ZSTD_p_compressionLevel and before ZSTD_p_windowLog and
1037
- * other LDM parameters. Setting the compression level
1038
- * after this parameter overrides the window log, though LDM
1039
- * will remain enabled until explicitly disabled. */
1040
- ZSTD_p_ldmHashLog, /* Size of the table for long distance matching, as a power of 2.
1041
- * Larger values increase memory usage and compression ratio, but decrease
1042
- * compression speed.
1043
- * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX
1044
- * (default: windowlog - 7). */
1045
- ZSTD_p_ldmMinMatch, /* Minimum size of searched matches for long distance matcher.
1046
- * Larger/too small values usually decrease compression ratio.
1047
- * Must be clamped between ZSTD_LDM_MINMATCH_MIN
1048
- * and ZSTD_LDM_MINMATCH_MAX (default: 64). */
1049
- ZSTD_p_ldmBucketSizeLog, /* Log size of each bucket in the LDM hash table for collision resolution.
1050
- * Larger values usually improve collision resolution but may decrease
1051
- * compression speed.
1052
- * The maximum value is ZSTD_LDM_BUCKETSIZELOG_MAX (default: 3). */
1053
- ZSTD_p_ldmHashEveryLog, /* Frequency of inserting/looking up entries in the LDM hash table.
1054
- * The default is MAX(0, (windowLog - ldmHashLog)) to
1055
- * optimize hash table usage.
1056
- * Larger values improve compression speed. Deviating far from the
1057
- * default value will likely result in a decrease in compression ratio.
1058
- * Must be clamped between 0 and ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN. */
1059
1058
 
1060
1059
  } ZSTD_cParameter;
1061
1060
 
1062
1061
 
1063
1062
  /*! ZSTD_CCtx_setParameter() :
1064
1063
  * Set one compression parameter, selected by enum ZSTD_cParameter.
1064
+ * Setting a parameter is generally only possible during frame initialization (before starting compression),
1065
+ * except for a few exceptions which can be updated during compression: compressionLevel, hashLog, chainLog, searchLog, minMatch, targetLength and strategy.
1065
1066
  * Note : when `value` is an enum, cast it to unsigned for proper type checking.
1066
- * @result : informational value (typically, the one being set, possibly corrected),
1067
+ * @result : informational value (typically, value being set clamped correctly),
1067
1068
  * or an error code (which can be tested with ZSTD_isError()). */
1068
1069
  ZSTDLIB_API size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, unsigned value);
1069
1070
 
@@ -1079,26 +1080,24 @@ ZSTDLIB_API size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param
1079
1080
  ZSTDLIB_API size_t ZSTD_CCtx_setPledgedSrcSize(ZSTD_CCtx* cctx, unsigned long long pledgedSrcSize);
1080
1081
 
1081
1082
  /*! ZSTD_CCtx_loadDictionary() :
1082
- * Create an internal CDict from dict buffer.
1083
- * Decompression will have to use same buffer.
1083
+ * Create an internal CDict from `dict` buffer.
1084
+ * Decompression will have to use same dictionary.
1084
1085
  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
1085
- * Special : Adding a NULL (or 0-size) dictionary invalidates any previous dictionary,
1086
- * meaning "return to no-dictionary mode".
1087
- * Note 1 : `dict` content will be copied internally. Use
1088
- * ZSTD_CCtx_loadDictionary_byReference() to reference dictionary
1089
- * content instead. The dictionary buffer must then outlive its
1090
- * users.
1086
+ * Special: Adding a NULL (or 0-size) dictionary invalidates previous dictionary,
1087
+ * meaning "return to no-dictionary mode".
1088
+ * Note 1 : Dictionary will be used for all future compression jobs.
1089
+ * To return to "no-dictionary" situation, load a NULL dictionary
1091
1090
  * Note 2 : Loading a dictionary involves building tables, which are dependent on compression parameters.
1092
1091
  * For this reason, compression parameters cannot be changed anymore after loading a dictionary.
1093
- * It's also a CPU-heavy operation, with non-negligible impact on latency.
1094
- * Note 3 : Dictionary will be used for all future compression jobs.
1095
- * To return to "no-dictionary" situation, load a NULL dictionary
1096
- * Note 5 : Use ZSTD_CCtx_loadDictionary_advanced() to select how dictionary
1097
- * content will be interpreted.
1098
- */
1092
+ * It's also a CPU consuming operation, with non-negligible impact on latency.
1093
+ * Note 3 :`dict` content will be copied internally.
1094
+ * Use ZSTD_CCtx_loadDictionary_byReference() to reference dictionary content instead.
1095
+ * In such a case, dictionary buffer must outlive its users.
1096
+ * Note 4 : Use ZSTD_CCtx_loadDictionary_advanced()
1097
+ * to precisely select how dictionary content must be interpreted. */
1099
1098
  ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary(ZSTD_CCtx* cctx, const void* dict, size_t dictSize);
1100
1099
  ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary_byReference(ZSTD_CCtx* cctx, const void* dict, size_t dictSize);
1101
- ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictMode_e dictMode);
1100
+ ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType);
1102
1101
 
1103
1102
 
1104
1103
  /*! ZSTD_CCtx_refCDict() :
@@ -1110,8 +1109,7 @@ ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void
1110
1109
  * Special : adding a NULL CDict means "return to no-dictionary mode".
1111
1110
  * Note 1 : Currently, only one dictionary can be managed.
1112
1111
  * Adding a new dictionary effectively "discards" any previous one.
1113
- * Note 2 : CDict is just referenced, its lifetime must outlive CCtx.
1114
- */
1112
+ * Note 2 : CDict is just referenced, its lifetime must outlive CCtx. */
1115
1113
  ZSTDLIB_API size_t ZSTD_CCtx_refCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict);
1116
1114
 
1117
1115
  /*! ZSTD_CCtx_refPrefix() :
@@ -1121,20 +1119,29 @@ ZSTDLIB_API size_t ZSTD_CCtx_refCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict);
1121
1119
  * Subsequent compression jobs will be done without prefix (if none is explicitly referenced).
1122
1120
  * If there is a need to use same prefix multiple times, consider embedding it into a ZSTD_CDict instead.
1123
1121
  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
1124
- * Special : Adding any prefix (including NULL) invalidates any previous prefix or dictionary
1122
+ * Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary
1125
1123
  * Note 1 : Prefix buffer is referenced. It must outlive compression job.
1126
1124
  * Note 2 : Referencing a prefix involves building tables, which are dependent on compression parameters.
1127
- * It's a CPU-heavy operation, with non-negligible impact on latency.
1128
- * Note 3 : By default, the prefix is treated as raw content
1129
- * (ZSTD_dm_rawContent). Use ZSTD_CCtx_refPrefix_advanced() to alter
1130
- * dictMode. */
1125
+ * It's a CPU consuming operation, with non-negligible impact on latency.
1126
+ * Note 3 : By default, the prefix is treated as raw content (ZSTD_dm_rawContent).
1127
+ * Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode. */
1131
1128
  ZSTDLIB_API size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize);
1132
- ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize, ZSTD_dictMode_e dictMode);
1129
+ ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType);
1130
+
1131
+ /*! ZSTD_CCtx_reset() :
1132
+ * Return a CCtx to clean state.
1133
+ * Useful after an error, or to interrupt an ongoing compression job and start a new one.
1134
+ * Any internal data not yet flushed is cancelled.
1135
+ * Dictionary (if any) is dropped.
1136
+ * All parameters are back to default values.
1137
+ * It's possible to modify compression parameters after a reset.
1138
+ */
1139
+ ZSTDLIB_API void ZSTD_CCtx_reset(ZSTD_CCtx* cctx);
1133
1140
 
1134
1141
 
1135
1142
 
1136
1143
  typedef enum {
1137
- ZSTD_e_continue=0, /* collect more data, encoder transparently decides when to output result, for optimal conditions */
1144
+ ZSTD_e_continue=0, /* collect more data, encoder decides when to output compressed result, for optimal conditions */
1138
1145
  ZSTD_e_flush, /* flush any data provided so far - frame will continue, future data can still reference previous data for better compression */
1139
1146
  ZSTD_e_end /* flush any remaining data and close current frame. Any additional data starts a new frame. */
1140
1147
  } ZSTD_EndDirective;
@@ -1150,10 +1157,11 @@ typedef enum {
1150
1157
  * and then immediately returns, just indicating that there is some data remaining to be flushed.
1151
1158
  * The function nonetheless guarantees forward progress : it will return only after it reads or write at least 1+ byte.
1152
1159
  * - Exception : in multi-threading mode, if the first call requests a ZSTD_e_end directive, it is blocking : it will complete compression before giving back control to caller.
1153
- * - @return provides the minimum amount of data remaining to be flushed from internal buffers
1160
+ * - @return provides a minimum amount of data remaining to be flushed from internal buffers
1154
1161
  * or an error code, which can be tested using ZSTD_isError().
1155
1162
  * if @return != 0, flush is not fully completed, there is still some data left within internal buffers.
1156
- * This is useful to determine if a ZSTD_e_flush or ZSTD_e_end directive is completed.
1163
+ * This is useful for ZSTD_e_flush, since in this case more flushes are necessary to empty all buffers.
1164
+ * For ZSTD_e_end, @return == 0 when internal buffers are fully flushed and frame is completed.
1157
1165
  * - after a ZSTD_e_end directive, if internal buffer is not fully flushed (@return != 0),
1158
1166
  * only ZSTD_e_end or ZSTD_e_flush operations are allowed.
1159
1167
  * Before starting a new compression job, or changing compression parameters,
@@ -1164,16 +1172,6 @@ ZSTDLIB_API size_t ZSTD_compress_generic (ZSTD_CCtx* cctx,
1164
1172
  ZSTD_inBuffer* input,
1165
1173
  ZSTD_EndDirective endOp);
1166
1174
 
1167
- /*! ZSTD_CCtx_reset() :
1168
- * Return a CCtx to clean state.
1169
- * Useful after an error, or to interrupt an ongoing compression job and start a new one.
1170
- * Any internal data not yet flushed is cancelled.
1171
- * Dictionary (if any) is dropped.
1172
- * All parameters are back to default values.
1173
- * It's possible to modify compression parameters after a reset.
1174
- */
1175
- ZSTDLIB_API void ZSTD_CCtx_reset(ZSTD_CCtx* cctx); /* Not ready yet ! */
1176
-
1177
1175
 
1178
1176
  /*! ZSTD_compress_generic_simpleArgs() :
1179
1177
  * Same as ZSTD_compress_generic(),
@@ -1207,25 +1205,26 @@ ZSTDLIB_API size_t ZSTD_compress_generic_simpleArgs (
1207
1205
  * for static allocation for single-threaded compression.
1208
1206
  */
1209
1207
  ZSTDLIB_API ZSTD_CCtx_params* ZSTD_createCCtxParams(void);
1208
+ ZSTDLIB_API size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
1210
1209
 
1211
- /*! ZSTD_resetCCtxParams() :
1212
- * Reset params to default, with the default compression level.
1210
+
1211
+ /*! ZSTD_CCtxParams_reset() :
1212
+ * Reset params to default values.
1213
1213
  */
1214
- ZSTDLIB_API size_t ZSTD_resetCCtxParams(ZSTD_CCtx_params* params);
1214
+ ZSTDLIB_API size_t ZSTD_CCtxParams_reset(ZSTD_CCtx_params* params);
1215
1215
 
1216
- /*! ZSTD_initCCtxParams() :
1216
+ /*! ZSTD_CCtxParams_init() :
1217
1217
  * Initializes the compression parameters of cctxParams according to
1218
1218
  * compression level. All other parameters are reset to their default values.
1219
1219
  */
1220
- ZSTDLIB_API size_t ZSTD_initCCtxParams(ZSTD_CCtx_params* cctxParams, int compressionLevel);
1220
+ ZSTDLIB_API size_t ZSTD_CCtxParams_init(ZSTD_CCtx_params* cctxParams, int compressionLevel);
1221
1221
 
1222
- /*! ZSTD_initCCtxParams_advanced() :
1222
+ /*! ZSTD_CCtxParams_init_advanced() :
1223
1223
  * Initializes the compression and frame parameters of cctxParams according to
1224
1224
  * params. All other parameters are reset to their default values.
1225
1225
  */
1226
- ZSTDLIB_API size_t ZSTD_initCCtxParams_advanced(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params);
1226
+ ZSTDLIB_API size_t ZSTD_CCtxParams_init_advanced(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params);
1227
1227
 
1228
- ZSTDLIB_API size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
1229
1228
 
1230
1229
  /*! ZSTD_CCtxParam_setParameter() :
1231
1230
  * Similar to ZSTD_CCtx_setParameter.
@@ -1238,9 +1237,10 @@ ZSTDLIB_API size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* params, ZSTD_cP
1238
1237
 
1239
1238
  /*! ZSTD_CCtx_setParametersUsingCCtxParams() :
1240
1239
  * Apply a set of ZSTD_CCtx_params to the compression context.
1241
- * This must be done before the dictionary is loaded.
1242
- * The pledgedSrcSize is treated as unknown.
1243
- * Multithreading parameters are applied only if nbThreads > 1.
1240
+ * This can be done even after compression is started,
1241
+ * if nbWorkers==0, this will have no impact until a new compression is started.
1242
+ * if nbWorkers>=1, new parameters will be picked up at next job,
1243
+ * with a few restrictions (windowLog, pledgedSrcSize, nbWorkers, jobSize, and overlapLog are not updated).
1244
1244
  */
1245
1245
  ZSTDLIB_API size_t ZSTD_CCtx_setParametersUsingCCtxParams(
1246
1246
  ZSTD_CCtx* cctx, const ZSTD_CCtx_params* params);
@@ -1267,9 +1267,9 @@ ZSTDLIB_API size_t ZSTD_CCtx_setParametersUsingCCtxParams(
1267
1267
  * Note 3 : Use ZSTD_DCtx_loadDictionary_advanced() to select
1268
1268
  * how dictionary content will be interpreted and loaded.
1269
1269
  */
1270
- ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary(ZSTD_DCtx* dctx, const void* dict, size_t dictSize); /* not implemented */
1271
- ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary_byReference(ZSTD_DCtx* dctx, const void* dict, size_t dictSize); /* not implemented */
1272
- ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary_advanced(ZSTD_DCtx* dctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictMode_e dictMode); /* not implemented */
1270
+ ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary(ZSTD_DCtx* dctx, const void* dict, size_t dictSize);
1271
+ ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary_byReference(ZSTD_DCtx* dctx, const void* dict, size_t dictSize);
1272
+ ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary_advanced(ZSTD_DCtx* dctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType);
1273
1273
 
1274
1274
 
1275
1275
  /*! ZSTD_DCtx_refDDict() :
@@ -1281,7 +1281,7 @@ ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary_advanced(ZSTD_DCtx* dctx, const void
1281
1281
  * Special : adding a NULL DDict means "return to no-dictionary mode".
1282
1282
  * Note 2 : DDict is just referenced, its lifetime must outlive its usage from DCtx.
1283
1283
  */
1284
- ZSTDLIB_API size_t ZSTD_DCtx_refDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict); /* not implemented */
1284
+ ZSTDLIB_API size_t ZSTD_DCtx_refDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict);
1285
1285
 
1286
1286
 
1287
1287
  /*! ZSTD_DCtx_refPrefix() :
@@ -1295,8 +1295,8 @@ ZSTDLIB_API size_t ZSTD_DCtx_refDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict);
1295
1295
  * Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode.
1296
1296
  * Note 4 : Referencing a raw content prefix has almost no cpu nor memory cost.
1297
1297
  */
1298
- ZSTDLIB_API size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize); /* not implemented */
1299
- ZSTDLIB_API size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize, ZSTD_dictMode_e dictMode); /* not implemented */
1298
+ ZSTDLIB_API size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize);
1299
+ ZSTDLIB_API size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType);
1300
1300
 
1301
1301
 
1302
1302
  /*! ZSTD_DCtx_setMaxWindowSize() :
@@ -1389,7 +1389,7 @@ ZSTDLIB_API void ZSTD_DCtx_reset(ZSTD_DCtx* dctx);
1389
1389
  ZSTDLIB_API size_t ZSTD_getBlockSize (const ZSTD_CCtx* cctx);
1390
1390
  ZSTDLIB_API size_t ZSTD_compressBlock (ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
1391
1391
  ZSTDLIB_API size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
1392
- ZSTDLIB_API size_t ZSTD_insertBlock(ZSTD_DCtx* dctx, const void* blockStart, size_t blockSize); /**< insert uncompressed block into `dctx` history. Useful for multi-blocks decompression */
1392
+ ZSTDLIB_API size_t ZSTD_insertBlock (ZSTD_DCtx* dctx, const void* blockStart, size_t blockSize); /**< insert uncompressed block into `dctx` history. Useful for multi-blocks decompression. */
1393
1393
 
1394
1394
 
1395
1395
  #endif /* ZSTD_H_ZSTD_STATIC_LINKING_ONLY */