update simple_buffer example

there were a few tiny inaccuracies, especially in error conditions.

diff --git a/examples/simple_buffer.c b/examples/simple_buffer.c
index 54e542a..027fc85 100644 (file)
--- a/examples/simple_buffer.c
+++ b/examples/simple_buffer.c
@@ -3,18 +3,18 @@
  * Copyright  : Kyle Harper
  * License    : Follows same licensing as the lz4.c/lz4.h program at any given time.  Currently, BSD 2.
  * Description: Example program to demonstrate the basic usage of the compress/decompress functions within lz4.c/lz4.h.
- *              The functions you'll likely want are LZ4_compress_default and LZ4_decompress_safe.  Both of these are documented in
- *              the lz4.h header file; I recommend reading them.
+ *              The functions you'll likely want are LZ4_compress_default and LZ4_decompress_safe.
+ *              Both of these are documented in the lz4.h header file; I recommend reading them.
  */
 
-/* Includes, for Power! */
-#include "lz4.h"     // This is all that is required to expose the prototypes for basic compression and decompression.
+/* Dependencies */
 #include <stdio.h>   // For printf()
 #include <string.h>  // For memcmp()
 #include <stdlib.h>  // For exit()
+#include "lz4.h"     // This is all that is required to expose the prototypes for basic compression and decompression.
 
 /*
- * Easy show-error-and-bail function.
+ * Simple show-error-and-bail function.
  */
 void run_screaming(const char* message, const int code) {
   printf("%s \n", message);
@@ -32,9 +32,9 @@ int main(void) {
   //   1) The return codes of LZ4_ functions are important.
   //      Read lz4.h if you're unsure what a given code means.
   //   2) LZ4 uses char* pointers in all LZ4_ functions.
-  //      This is baked into the API and probably not going to change.
-  //      If your program uses pointers that are unsigned char*, void*, or otherwise different,
-  //      you may need to do some casting or set the right -W compiler flags to ignore those warnings (e.g.: -Wno-pointer-sign).
+  //      This is baked into the API and not going to change, for consistency.
+  //      If your program uses different pointer types,
+  //      you may need to do some casting or set the right -Wno compiler flags to ignore those warnings (e.g.: -Wno-pointer-sign).
 
   /* Compression */
   // We'll store some text into a variable pointed to by *src to be compressed later.
@@ -44,7 +44,7 @@ int main(void) {
   // LZ4 provides a function that will tell you the maximum size of compressed output based on input data via LZ4_compressBound().
   const int max_dst_size = LZ4_compressBound(src_size);
   // We will use that size for our destination boundary when allocating space.
-  char* compressed_data = malloc(max_dst_size);
+  char* compressed_data = malloc((size_t)max_dst_size);
   if (compressed_data == NULL)
     run_screaming("Failed to allocate memory for *compressed_data.", 1);
   // That's all the information and preparation LZ4 needs to compress *src into *compressed_data.
@@ -52,21 +52,26 @@ int main(void) {
   // Save the return value for error checking.
   const int compressed_data_size = LZ4_compress_default(src, compressed_data, src_size, max_dst_size);
   // Check return_value to determine what happened.
-  if (compressed_data_size < 0)
-    run_screaming("A negative result from LZ4_compress_default indicates a failure trying to compress the data.  See exit code (echo $?) for value returned.", compressed_data_size);
-  if (compressed_data_size == 0)
-    run_screaming("A result of 0 means compression worked, but was stopped because the destination buffer couldn't hold all the information.", 1);
+  if (compressed_data_size <= 0)
+    run_screaming("A 0 or negative result from LZ4_compress_default() indicates a failure trying to compress the data. ", 1);
   if (compressed_data_size > 0)
     printf("We successfully compressed some data!\n");
   // Not only does a positive return_value mean success, the value returned == the number of bytes required.
   // You can use this to realloc() *compress_data to free up memory, if desired.  We'll do so just to demonstrate the concept.
-  compressed_data = (char *)realloc(compressed_data, compressed_data_size);
+  compressed_data = (char *)realloc(compressed_data, (size_t)compressed_data_size);
   if (compressed_data == NULL)
     run_screaming("Failed to re-alloc memory for compressed_data.  Sad :(", 1);
 
+
   /* Decompression */
-  // Now that we've successfully compressed the information from *src to *compressed_data, let's do the opposite!  We'll create a
-  // *new_src location of size src_size since we know that value.
+  // Now that we've successfully compressed the information from *src to *compressed_data, let's do the opposite!
+  // The decompression will need to know the compressed size, and an upper bound of the decompressed size.
+  // In this example, we just re-use this information from previous section,
+  // but in a real-world scenario, metadata must be transmitted to the decompression side.
+  // Each implementation is in charge of this part. Oftentimes, it adds some header of its own.
+  // Sometimes, the metadata can be extracted from the local context.
+
+  // First, let's create a *new_src location of size src_size since we know that value.
   char* const regen_buffer = malloc(src_size);
   if (regen_buffer == NULL)
     run_screaming("Failed to allocate memory for *regen_buffer.", 1);
@@ -77,17 +82,17 @@ int main(void) {
   free(compressed_data);   /* no longer useful */
   if (decompressed_size < 0)
     run_screaming("A negative result from LZ4_decompress_safe indicates a failure trying to decompress the data.  See exit code (echo $?) for value returned.", decompressed_size);
-  if (decompressed_size == 0)
-    run_screaming("I'm not sure this function can ever return 0.  Documentation in lz4.h doesn't indicate so.", 1);
-  if (decompressed_size > 0)
+  if (decompressed_size >= 0)
     printf("We successfully decompressed some data!\n");
   // Not only does a positive return value mean success,
   // value returned == number of bytes regenerated from compressed_data stream.
+  if (decompressed_size != src_size)
+    run_screaming("Decompressed data is different from original! \n", 1);
 
   /* Validation */
   // We should be able to compare our original *src with our *new_src and be byte-for-byte identical.
   if (memcmp(src, regen_buffer, src_size) != 0)
     run_screaming("Validation failed.  *src and *new_src are not identical.", 1);
-  printf("Validation done.  The string we ended up with is:\n%s\n", regen_buffer);
+  printf("Validation done. The string we ended up with is:\n%s\n", regen_buffer);
   return 0;
 }