From 2e02cd330dee3fcf9a8609b90ed7b965e0a6f9a1 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Thu, 31 Oct 2024 15:06:48 -0700 Subject: [PATCH] inform manual users that it's automatically generated suggested by @Eugeny1 --- contrib/gen_html/gen_html.cpp | 1 + doc/zstd_manual.html | 49 +++++++++++++++++++++++++---------- lib/zstd.h | 2 +- 3 files changed, 37 insertions(+), 15 deletions(-) diff --git a/contrib/gen_html/gen_html.cpp b/contrib/gen_html/gen_html.cpp index 1da5879ad..adf0f41b9 100644 --- a/contrib/gen_html/gen_html.cpp +++ b/contrib/gen_html/gen_html.cpp @@ -211,6 +211,7 @@ int main(int argc, char *argv[]) { ostream << "\n\n\n" << version << "\n\n" << endl; ostream << "

" << version << "

\n"; + ostream << "Note: the content of this file has been automatically generated by parsing \"zstd.h\" \n"; ostream << "

-zstd 1.5.6 Manual +zstd 1.5.7 Manual -

zstd 1.5.6 Manual

zstd 1.5.7 Manual

+Note: the content of this file has been automatically generated by parsing "zstd.h"

Compression helper functions

size_t ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */
-

#define ZSTD_MAX_INPUT_SIZE ((sizeof(size_t)==8) ? 0xFF00FF00FF00FF00ULL : 0xFF00FF00U)
+#define ZSTD_COMPRESSBOUND(srcSize)   (((size_t)(srcSize) >= ZSTD_MAX_INPUT_SIZE) ? 0 : (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 */
+size_t ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */
+ maximum compressed size in worst case single-pass scenario.
+ When invoking `ZSTD_compress()`, or any other one-pass compression function,
+ it's recommended to provide @dstCapacity >= ZSTD_compressBound(srcSize)
+ as it eliminates one potential failure scenario,
+ aka not enough room in dst buffer to write the compressed frame.
+ Note : ZSTD_compressBound() itself can fail, if @srcSize > ZSTD_MAX_INPUT_SIZE .
+        In which case, ZSTD_compressBound() will return an error code
+        which can be tested using ZSTD_isError().
+
+ ZSTD_COMPRESSBOUND() :
+ same as ZSTD_compressBound(), but as a macro.
+ It can be used to produce constants, which can be useful for static allocation,
+ for example to size a static array on stack.
+ Will produce constant value 0 if srcSize is too large.
+ 
+

Error helper functions

#include "zstd_errors.h" /* list of errors */
 /* ZSTD_isError() :
  * Most ZSTD_* functions returning a size_t value can be tested for error,
  * using ZSTD_isError().
  * @return 1 if error, 0 otherwise
  */
-unsigned     ZSTD_isError(size_t code);        /*!< tells if a `size_t` function result is an error code */
+unsigned     ZSTD_isError(size_t result);      /*!< tells if a `size_t` function result is an error code */
 ZSTD_ErrorCode ZSTD_getErrorCode(size_t functionResult); /* convert a result into an error code, which can be compared to error enum list */
-const char*  ZSTD_getErrorName(size_t code);   /*!< provides readable string from an error code */
+const char*  ZSTD_getErrorName(size_t result); /*!< provides readable string from a function result */
 int          ZSTD_minCLevel(void);             /*!< minimum negative compression level allowed, requires v1.4.0+ */
 int          ZSTD_maxCLevel(void);             /*!< maximum compression level available */
 int          ZSTD_defaultCLevel(void);         /*!< default compression level, specified by ZSTD_CLEVEL_DEFAULT, requires v1.5.0+ */
@@ -163,17 +182,17 @@ int          ZSTD_defaultCLevel(void);         /*!< default compression leve
 Explicit context

 
 Compression context
  When compressing many times,
-  it is recommended to allocate a context just once,
+  it is recommended to allocate a compression context just once,
   and reuse it for each successive compression operation.
-  This will make workload friendlier for system's memory.
+  This will make the workload easier for system's memory.
   Note : re-using context is just a speed / resource optimization.
          It doesn't change the compression ratio, which remains identical.
-  Note 2 : In multi-threaded environments,
-         use one different context per thread for parallel execution.
+  Note 2: For parallel execution in multi-threaded environments,
+         use one different context per thread .
  
 
typedef struct ZSTD_CCtx_s ZSTD_CCtx;
 ZSTD_CCtx* ZSTD_createCCtx(void);
-size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);  /* accept NULL pointer */
+size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);  /* compatible with NULL pointer */
 


 size_t ZSTD_compressCCtx(ZSTD_CCtx* cctx,
                          void* dst, size_t dstCapacity,
@@ -184,7 +203,7 @@ size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);  /* accept NULL pointer */
   this function compresses at the requested compression level,
   __ignoring any other advanced parameter__ .
   If any advanced parameter was set using the advanced API,
-  they will all be reset. Only `compressionLevel` remains.
+  they will all be reset. Only @compressionLevel remains.
  
 


 
@@ -384,7 +403,8 @@ size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);  /* accept NULL pointer */
      * ZSTD_c_stableOutBuffer
      * ZSTD_c_blockDelimiters
      * ZSTD_c_validateSequences
-     * ZSTD_c_useBlockSplitter
+     * ZSTD_c_blockSplitterLevel
+     * ZSTD_c_splitAfterSequences
      * ZSTD_c_useRowMatchFinder
      * ZSTD_c_prefetchCDictTables
      * ZSTD_c_enableSeqProducerFallback
@@ -411,7 +431,8 @@ size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);  /* accept NULL pointer */
      ZSTD_c_experimentalParam16=1013,
      ZSTD_c_experimentalParam17=1014,
      ZSTD_c_experimentalParam18=1015,
-     ZSTD_c_experimentalParam19=1016
+     ZSTD_c_experimentalParam19=1016,
+     ZSTD_c_experimentalParam20=1017
 } ZSTD_cParameter;

typedef struct {
diff --git a/lib/zstd.h b/lib/zstd.h
index 22aca768c..d2d6795e4 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -218,7 +218,7 @@ ZSTDLIB_API size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize)
 
 /*======  Compression helper functions  ======*/
 
-/* ZSTD_compressBound() :
+/*! ZSTD_compressBound() :
  * maximum compressed size in worst case single-pass scenario.
  * When invoking `ZSTD_compress()`, or any other one-pass compression function,
  * it's recommended to provide @dstCapacity >= ZSTD_compressBound(srcSize)
-- 
2.47.3

" << version << "

Contents

zstd 1.5.6 Manual

zstd 1.5.7 Manual

Contents

Compression helper functions

Error helper functions

Explicit context

Compression context