<BR></pre>
<pre><b>LZ4LIB_STATIC_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr);
-</b><p> Use this, like LZ4_resetStream(), to prepare a context for a new chain of
- calls to a streaming API (e.g., LZ4_compress_fast_continue()).
+</b><p> Use this to prepare a context for a new chain of calls to a streaming API
+ (e.g., LZ4_compress_fast_continue()).
+
+ Note:
+ To stay on the safe side, when LZ4_stream_t is used for the first time,
+ it should be either created using LZ4_createStream() or
+ initialized using LZ4_resetStream().
Note:
Using this in advance of a non-streaming-compression function is redundant,
since they all perform their own custom reset internally.
Differences from LZ4_resetStream():
- When an LZ4_stream_t is known to be in a internally coherent state,
- it can often be prepared for a new compression with almost no work,
- only sometimes falling back to the full, expensive reset
- that is always required when the stream is in an indeterminate state
- (i.e., the reset performed by LZ4_resetStream()).
+ When an LZ4_stream_t is known to be in an internally coherent state,
+ it will be prepared for a new compression with almost no work.
+ Otherwise, it will fall back to the full, expensive reset.
LZ4_streams are guaranteed to be in a valid state when:
- returned from LZ4_createStream()
call that fully reset the state (e.g., LZ4_compress_fast_extState()) and
that returned success
- When a stream isn't known to be in a valid state, it is not safe to pass to
- any fastReset or streaming function. It must first be cleansed by the full
- LZ4_resetStream().
+ Note:
+ A stream that was used in a compression call that did not return success
+ (e.g., LZ4_compress_fast_continue()), can still be passed to this function,
+ however, it's history is not preserved because of previous compression
+ failure.
</p></pre><BR>
</p></pre><BR>
<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
-</b><p> Provides minimum dstCapacity required to guarantee compression success
- given a srcSize and preferences, covering worst case scenario.
+</b><p> Provides minimum dstCapacity required to guarantee success of
+ LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario.
+ When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead.
+ Note that the result is only valid for a single invocation of LZ4F_compressUpdate().
+ When invoking LZ4F_compressUpdate() multiple times,
+ if the output buffer is gradually filled up instead of emptied and re-used from its start,
+ one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound().
+ @return is always the same for a srcSize and prefsPtr.
prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario.
- Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(),
- Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
- It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd().
- Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin().
- Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers.
- When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations.
+ tech details :
+ @return includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
+ It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd().
+ @return doesn't include frame header, as it was already generated by LZ4F_compressBegin().
</p></pre><BR>
`cOptPtr` is optional : it's possible to provide NULL, all options will be set to default.
@return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx)
or an error code if it fails (which can be tested using LZ4F_isError())
+ Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
</p></pre><BR>
`cOptPtr` is optional : NULL can be provided, in which case all options will be set to default.
@return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark),
or an error code if it fails (which can be tested using LZ4F_isError())
+ Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task.
</p></pre><BR>
/*---- Compression ----*/
#define LZ4F_HEADER_SIZE_MAX 19 /* LZ4 Frame header size can vary from 7 to 19 bytes */
+
/*! LZ4F_compressBegin() :
* will write the frame header into dstBuffer.
* dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes.
const LZ4F_preferences_t* prefsPtr);
/*! LZ4F_compressBound() :
- * Provides minimum dstCapacity required to guarantee compression success
- * given a srcSize and preferences, covering worst case scenario.
+ * Provides minimum dstCapacity required to guarantee success of
+ * LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario.
+ * When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead.
+ * Note that the result is only valid for a single invocation of LZ4F_compressUpdate().
+ * When invoking LZ4F_compressUpdate() multiple times,
+ * if the output buffer is gradually filled up instead of emptied and re-used from its start,
+ * one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound().
+ * @return is always the same for a srcSize and prefsPtr.
* prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario.
- * Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(),
- * Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
- * It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd().
- * Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin().
- * Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers.
- * When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations.
+ * tech details :
+ * @return includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
+ * It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd().
+ * @return doesn't include frame header, as it was already generated by LZ4F_compressBegin().
*/
LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
projects / platform / upstream / lz4.git / commitdiff