From: Yann Collet Date: Tue, 20 Nov 2018 01:38:15 +0000 (-0800) Subject: removed some constants and _simpleArgs() from staging X-Git-Tag: v1.3.8~33^2~27 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=19e5f2a35bb97228be12355d0c42c6a1a93372ab;p=thirdparty%2Fzstd.git removed some constants and _simpleArgs() from staging constants that *may* change in the future will be accessed through functions instead (to be created). _simpleArgs() variant do not have (yet) a clear enough added value to deserve "stable" status. --- diff --git a/doc/zstd_manual.html b/doc/zstd_manual.html index cee8294c0..724454cbb 100644 --- a/doc/zstd_manual.html +++ b/doc/zstd_manual.html @@ -68,7 +68,7 @@

Version


 
-
unsigned ZSTD_versionNumber(void);   /**< useful to check dll version */
+
unsigned ZSTD_versionNumber(void);   /**< to check runtime library version */
 


 
Default constant

 
@@ -310,8 +310,8 @@ size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
   ZSTD_DStream objects can be re-used multiple times.
 
   Use ZSTD_initDStream() to start a new decompression operation,
-   or ZSTD_initDStream_usingDict() if decompression requires a dictionary.
-   @return : recommended first input size
+  or ZSTD_initDStream_usingDict() if decompression requires a dictionary.
+ @return : recommended first input size
 
   Use ZSTD_decompressStream() repetitively to consume your input.
   The function will update both `pos` fields.
@@ -385,7 +385,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
                ZSTD_btopt=7,
                ZSTD_btultra=8
                /* note : new strategies might be added in the future */
-           } ZSTD_strategy;
+} ZSTD_strategy;
 


 
typedef enum {
 
@@ -510,7 +510,8 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
                               * enum. See the comments on that enum for an
                               * explanation of the feature.
                               */
-    /* Question : should rsyncable be categorized as experimental, or be candidate for stable ? */
+
+    /* Question : should rsyncable remain experimental, or be part of candidate for stable ? */
     ZSTD_p_rsyncable,        /* Enables rsyncable mode, which makes compressed
                               * files more rsync friendly by adding periodic
                               * synchronization points to the compressed data.
@@ -534,6 +535,16 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
                               */
 } ZSTD_cParameter;
 


+
unsigned ZSTD_cParam_lowerBound(ZSTD_cParameter cParam);
+unsigned ZSTD_cParam_upperBound(ZSTD_cParameter cParam);
+
  All parameters must respect lower/upper bounds,
+  otherwise they will either trigger an error
+  or be automatically clamped.
+ @return : requested bound (inclusive)
+  note : if the request specifies a non-existing parameter, it will return 0.
+ 
+


+
 
size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, unsigned value);
 
  Set one compression parameter, selected by enum ZSTD_cParameter.
   Setting a parameter is generally only possible during frame initialization (before starting compression).
@@ -666,18 +677,6 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
  
 


 
-
size_t ZSTD_compress_generic_simpleArgs (
-                ZSTD_CCtx* cctx,
-                void* dst, size_t dstCapacity, size_t* dstPos,
-          const void* src, size_t srcSize, size_t* srcPos,
-                ZSTD_EndDirective endOp);
-
  Same as ZSTD_compress_generic(),
-  but using only integral types as arguments.
-  This variant might be helpful for binders from dynamic languages
-  which have troubles handling structures containing memory pointers.
- 
-


-
 
 ZSTDLIB_API size_t ZSTD_DCtx_setMaxWindowSize(ZSTD_DCtx* dctx, size_t maxWindowSize);
 
  Refuses allocating internal buffers for frames requiring a window size larger than provided limit.
   This protects a decoder context from reserving too much memory for itself (potential attack scenario).
@@ -753,22 +752,11 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
  
 


 
-
size_t ZSTD_decompress_generic_simpleArgs (
-                ZSTD_DCtx* dctx,
-                void* dst, size_t dstCapacity, size_t* dstPos,
-          const void* src, size_t srcSize, size_t* srcPos);
-
  Same as ZSTD_decompress_generic(),
-  but using only integral types as arguments.
-  This can be helpful for binders from dynamic languages
-  which have troubles handling structures containing memory pointers.
- 
-


-
 
experimental API (static linking only)
  The following symbols and constants
  are not planned to join "stable API" status anytime soon.
- Some of them will never reach "stable", and are planned to remain in the static_only section indefinitely.
- Some of them might even be removed in the future.
+ Some of them are planned to remain in the static_only section indefinitely.
+ Some of them might even be removed in the future (especially when redundant with existing stable functions)
  
 

 
@@ -998,19 +986,20 @@ static ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL };  /**< t
   both values are optional, select `0` if unknown. 
 


 
-
size_t ZSTD_compress_advanced (ZSTD_CCtx* cctx,
-                      void* dst, size_t dstCapacity,
-                const void* src, size_t srcSize,
-                const void* dict,size_t dictSize,
-                      ZSTD_parameters params);
-
   Same as ZSTD_compress_usingDict(), with fine-tune control over each compression parameter 
+
size_t ZSTD_compress_advanced(ZSTD_CCtx* cctx,
+                              void* dst, size_t dstCapacity,
+                        const void* src, size_t srcSize,
+                        const void* dict,size_t dictSize,
+                              ZSTD_parameters params);
+
  Same as ZSTD_compress_usingDict(), with fine-tune control over compression parameters (by structure) 
 


 
 
size_t ZSTD_compress_usingCDict_advanced(ZSTD_CCtx* cctx,
-                      void* dst, size_t dstCapacity,
-                const void* src, size_t srcSize,
-                const ZSTD_CDict* cdict, ZSTD_frameParameters fParams);
-
   Same as ZSTD_compress_usingCDict(), with fine-tune control over frame parameters 
+                                  void* dst, size_t dstCapacity,
+                            const void* src, size_t srcSize,
+                            const ZSTD_CDict* cdict,
+                                  ZSTD_frameParameters fParams);
+
  Same as ZSTD_compress_usingCDict(), with fine-tune control over frame parameters 
 


 
 
size_t ZSTD_CCtx_loadDictionary_byReference(ZSTD_CCtx* cctx, const void* dict, size_t dictSize);
@@ -1098,6 +1087,18 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
  
 


 
+
size_t ZSTD_compress_generic_simpleArgs (
+                ZSTD_CCtx* cctx,
+                void* dst, size_t dstCapacity, size_t* dstPos,
+          const void* src, size_t srcSize, size_t* srcPos,
+                ZSTD_EndDirective endOp);
+
  Same as ZSTD_compress_generic(),
+  but using only integral types as arguments.
+  This variant might be helpful for binders from dynamic languages
+  which have troubles handling structures containing memory pointers.
+ 
+


+
 
Advanced decompression functions

 
 
unsigned ZSTD_isFrame(const void* buffer, size_t size);
@@ -1164,7 +1165,21 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
  @return : 0, or an error code (which can be tested using ZSTD_isError()). 
 


 
-
Advanced streaming functions

+
size_t ZSTD_decompress_generic_simpleArgs (
+                ZSTD_DCtx* dctx,
+                void* dst, size_t dstCapacity, size_t* dstPos,
+          const void* src, size_t srcSize, size_t* srcPos);
+
  Same as ZSTD_decompress_generic(),
+  but using only integral types as arguments.
+  This can be helpful for binders from dynamic languages
+  which have troubles handling structures containing memory pointers.
+ 
+


+
+
Advanced streaming functions
  Warning : most of these functions are now redundant with the Advanced API.
+  Once Advanced API reaches "stable" status,
+  redundant functions will be deprecated, and then at some point removed.
+

 
 
Advanced Streaming compression functions
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. */
 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.*/
diff --git a/lib/zstd.h b/lib/zstd.h
index 769cbf50c..5789f018d 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -74,13 +74,13 @@ extern "C" {
 #define ZSTD_VERSION_RELEASE  8
 
 #define ZSTD_VERSION_NUMBER  (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE)
-ZSTDLIB_API unsigned ZSTD_versionNumber(void);   /**< useful to check dll version */
+ZSTDLIB_API unsigned ZSTD_versionNumber(void);   /**< to check runtime library version */
 
 #define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE
 #define ZSTD_QUOTE(str) #str
 #define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str)
 #define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)
-ZSTDLIB_API const char* ZSTD_versionString(void);   /* v1.3.0+ */
+ZSTDLIB_API const char* ZSTD_versionString(void);   /* since v1.3.0+ */
 
 /***************************************
 *  Default constant
@@ -354,8 +354,8 @@ ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output
 *  ZSTD_DStream objects can be re-used multiple times.
 *
 *  Use ZSTD_initDStream() to start a new decompression operation,
-*   or ZSTD_initDStream_usingDict() if decompression requires a dictionary.
-*   @return : recommended first input size
+*  or ZSTD_initDStream_usingDict() if decompression requires a dictionary.
+* @return : recommended first input size
 *
 *  Use ZSTD_decompressStream() repetitively to consume your input.
 *  The function will update both `pos` fields.
@@ -415,8 +415,13 @@ ZSTDLIB_API size_t ZSTD_DStreamOutSize(void);   /*!< recommended size for output
  * as the API is locked once reaching "stable" status.
  * ***************************************************************************************/
 
+
+/* ===   query limits   === */
+
 ZSTDLIB_API int ZSTD_minCLevel(void);  /*!< minimum negative compression level allowed */
 
+
+
 /* ---  Constants  ---*/
 
 /* all magic numbers are supposed read/written to/from files/memory using little-endian convention */
@@ -425,39 +430,9 @@ ZSTDLIB_API int ZSTD_minCLevel(void);  /*!< minimum negative compression level a
 #define ZSTD_MAGIC_SKIPPABLE_START  0x184D2A50    /* all 16 values, from 0x184D2A50 to 0x184D2A5F, signal the beginning of a skippable frame */
 #define ZSTD_MAGIC_SKIPPABLE_MASK   0xFFFFFFF0
 
-/* note : should this limit be smaller ? like 23 (8 MB) as suggested in the spec ?
- * can it be different from zstd cli default limit, which is designed to match --ultra and --long default (27) ? */
-#define ZSTD_WINDOWLOG_LIMIT_DEFAULT 27   /* by default, the streaming decoder will refuse any frame
-                                           * requiring larger than (1<