DESCRIPTION
-----------
This archive contains simple and readable ANSI C implementations of
run length encoding and decoding (RLE).  It includes two implementations, a
conventional implementation and a variant of the packbits method.  These
implementations are not intended to be the best, fastest, smallest, or any
other performance related adjective.

The conventional version of encoding provides a run length for runs of two
or more symbols.  If the encoded file contains a run of two or more symbols,
the run will be encoded as two identical symbols followed by a byte with the
length of the rest of the run.  This method incurs a one byte penalty for
every two byte run.

The packbit variant will encode data as blocks of symbols.  Each block starts
with a one byte count.  If the count is non-negative, count + 1 symbols are
copied verbatim.  If the count is negative, the symbol that follows occurs
in a run 2 - count long.  This method incurs a one byte penalty for every
block of up symbols that is not a run.

More information on run length encoding may be found at:
https://michaeldipperstein.github.io/rle.html

FILES
-----
COPYING         - Rules for copying and distributing GPL software
COPYING.LESSER  - Rules for copying and distributing LGPL software
Makefile        - makefile for this project (assumes gcc compiler and GNU make)
README          - this file
rle.c           - Library of run length encoding and decoding routines.
rle.h           - Header containing prototypes for library functions.
sample.c        - Demonstration of how to use run length encoding library
                  functions
vpackbits.c     - Implementation of a variant of the packbits encoding and
                  decoding algorithm
optlist/        - Submodule containing optlist command line option parser
                  library

BUILDING
--------
To build these files with GNU make and gcc, simply enter "make" from the
command line.  The executable will be named sample (or sample.exe).

USAGE
-----
Usage: sample <options>

options:
  -c : Encode input file to output file.
  -d : Decode input file to output file.
  -v : Use variant of packbits algorithm.
  -i <filename> : Name of input file.
  -o <filename> : Name of output file.
  -h | ?  : Print out command line options.

-c      Compress the specified input file (see -i) then using run length
        encoding, writing the encoded results to the specified output file
        (see -o).

-d      Decompresses the specified input file (see -i) writing the results to
        the specified output file (see -o).  Only files compressed by this
        program may be decompressed.

-v      Compress/Decompress using a packbit variant.  Yields better compression
        in some instances.

-i <filename>   The name of the input file.  There is no valid usage of this
                program without a specified input file.

-o <filename>   The name of the output file.  If no file is specified, stdout
                will be used.  NOTE: Sending compressed output to stdout may
                produce undesirable results.

LIBRARY API
-----------
Encoding Data (Traditional or Packbits Variant):
int RleEncodeFile(FILE *inFile, FILE *outFile);
int VPackBitsEncodeFile(FILE *inFile, FILE *outFile);
inFile
    The file stream to be encoded. It must be opened.  NULL pointers will
    return an error.
outFile
    The file stream receiving the encoded results.  It must be opened.  NULL
    pointers will return an error.
Return Value
    Zero for success, -1 for failure.  Error type is contained in errno.  Files
    will remain open.

Decoding Data (Traditional or Packbits Variant):
int RleDecodeFile(FILE *inFile, FILE *outFile);
int VPackBitsDecodeFile(FILE *inFile, FILE *outFile);
inFile
    The file stream to be decoded.  It must be opened.  NULL pointers will
    return an error.
outFile
    The file stream receiving the decoded results.  It must be opened.  NULL
    pointers will return an error.
Return Value
    Zero for success, -1 for failure.  Error type is contained in errno.  Files
    will remain open.

HISTORY
-------
04/30/04  - Initial Release
09/08/06  - Added packbits variant
08/30/07  - Explicitly licensed under LGPL version 3.
          - Replaces getopt() with optlist library.
          - Corrects bug in packbits style compression that occurs with
            maximum length runs.
07/19/15  - Changed the API so that encode and decode routines accept opened
            file streams instead of file names.
          - Changed return value to 0 for success and -1 for failure with
            reason in errno.
          - Upgraded to latest oplist and bitfile libraries.
          - Tighter adherence to Michael Barr's "Top 10 Bug-Killing Coding
07/16/17  - Changes for cleaner use with GitHub

TODO
----
- Add an option to vary the size of the symbol being encoded.

AUTHOR
------
Michael Dipperstein (mdipperstein@gmail.com)
https://michaeldipperstein.github.io/index.html