If the decompression stream was terminated with a 1 bit at exactly the
byte boundary (perhaps due to decompressing from flash memory and
sinking erased 0xFF bytes until the end of a flash page), it could end
up in a state where heatshrink_decoder_finish() would return
HSDR_FINISH_MORE, but calling heatshrink_decoder_poll would always yield
0 bytes of output. If _both_ results were not checked, this could lead to
the code driving them uselessly calling them in a loop.

Added regression test case:
decoder_should_not_get_stuck_with_finish_yielding_MORE_but_0_bytes_output_from_poll

Resolved by explicitly checking remaining input length in
heatshrink_decoder_finish in the HSDS_YIELD_LITERAL state, since it is
not safe to assume that the decompression stream input will be padded
with 0 bits.

Only check for matches that can be improvements.

Only test whether len is > match_maxlen when at least the first byte
matches, and use a pointer to curry in the current offset, saving an
add per compare.

This eliminates more unnecessary compares, speeding things up further.

(Thanks to user jibsen on hacker news for the original suggestion.)

Also, update index type to int16_t.

Eliminate some unnecessary comparisons by making the position in the
index signed, and treating any negative value as not found, not just
((uint16_t)-1). Also, decrease HEATSHRINK_MAX_WINDOW_BITS to 15, so
index values with the highest bit set can be used as working space
for index optimization on the fly (some day).

Use 'if length >= 3' instead of 'length > 2' for the break even point,
sinec it makes the intent clearer, and pull the comparison outside of
the inner loop.

Increase HEATSHRINK_MIN_LOOKAHEAD_BITS to 2, since -l 1 won't compress.
Also, eliminate the corresponding MAX #define, since it has to be <= the
window size anyway.

Use a separate *pt == *pt2 instead of pt[0] == pt2[0] for comparison of the
leading byte, which should allow for better branch prediction.

Eliminate 'needle_index' in the inner loop -- it's only aliasing 'end'.

Also, add comments about the indexing strategy.

This can save a significant amount of time in push_bits, particularly if -w is 8.

1. Instead of storing an offset to the previous matching byte in the
   index, store the next matching byte bigram. Since the compression
   doesn't break even unless at least 3 bytes match, any single-byte
   matches in the index should just be skipped.

   Since this eliminates these false positives in one pass, it also
   removes work that would otherwise be done during every walk of the
   index's offset chain - possibly several times. This greatly
   reduces the time spent in find_longest_match().

   EDIT: This prematurely discards information from the index,
   damaging the overall compression effectiveness. Some of the
   links being skipped are still necessary for other chains, so
   they cannot be eliminated this way. It's still possible dynamic
   programming can be used for this, but the strategy in this
   commit doesn't quite work.

2. Eliminate the test of the first byte, since indexing already
   incorporates this comparison ahead of time.

*comment on rebase*

Since heatshrink.c is just the command-line interface,
but heatshrink.h is constants common to the encoder and decoder,
rename it to heatshrink_common.h to avoid confusion.

The "Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution."
clause of the BSD license seems to be problematic manufacturers that
do not otherwise provide written documentation for hardware.

There seems to be diminishing returns after 32 bytes, and it takes
significantly less space. (It's only a default, anyway.)

This eliminates the possibility of infinite loops caused by counters
overflowing and preventing the output buffer full or input exhausted
conditions from being reached.

Previously, suspending between the two bytes of a >8-bit index or count
could lead to accumulation of an incorrect value. This commit breaks
each of the index and count states into X_{msb,lsb}, where _msb reads
the >8th bits and stores them in the accumulator, and _lsb reads the
lower 8 bits (or all of them, if the total value is < 8). This adds
another point where the state machine can suspend and resume without any
loss of information, if necessary.

Since they're only stored as `uint16_t`s, disallow overly large sizes.

Added summary of key features and some formatting