diff options
author | Yann Collet <cyan@fb.com> | 2018-10-15 18:14:30 (GMT) |
---|---|---|
committer | Yann Collet <cyan@fb.com> | 2018-10-15 18:14:30 (GMT) |
commit | bf9bf80f8d06aab75347ed6df62758511e91fbe3 (patch) | |
tree | daf22cb208ea2eb0686a94ce4ca959162ffc7af3 /lib | |
parent | 5bd197e838269003e8d217cc0c83c03567e3cec7 (diff) | |
download | lz4-bf9bf80f8d06aab75347ed6df62758511e91fbe3.zip lz4-bf9bf80f8d06aab75347ed6df62758511e91fbe3.tar.gz lz4-bf9bf80f8d06aab75347ed6df62758511e91fbe3.tar.bz2 |
updated code documentation
to clarify #589
Diffstat (limited to 'lib')
-rw-r--r-- | lib/lz4frame.h | 21 |
1 files changed, 13 insertions, 8 deletions
diff --git a/lib/lz4frame.h b/lib/lz4frame.h index 599f17e..7c7c34e 100644 --- a/lib/lz4frame.h +++ b/lib/lz4frame.h @@ -248,6 +248,7 @@ LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); /*---- 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. @@ -260,15 +261,19 @@ LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx, 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); |