diff options
author | Yann Collet <cyan@fb.com> | 2018-09-07 23:21:31 (GMT) |
---|---|---|
committer | Yann Collet <cyan@fb.com> | 2018-09-07 23:21:31 (GMT) |
commit | eaed9ea4a15934e59f74902f0ed692a07151579d (patch) | |
tree | a77f02b437897266468c9d6c2fd1bb1bc02012f2 /lib | |
parent | bf614d3c51c9774df0f64285db314545f05bb5ef (diff) | |
download | lz4-eaed9ea4a15934e59f74902f0ed692a07151579d.zip lz4-eaed9ea4a15934e59f74902f0ed692a07151579d.tar.gz lz4-eaed9ea4a15934e59f74902f0ed692a07151579d.tar.bz2 |
updated function interface documentation
Diffstat (limited to 'lib')
-rw-r--r-- | lib/lz4.h | 24 |
1 files changed, 19 insertions, 5 deletions
@@ -226,14 +226,28 @@ LZ4LIB_API int LZ4_compress_destSize (const char* src, char* dst, int* srcSizePt LZ4LIB_API int LZ4_decompress_fast (const char* src, char* dst, int originalSize); /*! LZ4_decompress_safe_partial() : - * This function decompresses a compressed block of size 'srcSize' at position 'src' + * Decompress an LZ4 compressed block, of size 'srcSize' at position 'src', * into destination buffer 'dst' of size 'dstCapacity'. - * The function will decompress a minimum of 'targetOutputSize' bytes, and stop after that. - * However, it's not accurate, and may write more than 'targetOutputSize' (but always <= dstCapacity). + * Up to 'targetOutputSize' bytes will be decoded. + * The function stops decoding on reaching this objective, + * which can boost performance when only the beginning of a block is required. + * * @return : the number of bytes decoded in `dst` (necessarily <= dstCapacity) - * Note : this number can also be < targetOutputSize, if compressed block contains less data. * If source stream is detected malformed, function returns a negative result. - * This function is protected against malicious data packets. + * + * Note : @return can be < targetOutputSize, if compressed block contains less data. + * + * Note 2 : this function features 2 parameters, targetOutputSize and dstCapacity, + * and expects targetOutputSize <= dstCapacity. + * It effectively stops decoding on reaching targetOutputSize, + * so dstCapacity is kind of redundant. + * This is because in a previous version of this function, + * decoding operation would not "break" a sequence in the middle. + * As a consequence, there was no guarantee that decoding would stop at exactly targetOutputSize, + * it could write more bytes, though only up to dstCapacity. + * Some "margin" used to be required for this operation to work properly. + * This is no longer necessary. + * The function nonetheless keeps its signature, in an effort to not break API. */ LZ4LIB_API int LZ4_decompress_safe_partial (const char* src, char* dst, int srcSize, int targetOutputSize, int dstCapacity); |