microsoft/inflatelib

microsoft/inflatelib

Language: C++

License: MIT

Stars: 11

Forks: 2

Open issues: 2

Created: 2025-03-28T20:56:40Z

Pushed: 2026-06-26T05:26:38Z

Default branch: main

Fork: no

Archived: no

README:

About

InflateLib is a Deflate/Deflate64 decompression library written in C based off dotnet's System.IO.Compression implementation. The API is modeled after that of zlib.

> [!IMPORTANT] > InflateLib is currently considered "prerelease" (version 0.X.Y). > Its API and ABI should not be considered stable while we solicit feedback on its API. > This is expected to last a couple months at most. > In the meantime, please use the issues tab to submit feedback, issues, feature requests, etc.

Links

• [Contributing to InflateLib](./CONTRIBUTING.md)
• [Reporting security issues](./SECURITY.md)
• [Using the library](#usage)
• [Frequently asked questions](#faq)

Usage

Before getting started, you will need to ensure that InflateLib is accessible to your build system. If you are using CMake, you will want to find the inflatelib package and "link" against its target.

find_package(inflatelib REQUIRED)

target_link_libraries(myapp PRIVATE inflatelib::inflatelib)

Using the InflateLib library should be familiar to anyone who has used zlib before. To start, you will need to include the [InflateLib header](src/include/inflatelib.h).

#include

Next, you need to declare an inflatelib_stream variable and initialize it with inflatelib_init. Once you are finished with the stream, you can clean up its resources by calling inflatelib_destroy.

inflatelib_stream stream = { 0 };
if (inflatelib_init(&stream) != INFLATELIB_OK)
{
handle_error(stream.error_msg);
return 1;
}

/* Use the stream */

inflatelib_destroy(&stream);

You can additionally provide your own memory management routines used for allocating and deallocating memory if you desire.

/* Elsewhere in the project/file */
void* my_alloc(void* userData, size_t bytes, size_t alignment);
void my_free(void* userData, void* allocatedPtr, size_t bytes, size_t alignment);

/* Later on */
inflatelib_stream stream = { 0 };
stream.user_data = myAllocator;
stream.alloc = my_alloc;
stream.free = my_free;
if (inflatelib_innit(&stream) != INFLATELIB_OK) /* ... */

> [!TIP] > If you are using something like a monotonic allocator with the inflatelib_stream, it is not strictly necessary that you call inflatelib_destroy when you are done using it. > All memory allocated by inflatelib_stream uses the allocation functions provided to it, making it possible to "blink" its memory out of existence.

At this point, you can begin decompressing data.

int result = INFLATELIB_OK;
char* inputBuffer, *outputBuffer; /* Initialization not shown */
size_t inputSize, outputBufferSize; /* Initialization not shown */

/* Assume the whole input stream is in memory. Otherwise we need to update these values and read new data as necessary
* inside the loop */
stream.next_in = inputBuffer;
stream.avail_in = inputSize;

while (result != INFLATELIB_EOF)
{
stream.next_out = outputBuffer;
stream.avail_out = outputBufferSize;

result = inflatelib_inflate64(&stream);
if (result `](src/include/inflatelib.hpp) for a more "C++ friendly" interface.
When using the C++ interface, you will use the `inflatelib::stream` type in place of `inflatelib_stream`.
The call to `inflatelib_init` is done in the constructor and the call to `inflatelib_destroy` is done in the destructor.
As such, if you wish to provide custom memory management routines, these should be passed to the constructor.
Additionally, if you wish to delay initialization of the stream (e.g. for global variables, etc.), you can construct with `nullptr`.

// Use the default allocation & deallocation functions inflatelib::stream s;

// Use custom allocation & deallocation functions inflatelib::stream s2(myAllocator, &my_alloc, &my_free);

// Delay initialization inflatelib::stream s3(nullptr); s3 = inflatelib::stream(); // s3 is now initialized and can be used to inflate data

The inflation functions are then exposed as member functions off the `inflatelib::stream` type.
These functions take in two references to `std::span` that are used to set the input/output buffers and are updated on function exit to reflect the unused input/output buffer.
For example, the final example from above when everything is put together, becomes:

std::span input; std::span output; /* Initialization not shown */

inflatelib::stream stream; while (have_more_input) { input = read_more_input(); /* Assume result large enough to hold one entire stream's worth of input */

for (bool keepGoing = true; keepGoing; ) { auto outputCopy = output; keepGoing = stream.inflate(input, outputCopy); handle_output(output.subspan(0, output.size() - outputCopy.size())); }

stream.reset(); }

You will notice that there is no error handling in the above code.
When using the C++ interface, errors are thrown as exceptions: `std::invalid_argument` for `INFLATELIB_ERROR_ARG`, `std::bad_alloc` for `INFLATELIB_ERROR_OOM`, and `std::runtime_error` for `INFLATELIB_ERROR_DATA`.
If you don't wish for the inflation functions to throw exceptions, you can instead use the `try_inflate`/`try_inflate64` functions, which return the `int` result, unmodified.
There is no non-throwing alternative to the constructor.

# FAQ

> Q: Why is this library written in C? Why not a memory safe language?

The primary purpose of this library is to be easily integratable into other existing libraries and applications written in C.
If memory safe languages is a concern or requirement for you, several Deflate64 libraries already exist in such languages.
That said, this library has an extensive test suite, compiles and runs against both Address and Undefined Behavior sanitizer, and compiles a libFuzzer executable that is run nightly.

> Q: How does this library differ from zlib?

Zlib currently only has experimental, minimally tested support for Deflate64 that is difficult to enable in a consuming project.
The official stance of the zlib project is that the benefit of Deflate64 is minimal compared to the complexity of implementation and they have no intention of adding official support to the library at this time.
On top of that, this...