DESCRIPTION
-----------
This archive contains a simple and readable ANSI C implementation of
Rice coding (Golomb-Rice coding) and decoding.  This implementation is not
intended to be the best, fastest, smallest, or any other performance related
adjective.

More information on rice encoding may be found at:
https://michaeldipperstein.github.io/rice.html
http://en.wikipedia.org/wiki/Golomb_coding

FILES
-----
COPYING         - Rules for copying and distributing GPL software
COPYING.LESSER  - Rules for copying and distributing LGPL software
rice.c          - Source for rice library encoding and decoding routines.
rice.h          - Header containing prototypes for rice library functions.
Makefile        - makefile for this project (assumes gcc compiler and GNU make)
README          - this file
sample.c        - Demonstration of how to use the rice library functions
optlist/        - Submodule containing optlist command line option parser
                  library
bitfile/        - Submodule containing bitfile bitwise file 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).

GIT NOTE: Updates to subtrees optlist and bitfile don't get pulled by "git pull"
Use the following commands to pull their updates:
git subtree pull --prefix optlist https://github.com/MichaelDipperstein/optlist.git master --squash
git subtree pull --prefix bitfile https://github.com/MichaelDipperstein/bitfile.git master --squash

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

options:
  -c : Encode input file to output file.
  -d : Decode input file to output file.
  -k [1-7] : Length of binary portion.
  -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) using the Golomb-Rice
        encoding algorithm.  Results are written to the specified output file
        (see -o).

-d      Decompress the specified input file (see -i) using the Golomb-Rice
        decoding algorithm.  Results are written to the specified output file
        (see -o).  Only files compressed by this program may be decompressed.

-k [1-7]        The number of bits in the binary portion of a Rice encoded
                value.

-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:
int RiceEncodeFile(FILE *inFile, FILE *outFile, const unsigned char k)
inFile
    The file stream to be encoded.  It must 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.
k
    The length of binary portion of encoded word
Return Value
    Zero for success, -1 for failure.  Error type is contained in errno.  Files
    will remain open.

Decoding Data:
int RiceDecodeFile(FILE *inFile, FILE *outFile, const unsigned char k)
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.
k
    The length of binary portion of encoded word
Return Value
    Zero for success, -1 for failure.  Error type is contained in errno.  Files
    will remain open.

HISTORY
-------
01/23/08  - Initial Release
05/22/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
----
- Allow unenoded data sizes other than 8 bits.

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