Added : format description file

Added : new tuning parameter : LZ4_COMPRESSMIN. Thanks to Maciej Adamczyk for suggestion.
changed : macro for bswap16, in order to help GCC intrinsic detection. Thank to Erik Andersen for suggestion.

git-svn-id: https://lz4.googlecode.com/svn/trunk@57 650e7d94-2a16-8b24-b05c-7c0b3f6821cd

1 files changed, 20 insertions, 14 deletions

diff --git a/lz4.h b/lz4.h
index 556562b..1061fdf 100644
--- a/lz4.h
+++ b/lz4.h
@@ -43,17 +43,18 @@ int LZ4_uncompress (const char* source, char* dest, int osize);
 

 /*

 LZ4_compress() :

-	return : the number of bytes in compressed buffer dest

+	return : the number of bytes written in buffer dest

+			 or 0 if the compression fails (if LZ4_COMPRESSMIN is set)

 	note : destination buffer must be already allocated. 

-		To avoid any problem, size it to handle worst cases situations (input data not compressible)

-		Worst case size is : "inputsize + 0.4%", with "0.4%" being at least 8 bytes.

+		destination buffer must be sized to handle worst cases situations (input data not compressible)

+		worst case size evaluation is provided by function LZ4_compressBound()

 

 LZ4_uncompress() :

 	osize  : is the output size, therefore the original size

 	return : the number of bytes read in the source buffer

 			 If the source stream is malformed, the function will stop decoding and return a negative result, indicating the byte position of the faulty instruction

-			 This version never writes beyond dest + osize, and is therefore protected against malicious data packets

-	note 2 : destination buffer must be already allocated

+			 This function never writes beyond dest + osize, and is therefore protected against malicious data packets

+	note : destination buffer must be already allocated

 */

 

 

@@ -65,11 +66,12 @@ int LZ4_compressBound(int isize);
 

 /*

 LZ4_compressBound() :

-	Provides the maximum size that LZ4 may output in a "worst case" scenario, for memory allocation of output buffer.

+	Provides the maximum size that LZ4 may output in a "worst case" scenario (input data not compressible)

+	primarily useful for memory allocation of output buffer.

 

 	isize  : is the input size

-	return : maximum size that LZ4 may output in a "worst case" scenario

-	note : this function is limited by "int" range

+	return : maximum output size in a "worst case" scenario

+	note : this function is limited by "int" range (2^31-1)

 */

 

 

@@ -81,25 +83,29 @@ LZ4_uncompress_unknownOutputSize() :
 	maxOutputSize : is the size of the destination buffer (which must be already allocated)

 	return : the number of bytes decoded in the destination buffer (necessarily <= maxOutputSize)

 			 If the source stream is malformed, the function will stop decoding and return a negative result, indicating the byte position of the faulty instruction

-			 This version never writes beyond dest + maxOutputSize, and is therefore protected against malicious data packets

-	note   : This version is a bit slower than LZ4_uncompress

+			 This function never writes beyond dest + maxOutputSize, and is therefore protected against malicious data packets

+	note   : This version is slightly slower than LZ4_uncompress()

 */

 

 

 int LZ4_compressCtx(void** ctx, const char* source,  char* dest, int isize);

+int LZ4_compress64kCtx(void** ctx, const char* source,  char* dest, int isize);

 

 /*

 LZ4_compressCtx() :

 	This function explicitly handles the CTX memory structure.

-	It avoids allocating/deallocating memory between each call, improving performance when malloc is time-consuming.

-	Note : when memory is allocated into the stack (default mode), there is no "malloc" penalty.

-	Therefore, this function is mostly useful when memory is allocated into the heap (it requires increasing HASH_LOG value beyond STACK_LIMIT)

+	It avoids allocating/deallocating memory between each call, improving performance when malloc is heavily invoked.

+	This function is only useful when memory is allocated into the heap (HASH_LOG value beyond STACK_LIMIT)

+	Performance difference will be noticeable only when repetitively calling the compression function over many small segments.

+	Note : by default, memory is allocated into the stack, therefore "malloc" is not invoked.

+LZ4_compress64kCtx() :

+	Same as LZ4_compressCtx(), but specific to small inputs (<64KB).

+	isize *Must* be <64KB, otherwise the output will be corrupted.

 

 	On first call : provide a *ctx=NULL; It will be automatically allocated.

 	On next calls : reuse the same ctx pointer.

 	Use different pointers for different threads when doing multi-threading.

 

-	note : performance difference is small, mostly noticeable in HeapMode when repetitively calling the compression function over many small segments.

 */