Upgrade LZ4.

ext/lz4/lz4.h

@@ -37,12 +37,17 @@
 extern "C" {
 #endif
 
+/*
+ * lz4.h provides raw compression format functions, for optimal performance and integration into programs.
+ * If you need to generate data using an inter-operable format (respecting the framing specification),
+ * please use lz4frame.h instead.
+*/
 
 /**************************************
    Version
 **************************************/
-#define LZ4_VERSION_MAJOR    1    /* for major interface/format changes  */
+#define LZ4_VERSION_MAJOR    1    /* for breaking interface changes  */
-#define LZ4_VERSION_MINOR    3    /* for minor interface/format changes  */
+#define LZ4_VERSION_MINOR    5    /* for new (non-breaking) interface capabilities */
 #define LZ4_VERSION_RELEASE  0    /* for tweaks, bug-fixes, or development */
 #define LZ4_VERSION_NUMBER (LZ4_VERSION_MAJOR *100*100 + LZ4_VERSION_MINOR *100 + LZ4_VERSION_RELEASE)
 int LZ4_versionNumber (void);
@@ -64,12 +69,12 @@ int LZ4_versionNumber (void);
    Simple Functions
 **************************************/
 
-int LZ4_compress        (const char* source, char* dest, int inputSize);
+int LZ4_compress        (const char* source, char* dest, int sourceSize);
 int LZ4_decompress_safe (const char* source, char* dest, int compressedSize, int maxDecompressedSize);
 
 /*
 LZ4_compress() :
-    Compresses 'inputSize' bytes from 'source' into 'dest'.
+    Compresses 'sourceSize' bytes from 'source' into 'dest'.
     Destination buffer must be already allocated,
     and must be sized to handle worst cases situations (input data not compressible)
     Worst case size evaluation is provided by function LZ4_compressBound()
@@ -83,16 +88,9 @@ LZ4_decompress_safe() :
     return : the number of bytes decompressed into the destination buffer (necessarily <= maxDecompressedSize)
              If the destination buffer is not large enough, decoding will stop and output an error code (<0).
              If the source stream is detected malformed, the function will stop decoding and return a negative result.
-             This function is protected against buffer overflow exploits :
+             This function is protected against buffer overflow exploits,
-             it never writes outside of output buffer, and never reads outside of input buffer.
+             and never writes outside of output buffer, nor reads outside of input buffer.
-             Therefore, it is protected against malicious data packets.
+             It is also protected against malicious data packets.
-*/
-
-
-/*
-Note :
-    Should you prefer to explicitly allocate compression-table memory using your own allocation method,
-    use the streaming functions provided below, simply reset the memory area between each call to LZ4_compress_continue()
 */
 
 
@@ -104,9 +102,9 @@ Note :
 
 /*
 LZ4_compressBound() :
-    Provides the maximum size that LZ4 may output in a "worst case" scenario (input data not compressible)
+    Provides the maximum size that LZ4 compression may output in a "worst case" scenario (input data not compressible)
-    primarily useful for memory allocation of output buffer.
+    This function is primarily useful for memory allocation purposes (output buffer size).
-    macro is also provided when result needs to be evaluated at compilation (such as stack memory allocation).
+    Macro LZ4_COMPRESSBOUND() is also provided for compilation-time evaluation (stack memory allocation for example).
 
     isize  : is the input size. Max supported value is LZ4_MAX_INPUT_SIZE
     return : maximum output size in a "worst case" scenario
@@ -117,16 +115,17 @@ int LZ4_compressBound(int isize);
 
 /*
 LZ4_compress_limitedOutput() :
-    Compress 'inputSize' bytes from 'source' into an output buffer 'dest' of maximum size 'maxOutputSize'.
+    Compress 'sourceSize' bytes from 'source' into an output buffer 'dest' of maximum size 'maxOutputSize'.
     If it cannot achieve it, compression will stop, and result of the function will be zero.
+    This saves time and memory on detecting non-compressible (or barely compressible) data.
     This function never writes outside of provided output buffer.
 
-    inputSize  : Max supported value is LZ4_MAX_INPUT_VALUE
+    sourceSize  : Max supported value is LZ4_MAX_INPUT_VALUE
     maxOutputSize : is the size of the destination buffer (which must be already allocated)
     return : the number of bytes written in buffer 'dest'
-             or 0 if the compression fails
+             or 0 if compression fails
 */
-int LZ4_compress_limitedOutput (const char* source, char* dest, int inputSize, int maxOutputSize);
+int LZ4_compress_limitedOutput (const char* source, char* dest, int sourceSize, int maxOutputSize);
 
 
 /*
@@ -148,7 +147,7 @@ LZ4_decompress_fast() :
              Destination buffer must be already allocated. Its size must be a minimum of 'originalSize' bytes.
     note : This function fully respect memory boundaries for properly formed compressed data.
            It is a bit faster than LZ4_decompress_safe().
-           However, it does not provide any protection against intentionnally modified data stream (malicious input).
+           However, it does not provide any protection against intentionally modified data stream (malicious input).
            Use this function in trusted environment only (data to decode comes from a trusted source).
 */
 int LZ4_decompress_fast (const char* source, char* dest, int originalSize);
@@ -170,107 +169,106 @@ int LZ4_decompress_safe_partial (const char* source, char* dest, int compressedS
 
 
 /***********************************************
-   Experimental Streaming Compression Functions
+   Streaming Compression Functions
 ***********************************************/
 
-#define LZ4_STREAMSIZE_U32 ((1 << (LZ4_MEMORY_USAGE-2)) + 8)
+#define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE-3)) + 4)
-#define LZ4_STREAMSIZE     (LZ4_STREAMSIZE_U32 * sizeof(unsigned int))
+#define LZ4_STREAMSIZE     (LZ4_STREAMSIZE_U64 * sizeof(long long))
 /*
  * LZ4_stream_t
  * information structure to track an LZ4 stream.
  * important : init this structure content before first use !
+ * note : only allocated directly the structure if you are statically linking LZ4
+ *        If you are using liblz4 as a DLL, please use below construction methods instead.
  */
-typedef struct { unsigned int table[LZ4_STREAMSIZE_U32]; } LZ4_stream_t;
+typedef struct { long long table[LZ4_STREAMSIZE_U64]; } LZ4_stream_t;
 
 /*
  * LZ4_resetStream
- * Use this function to init a newly allocated LZ4_stream_t structure
+ * Use this function to init an allocated LZ4_stream_t structure
- * You can also reset an existing LZ4_stream_t structure
  */
-void LZ4_resetStream (LZ4_stream_t* LZ4_stream);
+void LZ4_resetStream (LZ4_stream_t* LZ4_streamPtr);
 
 /*
- * If you prefer dynamic allocation methods,
  * LZ4_createStream will allocate and initialize an LZ4_stream_t structure
  * LZ4_freeStream releases its memory.
+ * In the context of a DLL (liblz4), please use these methods rather than the static struct.
+ * They are more future proof, in case of a change of LZ4_stream_t size.
  */
 LZ4_stream_t* LZ4_createStream(void);
-int           LZ4_freeStream (LZ4_stream_t* LZ4_stream);
+int           LZ4_freeStream (LZ4_stream_t* LZ4_streamPtr);
 
 /*
  * LZ4_loadDict
  * Use this function to load a static dictionary into LZ4_stream.
  * Any previous data will be forgotten, only 'dictionary' will remain in memory.
  * Loading a size of 0 is allowed.
- * Return : 1 if OK, 0 if error
+ * Return : dictionary size, in bytes (necessarily <= 64 KB)
  */
-int LZ4_loadDict (LZ4_stream_t* LZ4_stream, const char* dictionary, int dictSize);
+int LZ4_loadDict (LZ4_stream_t* LZ4_streamPtr, const char* dictionary, int dictSize);
 
 /*
  * LZ4_compress_continue
  * Compress data block 'source', using blocks compressed before as dictionary to improve compression ratio
  * Previous data blocks are assumed to still be present at their previous location.
  */
-int LZ4_compress_continue (LZ4_stream_t* LZ4_stream, const char* source, char* dest, int inputSize);
+int LZ4_compress_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize);
 
 /*
  * LZ4_compress_limitedOutput_continue
  * Same as before, but also specify a maximum target compressed size (maxOutputSize)
  * If objective cannot be met, compression exits, and returns a zero.
  */
-int LZ4_compress_limitedOutput_continue (LZ4_stream_t* LZ4_stream, const char* source, char* dest, int inputSize, int maxOutputSize);
+int LZ4_compress_limitedOutput_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize, int maxOutputSize);
 
 /*
  * LZ4_saveDict
  * If previously compressed data block is not guaranteed to remain available at its memory location
- * save it into a safe place (char* safeBuffer)
+ * save it into a safer place (char* safeBuffer)
  * Note : you don't need to call LZ4_loadDict() afterwards,
  *        dictionary is immediately usable, you can therefore call again LZ4_compress_continue()
- * Return : 1 if OK, 0 if error
+ * Return : dictionary size in bytes, or 0 if error
  * Note : any dictSize > 64 KB will be interpreted as 64KB.
  */
-int LZ4_saveDict (LZ4_stream_t* LZ4_stream, char* safeBuffer, int dictSize);
+int LZ4_saveDict (LZ4_stream_t* LZ4_streamPtr, char* safeBuffer, int dictSize);
 
 
 /************************************************
-  Experimental Streaming Decompression Functions
+   Streaming Decompression Functions
 ************************************************/
 
-#define LZ4_STREAMDECODESIZE_U32 4
+#define LZ4_STREAMDECODESIZE_U64  4
-#define LZ4_STREAMDECODESIZE     (LZ4_STREAMDECODESIZE_U32 * sizeof(unsigned int))
+#define LZ4_STREAMDECODESIZE     (LZ4_STREAMDECODESIZE_U64 * sizeof(unsigned long long))
+typedef struct { unsigned long long table[LZ4_STREAMDECODESIZE_U64]; } LZ4_streamDecode_t;
 /*
  * LZ4_streamDecode_t
  * information structure to track an LZ4 stream.
- * important : init this structure content using LZ4_setStreamDecode or memset() before first use !
+ * init this structure content using LZ4_setStreamDecode or memset() before first use !
- */
+ *
-typedef struct { unsigned int table[LZ4_STREAMDECODESIZE_U32]; } LZ4_streamDecode_t;
+ * In the context of a DLL (liblz4) please prefer usage of construction methods below.
-
+ * They are more future proof, in case of a change of LZ4_streamDecode_t size in the future.
-/*
- * LZ4_setStreamDecode
- * Use this function to instruct where to find the dictionary.
- * This function can be used to specify a static dictionary,
- * or to instruct where to find some previously decoded data saved into a different memory space.
- * Setting a size of 0 is allowed (same effect as no dictionary).
- * Return : 1 if OK, 0 if error
- */
-int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize);
-
-/*
- * If you prefer dynamic allocation methods,
  * LZ4_createStreamDecode will allocate and initialize an LZ4_streamDecode_t structure
  * LZ4_freeStreamDecode releases its memory.
  */
 LZ4_streamDecode_t* LZ4_createStreamDecode(void);
 int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
 
+/*
+ * LZ4_setStreamDecode
+ * Use this function to instruct where to find the dictionary.
+ * Setting a size of 0 is allowed (same effect as reset).
+ * Return : 1 if OK, 0 if error
+ */
+int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize);
+
 /*
 *_continue() :
     These decoding functions allow decompression of multiple blocks in "streaming" mode.
-    Previously decoded blocks must still be available at the memory position where they were decoded.
+    Previously decoded blocks *must* remain available at the memory position where they were decoded (up to 64 KB)
-    If it's not possible, save the relevant part of decoded data into a safe buffer,
+    If this condition is not possible, save the relevant part of decoded data into a safe buffer,
-    and indicate where its new address using LZ4_setDictDecode()
+    and indicate where is its new address using LZ4_setStreamDecode()
 */
-int LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* source, char* dest, int compressedSize, int maxOutputSize);
+int LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* source, char* dest, int compressedSize, int maxDecompressedSize);
 int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* source, char* dest, int originalSize);
 
 
@@ -279,10 +277,9 @@ Advanced decoding functions :
 *_usingDict() :
     These decoding functions work the same as
     a combination of LZ4_setDictDecode() followed by LZ4_decompress_x_continue()
-    all together into a single function call.
+    They are stand-alone and don't use nor update an LZ4_streamDecode_t structure.
-    It doesn't use nor update an LZ4_streamDecode_t structure.
 */
-int LZ4_decompress_safe_usingDict (const char* source, char* dest, int compressedSize, int maxOutputSize, const char* dictStart, int dictSize);
+int LZ4_decompress_safe_usingDict (const char* source, char* dest, int compressedSize, int maxDecompressedSize, const char* dictStart, int dictSize);
 int LZ4_decompress_fast_usingDict (const char* source, char* dest, int originalSize, const char* dictStart, int dictSize);
 
 
@@ -297,18 +294,10 @@ They are only provided here for compatibility with older user programs.
 - LZ4_uncompress is the same as LZ4_decompress_fast
 - LZ4_uncompress_unknownOutputSize is the same as LZ4_decompress_safe
 These function prototypes are now disabled; uncomment them if you really need them.
-It is highly recommended to stop using these functions and migrated to newer ones */
+It is highly recommended to stop using these functions and migrate to newer ones */
 /* int LZ4_uncompress (const char* source, char* dest, int outputSize); */
 /* int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); */
 
-/*
- * If you prefer dynamic allocation methods,
- * LZ4_createStreamDecode()
- * provides a pointer (void*) towards an initialized LZ4_streamDecode_t structure.
- * LZ4_free just frees it.
- */
-/* void* LZ4_createStreamDecode(void); */
-/*int   LZ4_free (void* LZ4_stream);    yes, it's the same one as for compression */
 
 /* Obsolete streaming functions; use new streaming interface whenever possible */
 void* LZ4_create (const char* inputBuffer);