### Heatshrink Command-Line Interface

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Examples of using the heatshrink command-line tool for compression and decompression with various options.

```APIDOC
## Heatshrink Command-Line Interface

The heatshrink command-line tool compresses and decompresses files or streams using LZSS algorithm with configurable window and lookahead sizes.

### Examples

*   **Compress a file with default settings:**
    ```bash
    heatshrink -e input.txt output.hs
    ```

*   **Decompress a file:**
    ```bash
    heatshrink -d output.hs restored.txt
    ```

*   **Compress with custom window size (2^8 = 256 bytes) and lookahead (2^4 = 16 bytes):**
    ```bash
    heatshrink -e -w 8 -l 4 input.txt output.hs
    ```

*   **Compress with verbose output showing compression ratio:**
    ```bash
    heatshrink -e -v input.txt output.hs
    # Output: input.txt 45.23 %    1024 -> 560 (-w 11 -l 4)
    ```

*   **Compress from stdin to stdout (useful in pipelines):**
    ```bash
    cat input.txt | heatshrink -e > output.hs
    ```

*   **Decompress from stdin to stdout:**
    ```bash
    cat output.hs | heatshrink -d > restored.txt
    ```

*   **Recommended settings for embedded systems (smaller memory footprint):**
    ```bash
    heatshrink -e -w 8 -l 4 input.txt output.hs
    ```

*   **Recommended settings for general systems (better compression):**
    ```bash
    heatshrink -e -w 10 -l 5 input.txt output.hs
    ```
```

--------------------------------

### C: Full Data Compression and Decompression

Source: https://context7.com/atomicobject/heatshrink/llms.txt

This C code provides a complete example of compressing and decompressing data using the heatshrink library. It includes functions for both compression and decompression, along with a main function to demonstrate their usage and verify the results. Ensure proper allocation of input and output buffers.

```c
#include <stdio.h>
#include <string.h>
#include "heatshrink_encoder.h"
#include "heatshrink_decoder.h"

#define WINDOW_BITS 8
#define LOOKAHEAD_BITS 4

int compress_data(uint8_t *input, size_t input_size,
                  uint8_t *output, size_t output_max, size_t *output_size) {
    heatshrink_encoder *hse = heatshrink_encoder_alloc(WINDOW_BITS, LOOKAHEAD_BITS);
    if (!hse) return -1;

    size_t sunk = 0, polled = 0, total_sunk = 0, total_polled = 0;
    HSE_sink_res sres;
    HSE_poll_res pres;
    HSE_finish_res fres;

    // Sink and poll loop
    while (total_sunk < input_size) {
        sres = heatshrink_encoder_sink(hse, &input[total_sunk],
                                       input_size - total_sunk, &sunk);
        if (sres < 0) { heatshrink_encoder_free(hse); return -1; }
        total_sunk += sunk;

        do {
            pres = heatshrink_encoder_poll(hse, &output[total_polled],
                                           output_max - total_polled, &polled);
            if (pres < 0) { heatshrink_encoder_free(hse); return -1; }
            total_polled += polled;
        } while (pres == HSER_POLL_MORE);
    }

    // Finish and drain remaining output
    do {
        fres = heatshrink_encoder_finish(hse);
        if (fres < 0) { heatshrink_encoder_free(hse); return -1; }

        do {
            pres = heatshrink_encoder_poll(hse, &output[total_polled],
                                           output_max - total_polled, &polled);
            if (pres < 0) { heatshrink_encoder_free(hse); return -1; }
            total_polled += polled;
        } while (pres == HSER_POLL_MORE);
    } while (fres == HSER_FINISH_MORE);

    *output_size = total_polled;
    heatshrink_encoder_free(hse);
    return 0;
}

int decompress_data(uint8_t *input, size_t input_size,
                    uint8_t *output, size_t output_max, size_t *output_size) {
    heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, WINDOW_BITS, LOOKAHEAD_BITS);
    if (!hsd) return -1;

    size_t sunk = 0, polled = 0, total_sunk = 0, total_polled = 0;
    HSD_sink_res sres;
    HSD_poll_res pres;
    HSD_finish_res fres;

    // Sink and poll loop
    while (total_sunk < input_size) {
        sres = heatshrink_decoder_sink(hsd, &input[total_sunk],
                                       input_size - total_sunk, &sunk);
        if (sres < 0) { heatshrink_decoder_free(hsd); return -1; }
        total_sunk += sunk;

        do {
            pres = heatshrink_decoder_poll(hsd, &output[total_polled],
                                           output_max - total_polled, &polled);
            if (pres < 0) { heatshrink_decoder_free(hsd); return -1; }
            total_polled += polled;
        } while (pres == HSDR_POLL_MORE);
    }

    // Finish and drain remaining output
    do {
        fres = heatshrink_decoder_finish(hsd);
        if (fres < 0) { heatshrink_decoder_free(hsd); return -1; }

        do {
            pres = heatshrink_decoder_poll(hsd, &output[total_polled],
                                           output_max - total_polled, &polled);
            if (pres < 0) { heatshrink_decoder_free(hsd); return -1; }
            total_polled += polled;
        } while (pres == HSDR_POLL_MORE);
    } while (fres == HSDR_FINISH_MORE);

    *output_size = total_polled;
    heatshrink_decoder_free(hsd);
    return 0;
}

int main(void) {
    uint8_t original[] = "The quick brown fox jumps over the lazy dog. "
                         "The quick brown fox jumps over the lazy dog. "
                         "The quick brown fox jumps over the lazy dog.";
    size_t original_size = sizeof(original) - 1;

    uint8_t compressed[1024];
    uint8_t decompressed[1024];
    size_t compressed_size, decompressed_size;

    // Compress
    if (compress_data(original, original_size, compressed, sizeof(compressed),
                      &compressed_size) != 0) {
        fprintf(stderr, "Compression failed\n");
        return 1;
    }
    printf("Compressed: %zu -> %zu bytes (%.1f%% reduction)\n",
           original_size, compressed_size,
           100.0 * (1.0 - (double)compressed_size / original_size));

    // Decompress
    if (decompress_data(compressed, compressed_size, decompressed,
                        sizeof(decompressed), &decompressed_size) != 0) {
        fprintf(stderr, "Decompression failed\n");
        return 1;
    }
    printf("Decompressed: %zu -> %zu bytes\n", compressed_size, decompressed_size);

    // Verify
    if (decompressed_size == original_size &&
        memcmp(original, decompressed, original_size) == 0) {
        printf("Verification: SUCCESS\n");
    } else {
        printf("Verification: FAILED\n");
    }

    return 0;
}

```

--------------------------------

### Initialize and Use Static Compression in C

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Include necessary headers and use statically allocated encoder/decoder structures. Call reset to initialize them before use. This pattern is for streaming data compression in embedded systems.

```c
// Usage with static allocation:
#include "heatshrink_encoder.h"
#include "heatshrink_decoder.h"

// Statically allocate encoder and decoder
static heatshrink_encoder hse;
static heatshrink_decoder hsd;

void init_compression(void) {
    // Reset initializes the statically allocated structures
    heatshrink_encoder_reset(&hse);
    heatshrink_decoder_reset(&hsd);
}

void compress_chunk(uint8_t *data, size_t len) {
    size_t consumed;
    heatshrink_encoder_sink(&hse, data, len, &consumed);
    // ... poll for output
}

```

--------------------------------

### Command-Line Interface Usage

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Compress and decompress files or streams using various window and lookahead configurations.

```bash
# Compress a file with default settings (window=11, lookahead=4)
heatshrink -e input.txt output.hs

# Decompress a file
heatshrink -d output.hs restored.txt

# Compress with custom window size (2^8 = 256 bytes) and lookahead (2^4 = 16 bytes)
heatshrink -e -w 8 -l 4 input.txt output.hs

# Compress with verbose output showing compression ratio
heatshrink -e -v input.txt output.hs
# Output: input.txt 45.23 %    1024 -> 560 (-w 11 -l 4)

# Compress from stdin to stdout (useful in pipelines)
cat input.txt | heatshrink -e > output.hs

# Decompress from stdin to stdout
cat output.hs | heatshrink -d > restored.txt

# Recommended settings for embedded systems (smaller memory footprint)
heatshrink -e -w 8 -l 4 input.txt output.hs

# Recommended settings for general systems (better compression)
heatshrink -e -w 10 -l 5 input.txt output.hs
```

--------------------------------

### Configure Static Allocation in C

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Define HEATSHRINK_DYNAMIC_ALLOC to 0 and set buffer sizes for static allocation in heatshrink_config.h. This is required for embedded systems where dynamic allocation is unavailable.

```c
// heatshrink_config.h - Static allocation configuration

#ifndef HEATSHRINK_CONFIG_H
#define HEATSHRINK_CONFIG_H

// Disable dynamic allocation for embedded use
#define HEATSHRINK_DYNAMIC_ALLOC 0

// Required settings when using static allocation
#define HEATSHRINK_STATIC_INPUT_BUFFER_SIZE 32   // Decoder input buffer
#define HEATSHRINK_STATIC_WINDOW_BITS 8          // 2^8 = 256 byte window
#define HEATSHRINK_STATIC_LOOKAHEAD_BITS 4       // 2^4 = 16 byte lookahead

// Optional: Enable indexing for faster compression (uses more memory)
#define HEATSHRINK_USE_INDEX 1

// Optional: Enable debug logging
#define HEATSHRINK_DEBUGGING_LOGS 0

#endif

```

--------------------------------

### Allocate Encoder State Machine

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Initialize an encoder with specific window and lookahead sizes. Ensure the encoder is freed after use.

```c
#include "heatshrink_encoder.h"

// Allocate encoder with window=256 bytes (2^8), lookahead=16 bytes (2^4)
heatshrink_encoder *hse = heatshrink_encoder_alloc(8, 4);
if (hse == NULL) {
    fprintf(stderr, "Failed to allocate encoder\n");
    return -1;
}

// Valid window_sz2 range: 4-15 (16 bytes to 32KB window)
// Valid lookahead_sz2 range: 3 to (window_sz2 - 1)

// Example: larger window for better compression on desktop systems
heatshrink_encoder *hse_large = heatshrink_encoder_alloc(11, 4);  // 2KB window

// Example: minimal memory for tiny embedded systems
heatshrink_encoder *hse_tiny = heatshrink_encoder_alloc(4, 3);    // 16 byte window

// Always free when done
heatshrink_encoder_free(hse);
```

--------------------------------

### Allocate and Initialize Heatshrink Decoder

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Allocates and initializes a decoder state machine. Parameters must match those used during encoding. The input_buffer_size controls how much compressed data can be buffered internally.

```c
#include "heatshrink_decoder.h"

// Allocate decoder with:
// - 256 byte input buffer
// - window size matching encoder (2^8 = 256 bytes)
// - lookahead size matching encoder (2^4 = 16 bytes)
heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, 8, 4);
if (hsd == NULL) {
    fprintf(stderr, "Failed to allocate decoder\n");
    return -1;
}

// For minimal memory embedded systems
heatshrink_decoder *hsd_tiny = heatshrink_decoder_alloc(32, 4, 3);

// For desktop systems with more memory
heatshrink_decoder *hsd_large = heatshrink_decoder_alloc(512, 11, 4);

// Important: window and lookahead must match encoder settings!
// Mismatched settings will produce corrupted output

heatshrink_decoder_free(hsd);

```

--------------------------------

### heatshrink_encoder_alloc

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Allocates and initializes a new encoder state machine with specified window and lookahead sizes.

```APIDOC
## heatshrink_encoder_alloc

Allocates and initializes a new encoder state machine with specified window and lookahead sizes. The window size determines how far back in the input the encoder searches for repeated patterns (2^window_sz2 bytes), while lookahead size determines maximum match length (2^lookahead_sz2 bytes). Returns NULL if parameters are invalid.

### Parameters

*   **window_sz2** (uint8_t) - Required - The exponent for the window size (e.g., 8 for 2^8 = 256 bytes). Valid range: 4-15.
*   **lookahead_sz2** (uint8_t) - Required - The exponent for the lookahead size (e.g., 4 for 2^4 = 16 bytes). Valid range: 3 to (window_sz2 - 1).

### Returns

*   `heatshrink_encoder *` - A pointer to the allocated encoder state machine, or NULL if parameters are invalid.

### Request Example (C)

```c
#include "heatshrink_encoder.h"

// Allocate encoder with window=256 bytes (2^8), lookahead=16 bytes (2^4)
heatshrink_encoder *hse = heatshrink_encoder_alloc(8, 4);
if (hse == NULL) {
    fprintf(stderr, "Failed to allocate encoder\n");
    return -1;
}

// Example: larger window for better compression on desktop systems
heatshrink_encoder *hse_large = heatshrink_encoder_alloc(11, 4);  // 2KB window

// Example: minimal memory for tiny embedded systems
heatshrink_encoder *hse_tiny = heatshrink_encoder_alloc(4, 3);    // 16 byte window

// Always free when done
heatshrink_encoder_free(hse);
```
```

--------------------------------

### heatshrink_decoder_alloc

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Allocates and initializes a decoder state machine. Parameters must match those used during encoding. The input_buffer_size controls how much compressed data can be buffered internally; larger values improve throughput but use more memory.

```APIDOC
## heatshrink_decoder_alloc

### Description
Allocates and initializes a decoder state machine. Parameters must match those used during encoding. The input_buffer_size controls how much compressed data can be buffered internally; larger values improve throughput but use more memory.

### Method
(Not specified, likely internal C function)

### Endpoint
(Not applicable, C function)

### Parameters
- **input_buffer_size** (size_t) - The size of the internal buffer for compressed data.
- **window_sz2** (uint8_t) - The base-2 logarithm of the dictionary window size. Must match the encoder's window size.
- **lookahead_sz2** (uint8_t) - The base-2 logarithm of the lookahead buffer size. Must match the encoder's lookahead size.

### Request Example
```c
#include "heatshrink_decoder.h"

// Allocate decoder with: 256 byte input buffer, 256 byte window, 16 byte lookahead
heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, 8, 4);
if (hsd == NULL) {
    fprintf(stderr, "Failed to allocate decoder\n");
    // Handle error
}

// Example for minimal memory systems
heatshrink_decoder *hsd_tiny = heatshrink_decoder_alloc(32, 4, 3);

// Example for systems with more memory
heatshrink_decoder *hsd_large = heatshrink_decoder_alloc(512, 11, 4);

// Important: window and lookahead must match encoder settings!
// Mismatched settings will produce corrupted output

heatshrink_decoder_free(hsd);
```

### Response
#### Success Response (heatshrink_decoder*)
- A pointer to the newly allocated and initialized `heatshrink_decoder` state machine.

#### Error Response
- **NULL**: If allocation fails.

#### Response Example
(See C code example in source)
```

--------------------------------

### Poll Encoder for Compressed Output

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Polls the encoder for compressed output data. Must be called repeatedly until HSER_POLL_EMPTY is returned to ensure all compressed data is retrieved.

```c
#include "heatshrink_encoder.h"

heatshrink_encoder *hse = heatshrink_encoder_alloc(8, 4);
uint8_t input[] = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";  // Highly compressible
uint8_t output[256];
size_t input_consumed = 0;
size_t output_size = 0;
size_t total_output = 0;

// Sink input data
heatshrink_encoder_sink(hse, input, sizeof(input) - 1, &input_consumed);

// Signal end of input
heatshrink_encoder_finish(hse);

// Poll for all compressed output
HSE_poll_res pres;
do {
    pres = heatshrink_encoder_poll(hse,
        &output[total_output],
        sizeof(output) - total_output,
        &output_size);

    if (pres == HSER_POLL_MORE || pres == HSER_POLL_EMPTY) {
        total_output += output_size;
        printf("Polled %zu bytes of compressed data\n", output_size);
    } else if (pres == HSER_POLL_ERROR_NULL) {
        fprintf(stderr, "Error: NULL argument\n");
        break;
    }
} while (pres == HSER_POLL_MORE);

printf("Compression: %zu bytes -> %zu bytes (%.1f%% reduction)\n",
       sizeof(input) - 1, total_output,
       100.0 * (1.0 - (double)total_output / (sizeof(input) - 1)));

heatshrink_encoder_free(hse);

```

--------------------------------

### Reset Encoder to Initial State

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Resets an encoder to its initial state, allowing reuse without reallocation. Useful for compressing multiple independent data streams with the same configuration.

```c
#include "heatshrink_encoder.h"

heatshrink_encoder *hse = heatshrink_encoder_alloc(8, 4);
uint8_t output[1024];
size_t consumed, output_size;

// Compress first message
uint8_t msg1[] = "First message to compress";
heatshrink_encoder_sink(hse, msg1, sizeof(msg1) - 1, &consumed);
heatshrink_encoder_finish(hse);
while (heatshrink_encoder_poll(hse, output, sizeof(output), &output_size) == HSER_POLL_MORE);
printf("Compressed message 1\n");

// Reset for next message (no reallocation needed)
heatshrink_encoder_reset(hse);

// Compress second message
uint8_t msg2[] = "Second message to compress";
heatshrink_encoder_sink(hse, msg2, sizeof(msg2) - 1, &consumed);
heatshrink_encoder_finish(hse);
while (heatshrink_encoder_poll(hse, output, sizeof(output), &output_size) == HSER_POLL_MORE);
printf("Compressed message 2\n");

heatshrink_encoder_free(hse);

```

--------------------------------

### Sink Data into Encoder

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Feed input data into the encoder buffer incrementally. Handle potential API misuse errors by polling for output when necessary.

```c
#include "heatshrink_encoder.h"

heatshrink_encoder *hse = heatshrink_encoder_alloc(8, 4);
uint8_t input[] = "The quick brown fox jumps over the lazy dog. "
                  "The quick brown fox jumps over the lazy dog.";
size_t input_size = sizeof(input) - 1;
size_t bytes_sunk = 0;
size_t total_sunk = 0;

// Sink all input data (may require multiple calls if buffer fills)
while (total_sunk < input_size) {
    HSE_sink_res sres = heatshrink_encoder_sink(hse,
        &input[total_sunk],
        input_size - total_sunk,
        &bytes_sunk);

    if (sres == HSER_SINK_OK) {
        total_sunk += bytes_sunk;
        printf("Sunk %zu bytes (total: %zu/%zu)\n", bytes_sunk, total_sunk, input_size);
    } else if (sres == HSER_SINK_ERROR_NULL) {
        fprintf(stderr, "Error: NULL argument\n");
        break;
    } else if (sres == HSER_SINK_ERROR_MISUSE) {
        fprintf(stderr, "Error: API misuse (call poll first)\n");
        // Need to poll for output before sinking more data
        break;
    }
}

heatshrink_encoder_free(hse);
```

--------------------------------

### Sink Compressed Data into Decoder

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Use `heatshrink_decoder_sink` to feed compressed data into the decoder's buffer. It returns `HSDR_SINK_FULL` if the buffer is full, requiring a `poll()` call to make space. Ensure proper error handling for `HSDR_SINK_ERROR_NULL`.

```c
#include "heatshrink_decoder.h"

heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, 8, 4);
uint8_t compressed_data[] = { 0xb0, 0x80, 0x01, 0x80 };  // Compressed "aaaaa"
size_t compressed_size = sizeof(compressed_data);
size_t bytes_sunk = 0;
size_t total_sunk = 0;

// Sink all compressed data
while (total_sunk < compressed_size) {
    HSD_sink_res sres = heatshrink_decoder_sink(hsd,
        &compressed_data[total_sunk],
        compressed_size - total_sunk,
        &bytes_sunk);

    if (sres == HSDR_SINK_OK) {
        total_sunk += bytes_sunk;
        printf("Sunk %zu compressed bytes\n", bytes_sunk);
    } else if (sres == HSDR_SINK_FULL) {
        printf("Decoder buffer full, need to poll\n");
        // Must poll for output before sinking more
        break;
    } else if (sres == HSDR_SINK_ERROR_NULL) {
        fprintf(stderr, "Error: NULL argument\n");
        break;
    }
}

heatshrink_decoder_free(hsd);
```

--------------------------------

### heatshrink_encoder_finish

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Notifies the encoder that no more input will be provided, triggering it to flush any remaining data. Must be called after all input has been sunk. Continue calling poll() while this returns HSER_FINISH_MORE to retrieve all output.

```APIDOC
## heatshrink_encoder_finish

### Description
Notifies the encoder that no more input will be provided, triggering it to flush any remaining data. Must be called after all input has been sunk. Continue calling poll() while this returns HSER_FINISH_MORE to retrieve all output.

### Method
(Not specified, likely internal C function)

### Endpoint
(Not applicable, C function)

### Parameters
(Not specified in detail for this function signature, but inferred from usage)
- **hse** (heatshrink_encoder*) - Pointer to the encoder state.

### Request Example
(See C code example in source)

### Response
#### Success Response (HSE_finish_res)
- **HSER_FINISH_MORE**: More output data is available and needs to be polled.
- **HSER_FINISH_DONE**: All data has been flushed and encoding is complete.

#### Error Response (HSE_finish_res)
- **HSER_FINISH_ERROR_NULL**: A NULL encoder was provided.

#### Response Example
(See C code example in source)
```

--------------------------------

### Signal End of Compressed Input

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Use `heatshrink_decoder_finish` to indicate that no more compressed data will be provided. Subsequently, call `poll()` to retrieve any remaining decompressed output until `finish()` returns `HSDR_FINISH_DONE`.

```c
#include "heatshrink_decoder.h"

heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, 8, 4);
uint8_t compressed[] = { 0xb0, 0x80, 0x01, 0x80 };
uint8_t output[256];
size_t sunk = 0, output_size = 0;

heatshrink_decoder_sink(hsd, compressed, sizeof(compressed), &sunk);

// Signal end of compressed input
HSD_finish_res fres = heatshrink_decoder_finish(hsd);

// Drain all remaining decompressed output
while (fres == HSDR_FINISH_MORE) {
    HSD_poll_res pres = heatshrink_decoder_poll(hsd, output, sizeof(output), &output_size);
    printf("Polled %zu decompressed bytes\n", output_size);

    if (pres == HSDR_POLL_EMPTY) {
        fres = heatshrink_decoder_finish(hsd);
    }
}

if (fres == HSDR_FINISH_DONE) {
    printf("Decoding complete\n");
}

heatshrink_decoder_free(hsd);
```

--------------------------------

### heatshrink_encoder_sink

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Sinks input data into the encoder's internal buffer for compression.

```APIDOC
## heatshrink_encoder_sink

Sinks input data into the encoder's internal buffer for compression. The function accepts up to as many bytes as will fit in the buffer and reports how many bytes were actually consumed. Call repeatedly until all input data has been processed.

### Parameters

*   **hse** (`heatshrink_encoder *`) - Required - Pointer to the encoder state machine.
*   **input** (`uint8_t *`) - Required - Pointer to the input data buffer.
*   **len** (`size_t`) - Required - The number of bytes to sink from the input buffer.
*   **bytes_sunk** (`size_t *`) - Required - Pointer to a variable that will store the number of bytes actually consumed by the encoder.

### Returns

*   `HSE_sink_res` - An enum indicating the result of the operation:
    *   `HSER_SINK_OK`: Operation successful.
    *   `HSER_SINK_ERROR_NULL`: A NULL argument was provided.
    *   `HSER_SINK_ERROR_MISUSE`: API misuse (e.g., calling sink before poll when buffer is full).

### Request Example (C)

```c
#include "heatshrink_encoder.h"

heatshrink_encoder *hse = heatshrink_encoder_alloc(8, 4);
uint8_t input[] = "The quick brown fox jumps over the lazy dog. "
                  "The quick brown fox jumps over the lazy dog.";
size_t input_size = sizeof(input) - 1;
size_t bytes_sunk = 0;
size_t total_sunk = 0;

// Sink all input data (may require multiple calls if buffer fills)
while (total_sunk < input_size) {
    HSE_sink_res sres = heatshrink_encoder_sink(hse,
        &input[total_sunk],
        input_size - total_sunk,
        &bytes_sunk);

    if (sres == HSER_SINK_OK) {
        total_sunk += bytes_sunk;
        printf("Sunk %zu bytes (total: %zu/%zu)\n", bytes_sunk, total_sunk, input_size);
    } else if (sres == HSER_SINK_ERROR_NULL) {
        fprintf(stderr, "Error: NULL argument\n");
        break;
    } else if (sres == HSER_SINK_ERROR_MISUSE) {
        fprintf(stderr, "Error: API misuse (call poll first)\n");
        // Need to poll for output before sinking more data
        break;
    }
}

heatshrink_encoder_free(hse);
```
```

--------------------------------

### Poll for Decompressed Output

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Retrieve decompressed data using `heatshrink_decoder_poll`. Call this function repeatedly as long as it returns `HSDR_POLL_MORE` or `HSDR_POLL_EMPTY`. Handle potential errors like `HSDR_POLL_ERROR_NULL` and `HSDR_POLL_ERROR_UNKNOWN`.

```c
#include "heatshrink_decoder.h"

heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, 8, 4);
uint8_t compressed[] = { 0xb0, 0x80, 0x01, 0x80 };  // Compressed "aaaaa"
uint8_t output[256];
size_t sunk = 0, output_size = 0;
size_t total_output = 0;

// Sink compressed data
heatshrink_decoder_sink(hsd, compressed, sizeof(compressed), &sunk);

// Signal end of compressed stream
heatshrink_decoder_finish(hsd);

// Poll for all decompressed output
HSD_poll_res pres;
do {
    pres = heatshrink_decoder_poll(hsd,
        &output[total_output],
        sizeof(output) - total_output,
        &output_size);

    if (pres == HSDR_POLL_MORE || pres == HSDR_POLL_EMPTY) {
        total_output += output_size;
    } else if (pres == HSDR_POLL_ERROR_NULL) {
        fprintf(stderr, "Error: NULL argument\n");
        break;
    } else if (pres == HSDR_POLL_ERROR_UNKNOWN) {
        fprintf(stderr, "Error: Unknown decoding error\n");
        break;
    }
} while (pres == HSDR_POLL_MORE);

output[total_output] = '\0';
printf("Decompressed: '%s' (%zu bytes)\n", output, total_output);

heatshrink_decoder_free(hsd);
```

--------------------------------

### heatshrink_encoder_reset

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Resets an encoder to its initial state, allowing reuse without reallocation. Useful for compressing multiple independent data streams with the same configuration.

```APIDOC
## heatshrink_encoder_reset

### Description
Resets an encoder to its initial state, allowing reuse without reallocation. Useful for compressing multiple independent data streams with the same configuration.

### Method
(Not specified, likely internal C function)

### Endpoint
(Not applicable, C function)

### Parameters
(Not specified in detail for this function signature, but inferred from usage)
- **hse** (heatshrink_encoder*) - Pointer to the encoder state to reset.

### Request Example
(See C code example in source)

### Response
(No explicit return value mentioned, likely void or status code)

### Response Example
(See C code example in source)
```

--------------------------------

### heatshrink_decoder_sink

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Sinks compressed data into the decoder's internal buffer for decompression. Returns HSDR_SINK_FULL if the internal buffer is full, requiring poll() to be called to make room.

```APIDOC
## heatshrink_decoder_sink

### Description
Sinks compressed data into the decoder's internal buffer for decompression. Returns HSDR_SINK_FULL if the internal buffer is full, requiring poll() to be called to make room.

### Method
(Implicitly a function call, not an HTTP method)

### Parameters
- **hsd** (*heatshrink_decoder* *) - Required - Pointer to the decoder state.
- **compressed_data** (*const uint8_t * *) - Required - Pointer to the compressed data buffer.
- **compressed_size** (*size_t*) - Required - The number of bytes available in the compressed data buffer.
- **bytes_sunk** (*size_t* *) - Output - The number of bytes actually sunk into the decoder buffer.

### Return Value
- **HSDR_sink_res** - An enum indicating the result of the sink operation:
  - **HSDR_SINK_OK**: Data was successfully sunk.
  - **HSDR_SINK_FULL**: The decoder's internal buffer is full. Call `heatshrink_decoder_poll` to make space.
  - **HSDR_SINK_ERROR_NULL**: A NULL argument was provided.

### Example
```c
#include "heatshrink_decoder.h"

heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, 8, 4);
uint8_t compressed_data[] = { 0xb0, 0x80, 0x01, 0x80 };  // Compressed "aaaaa"
size_t compressed_size = sizeof(compressed_data);
size_t bytes_sunk = 0;
size_t total_sunk = 0;

// Sink all compressed data
while (total_sunk < compressed_size) {
    HSD_sink_res sres = heatshrink_decoder_sink(hsd,
        &compressed_data[total_sunk],
        compressed_size - total_sunk,
        &bytes_sunk);

    if (sres == HSDR_SINK_OK) {
        total_sunk += bytes_sunk;
        printf("Sunk %zu compressed bytes\n", bytes_sunk);
    } else if (sres == HSDR_SINK_FULL) {
        printf("Decoder buffer full, need to poll\n");
        // Must poll for output before sinking more
        break;
    } else if (sres == HSDR_SINK_ERROR_NULL) {
        fprintf(stderr, "Error: NULL argument\n");
        break;
    }
}

heatshrink_decoder_free(hsd);
```
```

--------------------------------

### heatshrink_encoder_poll

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Polls the encoder for compressed output data. This function must be called repeatedly until HSER_POLL_EMPTY is returned to ensure all compressed data is retrieved.

```APIDOC
## heatshrink_encoder_poll

### Description
Polls the encoder for compressed output data, copying available bytes into the provided output buffer. Returns status indicating whether more output is available. Must be called repeatedly until HSER_POLL_EMPTY is returned to ensure all compressed data is retrieved.

### Method
(Not specified, likely internal C function)

### Endpoint
(Not applicable, C function)

### Parameters
(Not specified in detail for this function signature, but inferred from usage)
- **output_buffer** (uint8_t*) - Buffer to copy compressed data into.
- **output_buffer_size** (size_t) - Maximum number of bytes to copy into the output buffer.
- **output_size** (size_t*) - Pointer to a size_t variable that will be updated with the number of bytes copied into the output buffer.

### Request Example
(See C code example in source)

### Response
#### Success Response (HSER_POLL_RES)
- **HSER_POLL_MORE**: More compressed data is available.
- **HSER_POLL_EMPTY**: No more compressed data is available.
- **HSER_POLL_DONE**: Encoding is complete (should not be returned by poll).

#### Error Response (HSER_POLL_RES)
- **HSER_POLL_ERROR_NULL**: A NULL argument was provided.

#### Response Example
(See C code example in source)
```

--------------------------------

### heatshrink_decoder_finish

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Notifies the decoder that no more compressed input will be provided. Call poll() while this returns HSDR_FINISH_MORE to retrieve remaining decompressed data.

```APIDOC
## heatshrink_decoder_finish

### Description
Notifies the decoder that no more compressed input will be provided. Call poll() while this returns HSDR_FINISH_MORE to retrieve remaining decompressed data.

### Method
(Implicitly a function call, not an HTTP method)

### Parameters
- **hsd** (*heatshrink_decoder* *) - Required - Pointer to the decoder state.

### Return Value
- **HSD_finish_res** - An enum indicating the result of the finish operation:
  - **HSDR_FINISH_MORE**: More decompressed data is available. Call `heatshrink_decoder_poll` to retrieve it.
  - **HSDR_FINISH_DONE**: All compressed input has been processed and all decompressed data has been output.

### Example
```c
#include "heatshrink_decoder.h"

heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, 8, 4);
uint8_t compressed[] = { 0xb0, 0x80, 0x01, 0x80 };
uint8_t output[256];
size_t sunk = 0, output_size = 0;

heatshrink_decoder_sink(hsd, compressed, sizeof(compressed), &sunk);

// Signal end of compressed input
HSD_finish_res fres = heatshrink_decoder_finish(hsd);

// Drain all remaining decompressed output
while (fres == HSDR_FINISH_MORE) {
    HSD_poll_res pres = heatshrink_decoder_poll(hsd, output, sizeof(output), &output_size);
    printf("Polled %zu decompressed bytes\n", output_size);

    if (pres == HSDR_POLL_EMPTY) {
        fres = heatshrink_decoder_finish(hsd);
    }
}

if (fres == HSDR_FINISH_DONE) {
    printf("Decoding complete\n");
}

heatshrink_decoder_free(hsd);
```
```

--------------------------------

### Notify Encoder of End of Input and Flush Data

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Notifies the encoder that no more input will be provided, triggering it to flush any remaining data. Continue calling poll() while this returns HSER_FINISH_MORE to retrieve all output.

```c
#include "heatshrink_encoder.h"

heatshrink_encoder *hse = heatshrink_encoder_alloc(8, 4);
uint8_t input[] = "Hello, World!";
uint8_t output[256];
size_t consumed = 0, output_size = 0;

// Sink all input
heatshrink_encoder_sink(hse, input, sizeof(input) - 1, &consumed);

// Signal end of input stream
HSE_finish_res fres = heatshrink_encoder_finish(hse);

// Flush all remaining output
while (fres == HSER_FINISH_MORE) {
    HSE_poll_res pres = heatshrink_encoder_poll(hse, output, sizeof(output), &output_size);

    if (pres == HSER_POLL_EMPTY) {
        fres = heatshrink_encoder_finish(hse);
    } else if (pres == HSER_POLL_MORE) {
        // Continue polling
    }
}

if (fres == HSER_FINISH_DONE) {
    printf("Encoding complete\n");
} else if (fres == HSER_FINISH_ERROR_NULL) {
    fprintf(stderr, "Error: NULL encoder\n");
}

heatshrink_encoder_free(hse);

```

--------------------------------

### heatshrink_decoder_poll

Source: https://context7.com/atomicobject/heatshrink/llms.txt

Polls the decoder for decompressed output data. Returns HSDR_POLL_MORE if more output is available (call again), or HSDR_POLL_EMPTY when current input is exhausted.

```APIDOC
## heatshrink_decoder_poll

### Description
Polls the decoder for decompressed output data. Returns HSDR_POLL_MORE if more output is available (call again), or HSDR_POLL_EMPTY when current input is exhausted.

### Method
(Implicitly a function call, not an HTTP method)

### Parameters
- **hsd** (*heatshrink_decoder* *) - Required - Pointer to the decoder state.
- **output_buffer** (*uint8_t * *) - Required - Buffer to store the decompressed output.
- **buffer_size** (*size_t*) - Required - The maximum number of bytes to write to the output buffer.
- **output_size** (*size_t* *) - Output - The number of bytes actually written to the output buffer.

### Return Value
- **HSD_poll_res** - An enum indicating the result of the poll operation:
  - **HSDR_POLL_MORE**: More decompressed data is available. Call `poll` again.
  - **HSDR_POLL_EMPTY**: No more decompressed data is available from the current input.
  - **HSDR_POLL_ERROR_NULL**: A NULL argument was provided.
  - **HSDR_POLL_ERROR_UNKNOWN**: An unknown decoding error occurred.

### Example
```c
#include "heatshrink_decoder.h"

heatshrink_decoder *hsd = heatshrink_decoder_alloc(256, 8, 4);
uint8_t compressed[] = { 0xb0, 0x80, 0x01, 0x80 };  // Compressed "aaaaa"
uint8_t output[256];
size_t sunk = 0, output_size = 0;
size_t total_output = 0;

// Sink compressed data
heatshrink_decoder_sink(hsd, compressed, sizeof(compressed), &sunk);

// Signal end of compressed stream
heatshrink_decoder_finish(hsd);

// Poll for all decompressed output
HSD_poll_res pres;
do {
    pres = heatshrink_decoder_poll(hsd,
        &output[total_output],
        sizeof(output) - total_output,
        &output_size);

    if (pres == HSDR_POLL_MORE || pres == HSDR_POLL_EMPTY) {
        total_output += output_size;
    } else if (pres == HSDR_POLL_ERROR_NULL) {
        fprintf(stderr, "Error: NULL argument\n");
        break;
    } else if (pres == HSDR_POLL_ERROR_UNKNOWN) {
        fprintf(stderr, "Error: Unknown decoding error\n");
        break;
    }
} while (pres == HSDR_POLL_MORE);

output[total_output] = '\0';
printf("Decompressed: '%s' (%zu bytes)\n", output, total_output);

heatshrink_decoder_free(hsd);
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.