From bf9bf80f8d06aab75347ed6df62758511e91fbe3 Mon Sep 17 00:00:00 2001
From: Yann Collet 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()).
+ 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()
@@ -329,9 +332,11 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize,
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.
LZ4LIB_STATIC_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr);
-
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html
index 72e6782..2b16045 100644
--- a/doc/lz4frame_manual.html
+++ b/doc/lz4frame_manual.html
@@ -157,15 +157,19 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); -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().