<li><a href="#Chapter10">Streaming decompression - HowTo</a></li>
<li><a href="#Chapter11">ADVANCED AND EXPERIMENTAL FUNCTIONS</a></li>
<li><a href="#Chapter12">Candidate API for promotion to stable status</a></li>
-<li><a href="#Chapter13">Memory management</a></li>
-<li><a href="#Chapter14">Advanced compression API</a></li>
-<li><a href="#Chapter15">experimental API (static linking only)</a></li>
-<li><a href="#Chapter16">Frame size functions</a></li>
-<li><a href="#Chapter17">Memory management</a></li>
-<li><a href="#Chapter18">Advanced compression functions</a></li>
-<li><a href="#Chapter19">Advanced decompression functions</a></li>
-<li><a href="#Chapter20">Advanced streaming functions</a></li>
-<li><a href="#Chapter21">Buffer-less and synchronous inner streaming functions</a></li>
-<li><a href="#Chapter22">Buffer-less streaming compression (synchronous mode)</a></li>
-<li><a href="#Chapter23">Buffer-less streaming decompression (synchronous mode)</a></li>
-<li><a href="#Chapter24">ZSTD_getFrameHeader() :</a></li>
-<li><a href="#Chapter25">Block level API</a></li>
+<li><a href="#Chapter13">Advanced compression API</a></li>
+<li><a href="#Chapter14">experimental API (static linking only)</a></li>
+<li><a href="#Chapter15">Frame size functions</a></li>
+<li><a href="#Chapter16">Memory management</a></li>
+<li><a href="#Chapter17">Advanced compression functions</a></li>
+<li><a href="#Chapter18">Advanced decompression functions</a></li>
+<li><a href="#Chapter19">Advanced streaming functions</a></li>
+<li><a href="#Chapter20">Buffer-less and synchronous inner streaming functions</a></li>
+<li><a href="#Chapter21">Buffer-less streaming compression (synchronous mode)</a></li>
+<li><a href="#Chapter22">Buffer-less streaming decompression (synchronous mode)</a></li>
+<li><a href="#Chapter23">ZSTD_getFrameHeader() :</a></li>
+<li><a href="#Chapter24">Block level API</a></li>
</ol>
<hr>
<a name="Chapter1"></a><h2>Introduction</h2><pre>
<a name="Chapter12"></a><h2>Candidate API for promotion to stable status</h2><pre>
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.
<BR></pre>
<pre><b>int ZSTD_minCLevel(void); </b>/*!< minimum negative compression level allowed */<b>
</b></pre><BR>
-<a name="Chapter13"></a><h2>Memory management</h2><pre></pre>
+<pre><b>size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
+</b><p> `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
+</p></pre><BR>
<pre><b>size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx);
size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx* dctx);
Object memory usage can evolve (increase or decrease) over time.
</p></pre><BR>
-<a name="Chapter1
4"></a><h2>Advanced compression API</h2><pre></pre>
+<a name="Chapter1
3"></a><h2>Advanced compression API</h2><pre></pre>
<pre><b>typedef enum { ZSTD_fast=1,
ZSTD_dfast=2,
</p></pre><BR>
-<a name="Chapter1
5"></a><h2>experimental API (static linking only)</h2><pre>
+<a name="Chapter1
4"></a><h2>experimental API (static linking only)</h2><pre>
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.
ZSTD_dictForceCopy = 2, </b>/* Always copy the dictionary. */<b>
} ZSTD_dictAttachPref_e;
</b></pre><BR>
-<a name="Chapter1
6"></a><h2>Frame size functions</h2><pre></pre>
+<a name="Chapter1
5"></a><h2>Frame size functions</h2><pre></pre>
<pre><b>size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
</b><p> `src` should point to the start of a ZSTD encoded frame or skippable frame
or an error code (if srcSize is too small)
</p></pre><BR>
-<a name="Chapter1
7"></a><h2>Memory management</h2><pre></pre>
+<a name="Chapter1
6"></a><h2>Memory management</h2><pre></pre>
<pre><b>size_t ZSTD_estimateCCtxSize(int compressionLevel);
size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams);
</p></pre><BR>
-<a name="Chapter1
8"></a><h2>Advanced compression functions</h2><pre></pre>
+<a name="Chapter1
7"></a><h2>Advanced compression functions</h2><pre></pre>
<pre><b>ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel);
</b><p> Create a digested dictionary for compression
</p></pre><BR>
-<a name="Chapter1
9"></a><h2>Advanced decompression functions</h2><pre></pre>
+<a name="Chapter1
8"></a><h2>Advanced decompression functions</h2><pre></pre>
<pre><b>unsigned ZSTD_isFrame(const void* buffer, size_t size);
</b><p> Tells if the content of `buffer` starts with a valid Frame Identifier.
</p></pre><BR>
-<a name="Chapter
20"></a><h2>Advanced streaming functions</h2><pre> Warning : most of these functions are now redundant with the Advanced API.
+<a name="Chapter
19"></a><h2>Advanced streaming functions</h2><pre> 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.
<BR></pre>
size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict); </b>/**< note : ddict is referenced, it must outlive decompression session */<b>
size_t ZSTD_resetDStream(ZSTD_DStream* zds); </b>/**< re-use decompression parameters from previous init; saves dictionary loading */<b>
</pre></b><BR>
-<a name="Chapter2
1"></a><h2>Buffer-less and synchronous inner streaming functions</h2><pre>
+<a name="Chapter2
0"></a><h2>Buffer-less and synchronous inner streaming functions</h2><pre>
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.
<BR></pre>
-<a name="Chapter2
2"></a><h2>Buffer-less streaming compression (synchronous mode)</h2><pre>
+<a name="Chapter2
1"></a><h2>Buffer-less streaming compression (synchronous mode)</h2><pre>
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.
size_t ZSTD_compressBegin_usingCDict_advanced(ZSTD_CCtx* const cctx, const ZSTD_CDict* const cdict, ZSTD_frameParameters const fParams, unsigned long long const pledgedSrcSize); </b>/* compression parameters are already set within cdict. pledgedSrcSize must be correct. If srcSize is not known, use macro ZSTD_CONTENTSIZE_UNKNOWN */<b>
size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx, unsigned long long pledgedSrcSize); </b>/**< note: if pledgedSrcSize is not known, use ZSTD_CONTENTSIZE_UNKNOWN */<b>
</pre></b><BR>
-<a name="Chapter2
3"></a><h2>Buffer-less streaming decompression (synchronous mode)</h2><pre>
+<a name="Chapter2
2"></a><h2>Buffer-less streaming decompression (synchronous mode)</h2><pre>
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.
unsigned checksumFlag;
} ZSTD_frameHeader;
</pre></b><BR>
-<a name="Chapter2
4"></a><h2>ZSTD_getFrameHeader() :</h2><pre> decode Frame Header, or requires larger `srcSize`.
+<a name="Chapter2
3"></a><h2>ZSTD_getFrameHeader() :</h2><pre> 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()
<pre><b>typedef enum { ZSTDnit_frameHeader, ZSTDnit_blockHeader, ZSTDnit_block, ZSTDnit_lastBlock, ZSTDnit_checksum, ZSTDnit_skippableFrame } ZSTD_nextInputType_e;
</b></pre><BR>
-<a name="Chapter2
5"></a><h2>Block level API</h2><pre></pre>
+<a name="Chapter2
4"></a><h2>Block level API</h2><pre></pre>
<pre><b></b><p> 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.
/****************************************************************************************
* 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<<ZSTD_BLOCKSIZELOG_MAX)
-/* --- Constants ---*/
+/* === query limits === */
-/* 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
+ZSTDLIB_API int ZSTD_minCLevel(void); /*!< minimum negative compression level allowed */
-#define ZSTD_BLOCKSIZELOG_MAX 17
-#define ZSTD_BLOCKSIZE_MAX (1<<ZSTD_BLOCKSIZELOG_MAX)
+/* === frame size === */
-/***************************************
-* Memory management
-***************************************/
+/*! ZSTD_findFrameCompressedSize() :
+ * `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 */
+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.
* 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 */
* 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
projects / thirdparty / zstd.git / commitdiff
