From: Yann Collet Date: Wed, 21 Nov 2018 22:47:23 +0000 (-0800) Subject: promote ZSTD_findFrameCompressedSize() into staging area X-Git-Tag: v1.3.8~33^2~19 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fea920615cb8240d85918fdb9e209daae7b512f0;p=thirdparty%2Fzstd.git promote ZSTD_findFrameCompressedSize() into staging area --- diff --git a/doc/zstd_manual.html b/doc/zstd_manual.html index b1674bd42..1078f2b91 100644 --- a/doc/zstd_manual.html +++ b/doc/zstd_manual.html @@ -20,19 +20,18 @@
  • Streaming decompression - HowTo
  • ADVANCED AND EXPERIMENTAL FUNCTIONS
  • Candidate API for promotion to stable status
    • -
  • Memory management
    • -
  • Advanced compression API
    • -
  • experimental API (static linking only)
    • -
  • Frame size functions
    • -
  • Memory management
    • -
  • Advanced compression functions
    • -
  • Advanced decompression functions
    • -
  • Advanced streaming functions
    • -
  • Buffer-less and synchronous inner streaming functions
    • -
  • Buffer-less streaming compression (synchronous mode)
    • -
  • Buffer-less streaming decompression (synchronous mode)
    • -
  • ZSTD_getFrameHeader() :
    • -
  • Block level API
    • +
  • Advanced compression API
    • +
  • experimental API (static linking only)
    • +
  • Frame size functions
    • +
  • Memory management
    • +
  • Advanced compression functions
    • +
  • Advanced decompression functions
    • +
  • Advanced streaming functions
    • +
  • Buffer-less and synchronous inner streaming functions
    • +
  • Buffer-less streaming compression (synchronous mode)
    • +
  • Buffer-less streaming decompression (synchronous mode)
    • +
  • ZSTD_getFrameHeader() :
    • +
  • Block level API

    • Introduction

    @@ -354,16 +353,22 @@ size_t ZSTD_decompressStream(ZSTD_DStream* zds, ZSTD_outBuffer* output, ZSTD_inB
 
    Candidate API for promotion to stable status
      The following symbols and constants are in "staging area" :
  they are considered to join "stable API" status by v1.4.0.
- The below proposal is created so that it's possible to make it stable "as is".
- That being said, it's still possible to suggest modifications.
+ The below proposal is written so that it can become stable "as is".
+ It's still possible to suggest modifications.
  Staging is in fact last chance for changes,
- because the API is locked once reaching "stable" status.
+ the API is locked once reaching "stable" status.
  
 
    
 
 
    int ZSTD_minCLevel(void);  /*!< minimum negative compression level allowed */
 

    
-
    Memory management
    
+
    size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
+
     `src` should point to the start of a ZSTD frame or skippable frame.
+ `srcSize` must be >= first frame size
+ @return : the compressed size of the first frame starting at `src`,
+           suitable to pass to `ZSTD_decompress` or similar,
+           or an error code if input is invalid 
+

    
 
 
    size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx);
 size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx* dctx);
@@ -375,7 +380,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
   Object memory usage can evolve (increase or decrease) over time. 
 

    
 
-
    Advanced compression API
    
+
    Advanced compression API
    
 
 
    typedef enum { ZSTD_fast=1,
                ZSTD_dfast=2,
@@ -764,7 +769,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
  
 

    
 
-
    experimental API (static linking only)
    +
    experimental API (static linking only)
      The following symbols and constants
  are not planned to join "stable API" status anytime soon.
  Some of them are planned to remain in the static_only section indefinitely.
@@ -852,7 +857,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
     ZSTD_dictForceCopy     = 2, /* Always copy the dictionary. */
 } ZSTD_dictAttachPref_e;
 

    
-
    Frame size functions
    
+
    Frame size functions
    
 
 
    size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
 
      `src` should point to the start of a ZSTD encoded frame or skippable frame
@@ -891,7 +896,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
            or an error code (if srcSize is too small) 
 

    
 
-
    Memory management
    
+
    Memory management
    
 
 
    size_t ZSTD_estimateCCtxSize(int compressionLevel);
 size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams);
@@ -971,7 +976,7 @@ static ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL };  /**< t
  
 

    
 
-
    Advanced compression functions
    
+
    Advanced compression functions
    
 
 
    ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel);
 
      Create a digested dictionary for compression
@@ -1110,7 +1115,7 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
  
 

    
 
-
    Advanced decompression functions
    
+
    Advanced decompression functions
    
 
 
    unsigned ZSTD_isFrame(const void* buffer, size_t size);
 
      Tells if the content of `buffer` starts with a valid Frame Identifier.
@@ -1187,7 +1192,7 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
  
 

    
 
-
    Advanced streaming functions
      Warning : most of these functions are now redundant with the Advanced API.
+
    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.
 
    
@@ -1239,14 +1244,14 @@ size_t ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, const ZSTD_CDict*
 size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict);      /**< note : ddict is referenced, it must outlive decompression session */
 size_t ZSTD_resetDStream(ZSTD_DStream* zds);  /**< re-use decompression parameters from previous init; saves dictionary loading */
 

    
-
    Buffer-less and synchronous inner streaming functions
    +
    Buffer-less and synchronous inner streaming functions
       This is an advanced API, giving full control over buffer management, for users which need direct control over memory.
   But it's also a complex one, with several restrictions, documented below.
   Prefer normal streaming API for an easier experience.
  
 
    
 
-
    Buffer-less streaming compression (synchronous mode)
    +
    Buffer-less streaming compression (synchronous mode)
       A ZSTD_CCtx object is required to track streaming operations.
   Use ZSTD_createCCtx() / ZSTD_freeCCtx() to manage resource.
   ZSTD_CCtx object can be re-used multiple times within successive compression operations.
@@ -1282,7 +1287,7 @@ size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict);
 size_t ZSTD_compressBegin_usingCDict_advanced(ZSTD_CCtx* const cctx, const ZSTD_CDict* const cdict, ZSTD_frameParameters const fParams, unsigned long long const pledgedSrcSize);   /* compression parameters are already set within cdict. pledgedSrcSize must be correct. If srcSize is not known, use macro ZSTD_CONTENTSIZE_UNKNOWN */
 size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx, unsigned long long pledgedSrcSize); /**<  note: if pledgedSrcSize is not known, use ZSTD_CONTENTSIZE_UNKNOWN */
 

    
-
    Buffer-less streaming decompression (synchronous mode)
    +
    Buffer-less streaming decompression (synchronous mode)
       A ZSTD_DCtx object is required to track streaming operations.
   Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it.
   A ZSTD_DCtx object can be re-used multiple times.
@@ -1364,7 +1369,7 @@ typedef struct {
     unsigned checksumFlag;
 } ZSTD_frameHeader;
 

    
-
    ZSTD_getFrameHeader() :
      decode Frame Header, or requires larger `srcSize`.
+
    ZSTD_getFrameHeader() :
      decode Frame Header, or requires larger `srcSize`.
  @return : 0, `zfhPtr` is correctly filled,
           >0, `srcSize` is too small, value is wanted `srcSize` amount,
            or an error code, which can be tested using ZSTD_isError() 
@@ -1380,7 +1385,7 @@ size_t ZSTD_decodingBufferSize_min(unsigned long long windowSize, unsigned long
 
 
    typedef enum { ZSTDnit_frameHeader, ZSTDnit_blockHeader, ZSTDnit_block, ZSTDnit_lastBlock, ZSTDnit_checksum, ZSTDnit_skippableFrame } ZSTD_nextInputType_e;
 

    
-
    Block level API
    
+
    Block level API
    
 
 
        Frame metadata cost is typically ~18 bytes, which can be non-negligible for very small blocks (< 100 bytes).
     User will have to take in charge required information to regenerate data, such as compressed and content sizes.
diff --git a/lib/zstd.h b/lib/zstd.h
index 6d75d8ea6..055d245f9 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -408,36 +408,44 @@ ZSTDLIB_API size_t ZSTD_DStreamOutSize(void);   /*!< recommended size for output
 /****************************************************************************************
  *   Candidate API for promotion to stable status
  ****************************************************************************************
- * The following symbols and constants are in "staging area" :
+ * The following symbols and constants belong to the "staging area" :
  * they are considered to join "stable API" status by v1.4.0.
- * The below proposal is created so that it's possible to make it stable "as is".
- * That being said, it's still possible to suggest modifications.
+ * The below proposal is written so that it can become stable "as is".
+ * It's still possible to suggest modifications.
  * Staging is in fact last chance for changes,
- * because the API is locked once reaching "stable" status.
+ * the API is locked once reaching "stable" status.
  * ***************************************************************************************/
 
 
-/* ===   query limits   === */
+ /* ===  Constants   === */
 
-ZSTDLIB_API int ZSTD_minCLevel(void);  /*!< minimum negative compression level allowed */
+ /* all magic numbers are supposed read/written to/from files/memory using little-endian convention */
+ #define ZSTD_MAGICNUMBER            0xFD2FB528    /* valid since v0.8.0 */
+ #define ZSTD_MAGIC_DICTIONARY       0xEC30A437    /* valid since v0.7.0 */
+ #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
 
+ #define ZSTD_BLOCKSIZELOG_MAX  17
+ #define ZSTD_BLOCKSIZE_MAX     (1<= first frame size
+ * @return : the compressed size of the first frame starting at `src`,
+ *           suitable to pass to `ZSTD_decompress` or similar,
+ *           or an error code if input is invalid */
+ZSTDLIB_API size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
+
+
+/* ===   Memory management   === */
 
 /*! ZSTD_sizeof_*() :
  *  These functions give the current memory usage of selected object.
@@ -881,9 +889,10 @@ ZSTDLIB_API size_t ZSTD_decompress_generic(ZSTD_DCtx* dctx,
  *   experimental API (static linking only)
  ****************************************************************************************
  * The following symbols and constants
- * are not planned to join "stable API" status anytime soon.
+ * are not planned to join "stable API" status in the near future.
+ * They can still change in future versions.
  * 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)
+ * Some of them might be removed in the future (especially when redundant with existing stable functions)
  * ***************************************************************************************/
 
 #define ZSTD_FRAMEHEADERSIZE_PREFIX 5   /* minimum input size required to query frame header size */
@@ -1022,14 +1031,6 @@ typedef enum {
 *  Frame size functions
 ***************************************/
 
-/*! ZSTD_findFrameCompressedSize() :
- *  `src` should point to the start of a ZSTD encoded frame or skippable frame
- *  `srcSize` must be >= first frame size
- *  @return : the compressed size of the first frame starting at `src`,
- *            suitable to pass to `ZSTD_decompress` or similar,
- *            or an error code if input is invalid */
-ZSTDLIB_API size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
-
 /*! ZSTD_findDecompressedSize() :
  *  `src` should point the start of a series of ZSTD encoded and/or skippable frames
  *  `srcSize` must be the _exact_ size of this series