add example code and library.properties

Author: Lorandil

README.md

@@ -1,6 +1,10 @@
 # uCompression
-uCompression provides RLE compression and decompression functions for microcontrollers implemented as static member functions, 
- so no instance of the class is required.
+Flash memory is valuable resource, especially when using graphical displays on small micro controllers like an ATTiny85 or the ATMega328PB (Arduino UNO). This is where data compression might save the day!
+
+**uCompression** provides fast RLE compression and decompression functions for micro controllers.
+It's easy to use, as it is implemented as static member functions, so no instance of the class is required.
+
+*The main design goals were code size and speed.*
 
 ## Compressing data
 
@@ -50,6 +54,9 @@ const uint8_t* uCompression::pgm_RLEdecompress256( const uint8_t* compressedData
  is automatically used, resulting in roughly the double decompression Speed.
 
 ## Limitiations
+The first and most important limitation is, that there is **NO error checking**!
+If a target buffer is too small or the chunk sizes for encoding is larger than for decoding, the behaviour is undefined, most likely the MCU will crash or reboot.
+
 RLE algorithms are specialized on efficiently compressing constant data areas. Random data cannot be compressed and will result in the compressed data being slightly larger than the original data.
  Under worst case conditions the resulting size will exceed the original data size (by 1 byte for every
  63 bytes of source data in a chunk).

examples/ASCII_Compression/ASCII_Compression.ino

@@ -0,0 +1,83 @@
+//
+// Demo code for uCompression
+//
+// (c)2024 by Lorandil
+//
+// This code is just a quick demonstration how to use the library and requires
+// at least 2kB of RAM and a serial interface to run.
+//
+// The library itself can even be used on an ATTiny25 when selecting an appropriate chunk size!
+//
+
+const uint16_t BUFFER_SIZE = 600;
+
+#include "uCompression.h"
+
+// some simple test data
+const uint8_t PROGMEM testData[] = 
+  "****************************************\n"
+  "*                                      *\n"
+  "* Welcome to the uCompression library! *\n"
+  "*                                      *\n"
+  "*       *                   *******    *\n"
+  "*      ***         ***      *     *    *\n"
+  "*     *****      *******    * *** *    *\n"
+  "*    *******    *********   * * * *    *\n"
+  "*   *********    *******    * *** *    *\n" 
+  "*      ***         ***      *     *    *\n"
+  "*      ***                  *******    *\n"
+  "*                                      *\n"
+  "****************************************\n";
+
+void setup()
+{
+  // wait a moment for the serial port to become ready
+  delay( 5000 );
+  // initialize serial transmission
+  Serial.begin( 115200 );
+}
+
+void loop() 
+{
+  uint16_t uncompressedSize = sizeof( testData );
+
+  // print the uncompressed data
+  Serial.print(F("Uncompressed data (size = ")); Serial.print( uncompressedSize ); Serial.println(F(")"));
+  Serial.print( (const __FlashStringHelper *) testData );
+
+  // allocate memory for the compressed data
+  uint8_t compressedData[BUFFER_SIZE];
+
+  // compress the test data
+  Serial.print(F("Compressing data... "));
+  uint16_t compressedSize = uCompression::pgm_RLEcompress( testData,         // pointer to original data
+                                                           uncompressedSize, // original size
+                                                           compressedData ); // pointer to result buffer (compressed data)
+
+  // print the compressed size
+  Serial.print(F("size of compressed data is ")); Serial.print( compressedSize ); Serial.println(F(" bytes"));
+
+  // allocate buffer for decompressed data (and fill it with '0' to ensure the test data is zero terminated)
+  uint8_t uncompressedData[BUFFER_SIZE];
+  memset( uncompressedData, 0, sizeof( uncompressedData ) );
+  // uncompress the data 
+  uCompression::RLEdecompress( compressedData,     // pointer to the compressed data
+                               uncompressedData,   // pointer to result buffer (decompressed data)
+                               uncompressedSize ); // original size
+
+  // and print the decompressed data for referrence
+  Serial.println(F("\nDecompressed data"));
+  Serial.print( (const char *) uncompressedData );
+
+  // compare decompressed data to original data
+  if ( memcmp_P( uncompressedData, testData, uncompressedSize ) == 0 )
+  {
+    Serial.println(F("The data has been decompressed correctly!"));
+  }
+  else
+  {
+    Serial.println(F("*** The decompressed data is different from the original data! ***"));
+  }
+
+  while ( true );
+}

keywords.txt

@@ -0,0 +1,43 @@
+#######################################
+
+# Syntax Coloring Map For uCompression
+
+####################################### 
+
+# Class (KEYWORD1)
+
+#######################################
+
+
+
+uCompression	KEYWORD1
+
+
+
+#######################################
+
+# Methods and Functions (KEYWORD2)
+
+#######################################	
+
+
+RLEcompress	KEYWORD2
+
+pgm_RLEcompress	KEYWORD2
+clearBuffer	KEYWORD2
+RLEdecompress	KEYWORD2
+RLEdecompress256	KEYWORD2
+pgm_RLEdecompress	KEYWORD2
+pgm_RLEdecompress256	KEYWORD2
+
+
+#######################################
+# Constants (LITERAL1)
+#######################################
+ 
+
+RLE_UNCOMPRESSED_DATA	LITERAL1
+RLE_COMPRESSED_0xFF_DATA	LITERAL1
+RLE_COMPRESSED_0x00_DATA	LITERAL1
+RLE_COMPRESSED_DATA	LITERAL1
+RLE_COMPRESSION_MASK	LITERAL1

library.properties

@@ -0,0 +1,10 @@
+name=uCompression
+version=0.1
+author=Lorandil
+maintainer=Lorandil (Lorandil@gmx.de)
+sentence=Simple compression/decompression library.
+paragraph=uCompression was designed to compress simple monochrome image data as it is usually used on displays like SSD1306.
+category=Data Processing
+url=https://github.com/Lorandil/uCompression
+architectures=*
+depends=

uCompression.cpp

@@ -3,8 +3,7 @@
 /*--------------------------------------------------------------*/
 uint16_t uCompression::RLEcompress( const uint8_t *uncompressedData,
                                     uint16_t uncompressedByteCount,
-                                    uint8_t *compressedData,
-                                    uint16_t compressedBufferSize )
+                                    uint8_t *compressedData )
 {
   uint16_t compressedByteCount = 0;
 
@@ -98,8 +97,7 @@ uint16_t uCompression::RLEcompress( const uint8_t *uncompressedData,
 /*--------------------------------------------------------------*/
 uint16_t uCompression::pgm_RLEcompress( const uint8_t *uncompressedData,
                                         uint16_t uncompressedByteCount,
-                                        uint8_t *compressedData,
-                                        uint16_t compressedBufferSize )
+                                        uint8_t *compressedData )
 {
   uint16_t compressedByteCount = 0;
 

uCompression.h

@@ -26,9 +26,9 @@ class uCompression
 public:
   uCompression() = default;
   static uint16_t RLEcompress( const uint8_t *uncompressedData, uint16_t uncompressedByteCount,
-                               uint8_t *compressedData, uint16_t compressedBufferSize );
+                               uint8_t *compressedData );
   static uint16_t pgm_RLEcompress( const uint8_t *uncompressedData, uint16_t uncompressedByteCount,
-                                   uint8_t *compressedData, uint16_t compressedBufferSize );
+                                   uint8_t *compressedData );
   static const uint8_t *RLEdecompress( const uint8_t *compressedData, 
                                        uint8_t *uncompressedData, uint16_t uncompressedByteCount );
   static const uint8_t *RLEdecompress256( const uint8_t *compressedData,