### BZ2_bzCompressInit with Default Allocators

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Example of initializing bz_stream using default memory allocators (malloc/free). Set bzalloc, bzfree, and opaque to NULL.

```c
bz_stream strm;
strm.bzalloc = NULL;
strm.bzfree = NULL;
strm.opaque = NULL;

int ret = BZ2_bzCompressInit(&strm, 9, 0, 0);
```

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

### Run ABC Binary in Command-Line Mode

Source: https://github.com/berkeley-abc/abc/blob/master/README.md

Execute ABC directly from the command line. This example demonstrates reading a network, performing synthesis and rewriting operations, and verifying equivalence.

```bash
[...] ~/abc> ./abc
UC Berkeley, ABC 1.01 (compiled Oct  6 2012 19:05:18)
abc 01> r i10.aig; b; ps; b; rw -l; rw -lz; b; rw -lz; b; ps; cec
i10          : i/o =  257/  224  lat =    0  and =   2396  lev = 37
i10          : i/o =  257/  224  lat =    0  and =   1851  lev = 35
Networks are equivalent.
```

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

### BZ2_bzCompressInit with Custom Allocators

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Example of initializing bz_stream with custom memory allocators. Set bzalloc, bzfree, and opaque to NULL to use standard malloc/free.

```c
void *myalloc(void *opaque, int n, int m) {
  return malloc(n*m);
}

void myfree(void *opaque, void *p) {
  free(p);
}

bz_stream strm;
strm.bzalloc = myalloc;
strm.bzfree = myfree;
strm.opaque = NULL;

int ret = BZ2_bzCompressInit(&strm, 9, 0, 0);
```

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

### Example Symbol Codes

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/zlib/algorithm.txt

Illustrates a set of symbols with their corresponding binary codes and lengths, used to demonstrate the inflate algorithm's table construction.

```text
A: 0
B: 10
C: 1100
D: 11010
E: 11011
F: 11100
G: 11101
H: 11110
I: 111110
J: 111111
```

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

### Compile ABC as Static Library

Source: https://github.com/berkeley-abc/abc/blob/master/README.md

To compile ABC as a static library, use the 'make libabc.a' command. This provides additional procedures for starting and quitting the ABC framework when used in a calling application.

```makefile
make libabc.a
```

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

### First Level Lookup Table Example

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/zlib/algorithm.txt

Demonstrates the structure of the first level lookup table in the inflate algorithm, showing how 3-bit prefixes map to symbols or point to subsequent tables.

```text
000: A,1
001: A,1
010: A,1
011: A,1
100: B,2
101: B,2
110: -> table X (gobble 3 bits)
111: -> table Y (gobble 3 bits)
```

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

### Second Level Lookup Table X Example

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/zlib/algorithm.txt

Shows the second level lookup table (Table X) used when the first three bits are '110'. This table decodes symbols that start with '110' and are longer than 3 bits.

```text
00: C,1
01: C,1
10: D,2
11: E,2
```

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

### Get Bzip2 Library Version - BZ2_bzlibVersion

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Returns a string indicating the version of the bzip2 library. This function is part of the zlib compatibility layer.

```c
const char * BZ2_bzlibVersion ( void );
```

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

### Build Demo Program with ABC Static Library

Source: https://github.com/berkeley-abc/abc/blob/master/README.md

To build a demo program that uses ABC as a static library, compile the demo C file and then link it with the static library and necessary system libraries.

```bash
gcc -Wall -g -c demo.c -o demo.o
```

```bash
g++ -g -o demo demo.o libabc.a -lm -ldl -lreadline -lpthread
```

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

### Second Level Lookup Table Y Example

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/zlib/algorithm.txt

Presents the second level lookup table (Table Y) used when the first three bits are '111'. This table decodes symbols that start with '111' and are longer than 3 bits.

```text
000: F,2
001: F,2
010: G,2
011: G,2
100: H,2
101: H,2
110: I,3
111: J,3
```

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

### Run Demo Program with Logic Network

Source: https://github.com/berkeley-abc/abc/blob/master/README.md

Execute the demo program by providing a file containing the logic network in AIGER or BLIF format. The output shows network statistics and verification results.

```bash
[...] ~/abc> demo i10.aig
i10          : i/o =  257/  224  lat =    0  and =   2396  lev = 37
i10          : i/o =  257/  224  lat =    0  and =   1851  lev = 35
Networks are equivalent.
Reading =   0.00 sec   Rewriting =   0.18 sec   Verification =   0.41 sec
```

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

### BZ2_bzWriteOpen

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Prepares to write compressed data to a file handle `f`. It takes parameters for block size, verbosity, and work factor, similar to `BZ2_bzCompressInit`. Returns a pointer to a BZFILE structure on success or NULL on error.

```APIDOC
## BZ2_bzWriteOpen

### Description
Prepare to write compressed data to file handle `f`. `f` should refer to a file which has been opened for writing, and for which the error indicator (`ferror(f)`)is not set.

For the meaning of parameters `blockSize100k`, `verbosity` and `workFactor`, see `BZ2_bzCompressInit`.

All required memory is allocated at this stage, so if the call completes successfully, `BZ_MEM_ERROR` cannot be signalled by a subsequent call to `BZ2_bzWrite`.

### Parameters
- **bzerror** (int *) - Output parameter to store the status of the operation.
- **f** (FILE *) - Pointer to the FILE structure opened for writing.
- **blockSize100k** (int) - Block size in units of 100k bytes (1-9).
- **verbosity** (int) - Controls the level of detail in progress information.
- **workFactor** (int) - Controls the trade-off between compression speed and memory usage.

### Possible assignments to `bzerror`:
- **BZ_CONFIG_ERROR**: if the library has been mis-compiled
- **BZ_PARAM_ERROR**: if f is NULL or blockSize100k < 1 or blockSize100k > 9
- **BZ_IO_ERROR**: if ferror(f) is nonzero
- **BZ_MEM_ERROR**: if insufficient memory is available
- **BZ_OK**: otherwise

### Return Values
- **Pointer to an abstract BZFILE**: if bzerror is BZ_OK
- **NULL**: otherwise

### Allowable next actions:
- **BZ2_bzWrite**: if bzerror is BZ_OK (you could go directly to BZ2_bzWriteClose, but this would be pretty pointless)
- **BZ2_bzWriteClose**: otherwise
```

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

### BZ2_bzCompressInit

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Prepares for compression by initializing the bz_stream structure. It configures block size, verbosity, and a work factor for handling repetitive data. Custom memory allocators can be specified.

```APIDOC
## BZ2_bzCompressInit

### Description
Prepares for compression. The `bz_stream` structure holds all data pertaining to the compression activity. A `bz_stream` structure should be allocated and initialised prior to the call. The fields of `bz_stream` comprise the entirety of the user-visible data. `state` is a pointer to the private data structures required for compression.

Custom memory allocators are supported, via fields `bzalloc`, `bzfree`, and `opaque`. The value `opaque` is passed to as the first argument to all calls to `bzalloc` and `bzfree`, but is otherwise ignored by the library. The call `bzalloc ( opaque, n, m )` is expected to return a pointer `p` to `n * m` bytes of memory, and `bzfree ( opaque, p )` should free that memory.

If you don't want to use a custom memory allocator, set `bzalloc`, `bzfree` and `opaque` to `NULL`, and the library will then use the standard `malloc` / `free` routines.

Before calling `BZ2_bzCompressInit`, fields `bzalloc`, `bzfree` and `opaque` should be filled appropriately, as just described. Upon return, the internal state will have been allocated and initialised, and `total_in_lo32`, `total_in_hi32`, `total_out_lo32` and `total_out_hi32` will have been set to zero. These four fields are used by the library to inform the caller of the total amount of data passed into and out of the library, respectively. You should not try to change them. As of version 1.0, 64-bit counts are maintained, even on 32-bit platforms, using the `_hi32` fields to store the upper 32 bits of the count. So, for example, the total amount of data in is `(total_in_hi32 << 32) + total_in_lo32`.

Parameter `blockSize100k` specifies the block size to be used for compression. It should be a value between 1 and 9 inclusive, and the actual block size used is 100000 x this figure. 9 gives the best compression but takes most memory.

Parameter `verbosity` should be set to a number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output. If the library has been compiled with `-DBZ_NO_STDIO`, no such output will appear for any verbosity setting.

Parameter `workFactor` controls how the compression phase behaves when presented with worst case, highly repetitive, input data. If compression runs into difficulties caused by repetitive data, the library switches from the standard sorting algorithm to a fallback algorithm. The fallback is slower than the standard algorithm by perhaps a factor of three, but always behaves reasonably, no matter how bad the input.

Lower values of `workFactor` reduce the amount of effort the standard algorithm will expend before resorting to the fallback. You should set this parameter carefully; too low, and many inputs will be handled by the fallback algorithm and so compress rather slowly, too high, and your average-to-worst case compression times can become very large. The default value of 30 gives reasonable behaviour over a wide range of circumstances.

Allowable values range from 0 to 250 inclusive. 0 is a special case, equivalent to using the default value of 30.

Note that the compressed output generated is the same regardless of whether or not the fallback algorithm is used.

Be aware also that this parameter may disappear entirely in future versions of the library. In principle it should be possible to devise a good way to automatically choose which algorithm to use. Such a mechanism would render the parameter obsolete.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **strm** (`bz_stream *`) - Pointer to the bz_stream structure to be initialized.
- **blockSize100k** (`int`) - Block size for compression, between 1 and 9 (inclusive). Actual block size is 100000 * this value.
- **verbosity** (`int`) - Verbosity level, between 0 and 4 (inclusive). 0 is silent.
- **workFactor** (`int`) - Controls fallback algorithm usage for repetitive data. Allowable values range from 0 to 250. 0 is equivalent to the default of 30.

### Return Values
- **BZ_CONFIG_ERROR**: If the library has been mis-compiled.
- **BZ_PARAM_ERROR**: If `strm` is NULL, or `blockSize` is out of range (1-9), or `verbosity` is out of range (0-4), or `workFactor` is out of range (0-250).
- **BZ_MEM_ERROR**: If not enough memory is available.
- **BZ_OK**: Otherwise (success).

### Allowable next actions
- **BZ2_bzCompress**: If BZ_OK is returned.
- No specific action needed in case of error.
```

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

### Get Bzip2 Error Information - BZ2_bzerror

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Returns a string describing the most recent error status of a bzip2 file stream and sets an integer pointer to its numerical error code. This is part of the zlib compatibility layer.

```c
const char * BZ2_bzerror ( BZFILE *b, int *errnum );
```

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

### Write to a Compressed File using Bzip2

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Demonstrates writing data to a compressed file using Bzip2's low-level interface. Ensure proper error handling for file operations and Bzip2 functions.

```c
FILE*   f;
BZFILE* b;
int     nBuf;
char    buf[ /* whatever size you like */ ];
int     bzerror;
int     nWritten;

f = fopen ( "myfile.bz2", "w" );
if ( !f ) {
 /* handle error */
}
b = BZ2_bzWriteOpen( &bzerror, f, 9 );
if (bzerror != BZ_OK) {
 BZ2_bzWriteClose ( b );
 /* handle error */
}

while ( /* condition */ ) {
 /* get data to write into buf, and set nBuf appropriately */
 nWritten = BZ2_bzWrite ( &bzerror, b, buf, nBuf );
 if (bzerror == BZ_IO_ERROR) {
   BZ2_bzWriteClose ( &bzerror, b );
   /* handle error */
 }
}

BZ2_bzWriteClose( &bzerror, b );
if (bzerror == BZ_IO_ERROR) {
 /* handle error */
}
```

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

### BZ2_bzDecompressInit

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Prepares a bz_stream for decompression. It initializes the internal state and sets total_in and total_out to zero. Custom memory allocators can be specified. The 'small' parameter allows for a lower memory usage decompression algorithm at the cost of speed.

```APIDOC
## BZ2_bzDecompressInit

### Description
Prepares for decompression. A `bz_stream` record should be allocated and initialised before the call. Fields `bzalloc`, `bzfree` and `opaque` should be set if a custom memory allocator is required, or made `NULL` for the normal `malloc` / `free` routines. Upon return, the internal state will have been initialised, and `total_in` and `total_out` will be zero.

### Parameters
- **strm** (*bz_stream* *) - Required - Pointer to the bz_stream structure.
- **verbosity** (*int*) - Required - Controls the level of output verbosity (0-4).
- **small** (*int*) - Required - If non-zero, uses a memory-efficient decompression algorithm.

### Return Values
- **BZ_CONFIG_ERROR**: If the library has been mis-compiled.
- **BZ_PARAM_ERROR**: If `small` is not 0 or 1, or `verbosity` is outside the range [0, 4].
- **BZ_MEM_ERROR**: If insufficient memory is available.
- **BZ_OK**: Otherwise.

### Allowable next actions:
- **BZ2_bzDecompress**: If BZ_OK was returned.
- No specific action required in case of error.
```

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

### Read from a Compressed File using Bzip2

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Illustrates reading data from a compressed file using Bzip2's low-level interface. Includes error checking for read operations and stream end conditions.

```c
FILE*   f;
BZFILE* b;
int     nBuf;
char    buf[ /* whatever size you like */ ];
int     bzerror;
int     nWritten;

f = fopen ( "myfile.bz2", "r" );
if ( !f ) {
  /* handle error */
}
b = BZ2_bzReadOpen ( &bzerror, f, 0, NULL, 0 );
if ( bzerror != BZ_OK ) {
  BZ2_bzReadClose ( &bzerror, b );
  /* handle error */
}

bzerror = BZ_OK;
while ( bzerror == BZ_OK && /* arbitrary other conditions */) {
  nBuf = BZ2_bzRead ( &bzerror, b, buf, /* size of buf */ );
  if ( bzerror == BZ_OK ) {
    /* do something with buf[0 .. nBuf-1] */
  }
}
if ( bzerror != BZ_STREAM_END ) {
   BZ2_bzReadClose ( &bzerror, b );
   /* handle error */
} else {
   BZ2_bzReadClose ( &bzerror, b );
}
```

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

### Build Shared Library for ABC

Source: https://github.com/berkeley-abc/abc/blob/master/README.md

To build a shared library (libabc.so), add 'ABC_USE_PIC=1' to the make command and specify the 'libabc.so' target.

```makefile
make ABC_USE_PIC=1 libabc.so
```

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

### Open Bzip2 File by Path - BZ2_bzopen

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Opens a bzip2 compressed file for reading or writing. This function is analogous to `fopen` and is part of the zlib compatibility layer.

```c
BZFILE * BZ2_bzopen  ( const char *path, const char *mode );
```

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

### BZ2_bzReadOpen Function Signature

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Prepares to read compressed data from a file handle. Ensure the FILE* is opened in binary mode and consult bzerror for various error conditions like BZ_CONFIG_ERROR, BZ_PARAM_ERROR, BZ_IO_ERROR, or BZ_MEM_ERROR.

```c
BZFILE *BZ2_bzReadOpen( int *bzerror, FILE *f,
                        int verbosity, int small,
                        void *unused, int nUnused );
```

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

### BZ2_bzopen, BZ2_bzdopen

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Opens a bzip2 compressed file for reading or writing, analogous to fopen and fdopen.

```APIDOC
## BZ2_bzopen, BZ2_bzdopen

### Description
Opens a `.bz2` file for reading or writing, using either its name or a pre-existing file descriptor. Analogous to `fopen` and `fdopen`.

### Signatures
```c
BZFILE * BZ2_bzopen ( const char *path, const char *mode );
BZFILE * BZ2_bzdopen ( int fd, const char *mode );
```

### Parameters
- **path** (const char*): The file path for `BZ2_bzopen`.
- **fd** (int): The file descriptor for `BZ2_bzdopen`.
- **mode** (const char*): The mode in which to open the file (e.g., "r", "w", "rb", "wb").
```

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

### BZ2_bzCompressInit Function Signature

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

The function signature for BZ2_bzCompressInit. It initializes a bz_stream structure for compression.

```c
int BZ2_bzCompressInit ( bz_stream *strm, 
                         int blockSize100k, 
                         int verbosity,
                         int workFactor );
```

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

### BZ2_bzReadOpen

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Prepares to read compressed data from a file handle.

```APIDOC
## BZ2_bzReadOpen

### Description
Prepares to read compressed data from a file handle `f`. The file `f` should be opened for reading and have no error indicator set. The `small` parameter influences memory usage versus speed. `unused` and `nUnused` allow for pre-decompression of data before reading from the file handle.

### Signature
`BZFILE *BZ2_bzReadOpen(int *bzerror, FILE *f, int verbosity, int small, void *unused, int nUnused);`

### Parameters
* **bzerror** (*int* *) - A pointer to an integer that will store the outcome of the call. Should be checked first.
* **f** (*FILE* *) - A file handle opened for reading.
* **verbosity** (*int*) - Controls the level of verbosity (see BZ2_bzDecompressInit).
* **small** (*int*) - If 1, the library attempts to decompress using less memory at the expense of speed.
* **unused** (*void* *) - A pointer to data to be pre-decompressed before reading from `f`. Pass NULL if not needed.
* **nUnused** (*int*) - The number of bytes in `unused`. Pass 0 if `unused` is NULL. Maximum is BZ_MAX_UNUSED.

### Return Values
* **Pointer to an abstract BZFILE**: if bzerror is BZ_OK.
* **NULL**: otherwise.

### Possible assignments to bzerror:
* **BZ_CONFIG_ERROR**: if the library has been mis-compiled.
* **BZ_PARAM_ERROR**: if f is NULL, or small is neither 0 nor 1, or (unused == NULL && nUnused != 0), or (unused != NULL && !(0 <= nUnused <= BZ_MAX_UNUSED)).
* **BZ_IO_ERROR**: if ferror(f) is nonzero.
* **BZ_MEM_ERROR**: if insufficient memory is available.
* **BZ_OK**: otherwise.

### Allowable next actions
* **BZ2_bzRead**: if bzerror is BZ_OK.
* **BZ2_bzClose**: otherwise.
```

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

### Compile ABC as C++ with Namespaces

Source: https://github.com/berkeley-abc/abc/blob/master/README.md

To compile ABC as C++ code with namespaces, set the CC to g++ and define ABC_NAMESPACE with the desired namespace name using OPTFLAGS.

```makefile
CC=g++ -DABC_NAMESPACE=xxx
```

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

### Open Bzip2 File by File Descriptor - BZ2_bzdopen

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Opens a bzip2 compressed file for reading or writing using a pre-existing file descriptor. This function is analogous to `fdopen` and is part of the zlib compatibility layer.

```c
BZFILE * BZ2_bzdopen ( int        fd,    const char *mode );
```

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

### BZ2_bzlibVersion

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Returns a string indicating the version of the bzip2 library.

```APIDOC
## BZ2_bzlibVersion

### Description
Returns a string indicating the library version.

### Signature
```c
const char * BZ2_bzlibVersion( void );
```
```

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

### Run ABC Binary in Batch Mode

Source: https://github.com/berkeley-abc/abc/blob/master/README.md

Execute ABC in batch mode by providing a command string using the -c option. This is useful for scripting and automated tasks.

```bash
[...] ~/abc> ./abc -c "r i10.aig; b; ps; b; rw -l; rw -lz; b; rw -lz; b; ps; cec"
ABC command line: "r i10.aig; b; ps; b; rw -l; rw -lz; b; rw -lz; b; ps; cec".
i10          : i/o =  257/  224  lat =    0  and =   2396  lev = 37
i10          : i/o =  257/  224  lat =    0  and =   1851  lev = 35
Networks are equivalent.
```

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

### Utility Functions

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Functions for buffer-to-buffer compression and decompression.

```APIDOC
## `BZ2_bzBuffToBuffCompress`

### Description
Compresses data from a buffer to another buffer.

### Function Signature
`int BZ2_bzBuffToBuffCompress(char *dest, unsigned int *destLen, const char *source, unsigned int sourceLen, int blockSize100k, int verbosity, int workFactor);
`

### Parameters
- `dest` (char*) - Destination buffer for compressed data.
- `destLen` (unsigned int*) - Pointer to the size of the destination buffer (will be updated with the compressed size).
- `source` (const char*) - Source buffer containing the data to compress.
- `sourceLen` (unsigned int) - Size of the source buffer.
- `blockSize100k` (int) - Size of the block in 100k units (1-9).
- `verbosity` (int) - Controls the level of output (0-4).
- `workFactor` (int) - Controls the trade-off between speed and memory usage (1-25).

### Return Value
Returns `BZ_OK` on success, or an error code.
```

```APIDOC
## `BZ2_bzBuffToBuffDecompress`

### Description
Decompresses data from a buffer to another buffer.

### Function Signature
`int BZ2_bzBuffToBuffDecompress(char *dest, unsigned int *destLen, const char *source, unsigned int sourceLen, int verbosity, int smallMem);
`

### Parameters
- `dest` (char*) - Destination buffer for decompressed data.
- `destLen` (unsigned int*) - Pointer to the size of the destination buffer (will be updated with the decompressed size).
- `source` (const char*) - Source buffer containing the compressed data.
- `sourceLen` (unsigned int) - Size of the source buffer.
- `verbosity` (int) - Controls the level of output (0-4).
- `smallMem` (int) - Flag to enable small memory mode (0 or 1).

### Return Value
Returns `BZ_OK` on success, or an error code.
```

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

### Low-level Interface Functions

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Functions for direct control over bzip2 compression and decompression streams.

```APIDOC
## `BZ2_bzCompressInit`

### Description
Initializes the compression stream.

### Function Signature
`int BZ2_bzCompressInit(bz_stream *strm, int blockSize100k, int verbosity, int workFactor);`

### Parameters
- `strm` (bz_stream*) - Pointer to the stream structure.
- `blockSize100k` (int) - Size of the block in 100k units (1-9).
- `verbosity` (int) - Controls the level of output (0-4).
- `workFactor` (int) - Controls the trade-off between speed and memory usage (1-25).

### Return Value
Returns `BZ_OK` on success, or an error code otherwise.
```

```APIDOC
## `BZ2_bzCompress`

### Description
Performs compression on the input data.

### Function Signature
`int BZ2_bzCompress(bz_stream *strm, int action);`

### Parameters
- `strm` (bz_stream*) - Pointer to the stream structure.
- `action` (int) - Action to perform (`BZ_RUN` or `BZ_FLUSH`).

### Return Value
Returns `BZ_OK` on success, or an error code otherwise.
```

```APIDOC
## `BZ2_bzCompressEnd`

### Description
Cleans up the compression stream and frees allocated memory.

### Function Signature
`int BZ2_bzCompressEnd(bz_stream *strm);`

### Parameters
- `strm` (bz_stream*) - Pointer to the stream structure.

### Return Value
Returns `BZ_OK` on success, or an error code otherwise.
```

```APIDOC
## `BZ2_bzDecompressInit`

### Description
Initializes the decompression stream.

### Function Signature
`int BZ2_bzDecompressInit(bz_stream *strm, int verbosity, int smallMem);`

### Parameters
- `strm` (bz_stream*) - Pointer to the stream structure.
- `verbosity` (int) - Controls the level of output (0-4).
- `smallMem` (int) - Flag to enable small memory mode (0 or 1).

### Return Value
Returns `BZ_OK` on success, or an error code otherwise.
```

```APIDOC
## `BZ2_bzDecompress`

### Description
Performs decompression on the input data.

### Function Signature
`int BZ2_bzDecompress(bz_stream *strm);`

### Parameters
- `strm` (bz_stream*) - Pointer to the stream structure.

### Return Value
Returns `BZ_OK` on success, or an error code otherwise.
```

```APIDOC
## `BZ2_bzDecompressEnd`

### Description
Cleans up the decompression stream and frees allocated memory.

### Function Signature
`int BZ2_bzDecompressEnd(bz_stream *strm);`

### Parameters
- `strm` (bz_stream*) - Pointer to the stream structure.

### Return Value
Returns `BZ_OK` on success, or an error code otherwise.
```

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

### Low-level Interface Functions

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

These functions provide a low-level interface for managing compression and decompression streams. They allow for fine-grained control over the compression and decompression process.

```APIDOC
## Low-level Interface

This section describes the low-level functions for managing compression and decompression streams.

### `BZ2_bzCompressInit`

Initializes the compression stream.

### `BZ2_bzCompress`

Performs compression on the provided data buffer.

### `BZ2_bzCompressEnd`

Cleans up and finalizes the compression stream.

### `BZ2_bzDecompressInit`

Initializes the decompression stream.

### `BZ2_bzDecompress`

Performs decompression on the provided data buffer.

### `BZ2_bzDecompressEnd`

Cleans up and finalizes the decompression stream.
```

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

### High-level Interface Functions

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Functions for simplified reading and writing of bzip2 compressed data.

```APIDOC
## `BZ2_bzReadOpen`

### Description
Opens a bzip2 compressed stream for reading.

### Function Signature
`bzFile BZ2_bzReadOpen(int *bzErrorf, FILE *f, int bin, int چھوڑ, const char *mode);
`

### Parameters
- `bzErrorf` (int*) - Pointer to an integer for error reporting.
- `f` (FILE*) - File pointer to the compressed data.
- `bin` (int) - Binary mode flag (0 or 1).
- ` چھوڑ` (int) - Unused parameter.
- `mode` (const char*) - Mode string (e.g., "rb").

### Return Value
Returns a `bzFile` handle on success, or `NULL` on error.
```

```APIDOC
## `BZ2_bzRead`

### Description
Reads decompressed data from a `bzFile`.

### Function Signature
`int BZ2_bzRead(int *bzErrorf, bzFile f, void *buf, int len);
`

### Parameters
- `bzErrorf` (int*) - Pointer to an integer for error reporting.
- `f` (bzFile) - The `bzFile` handle.
- `buf` (void*) - Buffer to store the decompressed data.
- `len` (int) - Maximum number of bytes to read.

### Return Value
Returns the number of bytes read, or a negative error code.
```

```APIDOC
## `BZ2_bzReadGetUnused`

### Description
Retrieves unused data after a `BZ2_bzRead` call.

### Function Signature
`int BZ2_bzReadGetUnused(int *bzErrorf, bzFile f, void **buf, int *len);
`

### Parameters
- `bzErrorf` (int*) - Pointer to an integer for error reporting.
- `f` (bzFile) - The `bzFile` handle.
- `buf` (void**) - Pointer to a buffer that will hold the unused data.
- `len` (int*) - Pointer to an integer that will hold the length of the unused data.

### Return Value
Returns `BZ_OK` on success, or a negative error code.
```

```APIDOC
## `BZ2_bzReadClose`

### Description
Closes a `bzFile` opened for reading.

### Function Signature
`int BZ2_bzReadClose(int *bzErrorf, bzFile f);
`

### Parameters
- `bzErrorf` (int*) - Pointer to an integer for error reporting.
- `f` (bzFile) - The `bzFile` handle.

### Return Value
Returns `BZ_OK` on success, or a negative error code.
```

```APIDOC
## `BZ2_bzWriteOpen`

### Description
Opens a `bzFile` for writing compressed data.

### Function Signature
`bzFile BZ2_bzWriteOpen(int *bzErrorf, FILE *f, int blockSize100k, int verbosity, int workFactor);
`

### Parameters
- `bzErrorf` (int*) - Pointer to an integer for error reporting.
- `f` (FILE*) - File pointer to write the compressed data to.
- `blockSize100k` (int) - Size of the block in 100k units (1-9).
- `verbosity` (int) - Controls the level of output (0-4).
- `workFactor` (int) - Controls the trade-off between speed and memory usage (1-25).

### Return Value
Returns a `bzFile` handle on success, or `NULL` on error.
```

```APIDOC
## `BZ2_bzWrite`

### Description
Writes compressed data to a `bzFile`.

### Function Signature
`int BZ2_bzWrite(int *bzErrorf, bzFile f, const void *buf, int len);
`

### Parameters
- `bzErrorf` (int*) - Pointer to an integer for error reporting.
- `f` (bzFile) - The `bzFile` handle.
- `buf` (const void*) - Buffer containing the data to compress and write.
- `len` (int) - Number of bytes to write.

### Return Value
Returns the number of bytes written, or a negative error code.
```

```APIDOC
## `BZ2_bzWriteClose`

### Description
Closes a `bzFile` opened for writing, flushing any remaining compressed data.

### Function Signature
`int BZ2_bzWriteClose(int *bzErrorf, bzFile f);
`

### Parameters
- `bzErrorf` (int*) - Pointer to an integer for error reporting.
- `f` (bzFile) - The `bzFile` handle.

### Return Value
Returns `BZ_OK` on success, or a negative error code.
```

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

### BZ2_bzBuffToBuffCompress

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Compresses data from a source buffer to a destination buffer. This is a one-shot operation.

```APIDOC
## BZ2_bzBuffToBuffCompress

### Description
Attempts to compress the data in `source[0 .. sourceLen-1]` into the destination buffer, `dest[0 .. *destLen-1]`. If the destination buffer is big enough, `*destLen` is set to the size of the compressed data, and `BZ_OK` is returned. If the compressed data won't fit, `*destLen` is unchanged, and `BZ_OUTBUFF_FULL` is returned.

Compression in this manner is a one-shot event, done with a single call to this function. The resulting compressed data is a complete `bzip2` format data stream. There is no mechanism for making additional calls to provide extra input data. If you want that kind of mechanism, use the low-level interface.

For the meaning of parameters `blockSize100k`, `verbosity` and `workFactor`, see `BZ2_bzCompressInit`.

To guarantee that the compressed data will fit in its buffer, allocate an output buffer of size 1% larger than the uncompressed data, plus six hundred extra bytes.

`BZ2_bzBuffToBuffDecompress` will not write data at or beyond `dest[*destLen]`, even in case of buffer overflow.

### Parameters
#### Path Parameters
- **dest** (char*) - Required - Pointer to the destination buffer for compressed data.
- **destLen** (unsigned int*) - Required - Pointer to the size of the destination buffer. Will be updated with the size of the compressed data.
- **source** (char*) - Required - Pointer to the source buffer containing data to compress.
- **sourceLen** (unsigned int) - Required - The length of the data in the source buffer.
- **blockSize100k** (int) - Required - Block size in units of 100k bytes (1-9).
- **verbosity** (int) - Required - Verbosity level (0-4).
- **workFactor** (int) - Required - Compression work factor (0-250).

### Return Values
- **BZ_CONFIG_ERROR**: If the library has been mis-compiled.
- **BZ_PARAM_ERROR**: If parameters are invalid (e.g., NULL pointers, invalid block size, verbosity, or work factor).
- **BZ_MEM_ERROR**: If insufficient memory is available.
- **BZ_OUTBUFF_FULL**: If the compressed data exceeds the destination buffer size.
- **BZ_OK**: If compression was successful.
```

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

### Compress Buffer to Buffer using Bzip2

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Compresses data from a source buffer to a destination buffer in a single operation. The destination buffer must be pre-allocated and large enough to hold the compressed data.

```c
int BZ2_bzBuffToBuffCompress( char*         dest,
                              unsigned int* destLen,
                              char*         source,
                              unsigned int  sourceLen,
                              int           blockSize100k,
                              int           verbosity,
                              int           workFactor );
```

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

### Utility Functions

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

These utility functions provide convenient ways to perform common compression and decompression tasks, such as compressing or decompressing data between two buffers.

```APIDOC
## Utility Functions

This section describes utility functions for common compression and decompression tasks.

### `BZ2_bzBuffToBuffCompress`

Compresses data from a source buffer to a destination buffer.

### `BZ2_bzBuffToBuffDecompress`

Decompresses data from a source buffer to a destination buffer.
```

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

### Link Libraries for Gia Test

Source: https://github.com/berkeley-abc/abc/blob/master/test/gia/CMakeLists.txt

Links the Gia test executable with the gtest_main and libabc libraries.

```cmake
target_link_libraries(gia_test
    gtest_main
    libabc
)
```

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

### BZ2_bzCompress

Source: https://github.com/berkeley-abc/abc/blob/master/src/misc/bzlib/manual.html

Manages input and output buffers for data compression. It allows transferring data between caller-maintained buffers and updates buffer pointers and counts. It also handles state transitions for the compression stream (RUNNING, FLUSHING, FINISHING).

```APIDOC
## BZ2_bzCompress

### Description
Provides more input and/or output buffer space for the library. The caller maintains input and output buffers, and calls `BZ2_bzCompress` to transfer data between them. It also manages the state of the compression stream.

### Function Signature
`int BZ2_bzCompress(bz_stream *strm, int action);`

### Parameters
- **strm** (*bz_stream*)
  - A pointer to the `bz_stream` structure containing buffer information (`next_in`, `avail_in`, `next_out`, `avail_out`) and state.
- **action** (*int*)
  - The action to perform. Possible values include `BZ_RUN`, `BZ_FLUSH`, and `BZ_FINISH`.

### Usage Details
- **Input Buffering**: Before calling, `strm->next_in` should point to the data to be compressed, and `strm->avail_in` should indicate the number of bytes available. `BZ2_bzCompress` updates `next_in`, `avail_in`, and `total_in`.
- **Output Buffering**: `strm->next_out` should point to a buffer for compressed data, with `strm->avail_out` indicating available space. `BZ2_bzCompress` updates `next_out`, `avail_out`, and `total_out`.
- **Buffer Management**: You can provide and remove data in arbitrary amounts, but ensure at least one byte of output space is available.

### Stream States and Actions
- **IDLE**: State before initialization or after termination. Any action is illegal.
- **RUNNING**: Initial state after `BZ2_bzCompressInit`. Use `BZ_RUN` for normal compression.
  - **Action**: `BZ_RUN`
  - **Result**: Compresses data as much as possible.
  - **Next State**: RUNNING
  - **Return Value**: `BZ_RUN_OK`
- **FLUSHING**: State entered when `BZ_FLUSH` is requested. Used to process remaining data in a compression block without accepting new input.
  - **Action**: `BZ_FLUSH` (from RUNNING state)
  - **Result**: Remembers current input pointer, compresses available data, does not accept more input.
  - **Next State**: FLUSHING
  - **Return Value**: `BZ_FLUSH_OK`
  - **Continuation**: Repeated calls with `BZ_FLUSH` until `BZ_RUN` is returned indicate flush completion.
- **FINISHING**: State entered when `BZ_FINISH` is requested. Used to process all remaining buffered data and terminate the stream.
  - **Action**: `BZ_FINISH` (from RUNNING state)
  - **Result**: Remembers current input pointer, compresses available data, does not accept more input.
  - **Next State**: FINISHING
  - **Return Value**: `BZ_FINISH_OK`
  - **Continuation**: Repeated calls with `BZ_FINISH` until `BZ_STREAM_END` is returned indicate stream termination.

### Error Handling
- `BZ_SEQUENCE_ERROR`: Returned for illegal actions based on the current stream state, or if more input is provided after `BZ_FLUSH` or `BZ_FINISH` has been initiated.

### Return Values
- `BZ_RUN_OK`: Normal compression successful.
- `BZ_FLUSH_OK`: Flush operation initiated successfully.
- `BZ_FINISH_OK`: Finish operation initiated successfully.
- `BZ_STREAM_END`: Indicates the end of the compressed stream after a `BZ_FINISH` action.
- `BZ_SEQUENCE_ERROR`: Sequence error detected.
```