Chilkat.Compression Class Overview

Chilkat.Compression provides general-purpose compression and decompression for bytes, strings, files, streams, BinData, and StringBuilder objects. It supports deflate, zlib, bzip2, and lzw, and also includes streaming file operations and combined compress/encrypt workflows.

What the Class Is Used For

Use Chilkat.Compression when an application needs a flexible compression API that works across several input and output forms. The class can compress raw bytes, text, files, streams, or existing BinData buffers, and it can decompress the resulting compressed data back to bytes, text, files, streams, or StringBuilder output.

Multiple Algorithms Choose deflate, zlib, bzip2, or lzw with Algorithm.
Bytes, Text, and Files Compress and decompress byte arrays, strings, files, streams, BinData, and StringBuilder.
Encoded String Output Use EncodingMode with methods ending in ENC to represent compressed bytes as text.
Chunked Processing Use FirstChunk and LastChunk with chunk-aware methods.

Typical Workflow: Compress and Decompress Bytes

  1. Create a Compression object.
  2. Set Algorithm to deflate, zlib, bzip2, or lzw.
  3. Optionally set DeflateLevel when using deflate or zlib.
  4. Call CompressBytes to compress a byte array.
  5. Call DecompressBytes to restore the original bytes.
  6. If a method fails or behaves unexpectedly, inspect LastErrorText.

Typical Workflow: Compress and Decompress Text

  1. Set Charset, preferably to utf-8 for modern applications.
  2. Set Algorithm to the desired compression algorithm.
  3. Call CompressString or CompressStr to convert text to bytes and compress it.
  4. Call DecompressString or DecompressSb to decompress and convert bytes back to text using the same charset.
  5. For encoded string output, set EncodingMode and use CompressStringENC / DecompressStringENC.
Charset recommendation: The current default is the computer's ANSI charset, but most modern applications should explicitly set Charset = "utf-8".

Core Concepts

Concept Meaning Important Members
Compression Algorithm The algorithm used to compress or decompress data. Algorithm
Text Charset The encoding used to convert strings to bytes before compression and bytes back to strings after decompression. Charset
Encoded Compressed Data Compressed binary data represented as text, such as base64 or hex. EncodingMode, CompressBytesENC, CompressStringENC, DecompressStringENC
Chunked Processing Allows data to be compressed or decompressed in a sequence of chunks. FirstChunk, LastChunk
Streaming Files and Streams Allows very large files or continuous streams to be processed with stable memory usage. CompressFile, DecompressFile, CompressStream, DecompressStream
Compression + Encryption Supports combined compression and encryption for file workflows. CompressEncryptFile, DecryptDecompressFile

Algorithms

Algorithm Value Meaning Notes
deflate Deflate compression. Uses DeflateLevel to control compression level.
zlib Deflate compression with a zlib header. Also uses DeflateLevel.
bzip2 BZip2 compression. Use when BZip2-compatible compressed data is required.
lzw LZW compression. Use when LZW-compatible compressed data is required.
ppmd Deprecated. Do not use in new applications. It was only available on 32-bit systems and specifically used the J variant.

Properties

Property Purpose Guidance
Algorithm Selects the compression algorithm. Supported values are deflate, zlib, bzip2, and lzw.
Charset Controls text-to-bytes and bytes-to-text conversion. Set to utf-8 unless compatibility with another encoding is required.
DeflateLevel Compression level for deflate and zlib. 0 means no compression, 9 means maximum compression, and the default is 6.
EncodingMode Text encoding used by methods ending in ENC. Valid values include base64, hex, url, and quoted-printable.
FirstChunk Indicates the next chunk-aware call is the first chunk. Default is true. When both FirstChunk and LastChunk are true, the operation is treated as a complete single-call operation.
LastChunk Indicates the next chunk-aware call is the final chunk. Default is true. Set carefully when processing a sequence of chunks.
HeartbeatMs Interval in milliseconds between AbortCheck callbacks. Default is 0, which disables AbortCheck callbacks.
UncommonOptions Enables specialized behavior. Normally remains empty. Supported option: Crypt2CompressHdr.
LastErrorText Diagnostic information for the last method or property access. Check after failures or unexpected behavior. Information may be available regardless of success or failure.

Input and Output Patterns

Workflow Compression Method Decompression Method Notes
Byte array to byte array CompressBytes DecompressBytes Chunk-aware.
Pointer/size byte input CompressBytes2 DecompressBytes2 Chunk-aware.
Byte array to encoded string CompressBytesENC DecompressBytesENC Uses EncodingMode. CompressBytesENC is not chunk-aware.
String to compressed bytes CompressString DecompressString Uses Charset. Chunk-aware.
String to encoded compressed string CompressStringENC DecompressStringENC Uses Charset and EncodingMode. Not chunk-aware.
BinData in-place CompressBd DecompressBd Modifies the supplied BinData. Not chunk-aware.
BinData input to separate output CompressBd2 DecompressBd2 Input is not modified; output is appended. Chunk-aware.
StringBuilder text CompressSb DecompressSb Uses Charset. Chunk-aware.
File to file CompressFile DecompressFile Streaming mode for stable memory usage.
Stream source to stream sink CompressStream DecompressStream Suitable for very large or continuous streams.
Compress + encrypt file CompressEncryptFile DecryptDecompressFile Uses JsonObject crypt parameters.

Compression Methods

Method Input Output Chunk-Aware?
CompressBytes Byte array Compressed byte array Yes
CompressBytes2 Byte pointer and size Compressed byte array Yes
CompressBytesENC Byte array Encoded compressed string No
CompressString String Compressed byte array Yes
CompressStringENC String Encoded compressed string No
CompressStr String Appends compressed bytes to BinData Yes
CompressSb StringBuilder Appends compressed bytes to BinData Yes
CompressBd BinData Same BinData, replaced with compressed data No
CompressBd2 Input BinData Appends compressed data to output BinData Yes
CompressFile Source file path Destination file path Streaming file operation
CompressStream Stream source Stream sink Streaming operation
CompressEncryptFile Crypt params and source file path Compressed and encrypted destination file Streaming file operation

Decompression Methods

Method Input Output Chunk-Aware?
DecompressBytes Compressed byte array Decompressed byte array Yes
DecompressBytes2 Compressed byte pointer and size Decompressed byte array Yes
DecompressBytesENC Encoded compressed string Decompressed byte array No
DecompressString Compressed byte array Decompressed string Yes
DecompressStringENC Encoded compressed string Decompressed string No
DecompressSb Compressed BinData Appends decompressed text to StringBuilder Yes
DecompressBd Compressed BinData Same BinData, replaced with decompressed data No
DecompressBd2 Compressed input BinData Appends decompressed data to output BinData Yes
DecompressFile Compressed source file path Destination file path Streaming file operation
DecompressStream Compressed stream source Decompressed stream sink Streaming operation
DecryptDecompressFile Crypt params and encrypted/compressed source file Restored destination file Reverse of CompressEncryptFile

Chunked Compression and Decompression

Some methods are FirstChunk / LastChunk aware. These methods can be used when data arrives or is produced in multiple pieces. The FirstChunk and LastChunk properties tell Chilkat where the next method call sits in the sequence.

Setting Meaning Common Use
FirstChunk = true
LastChunk = false 		The next call begins a multi-call sequence. First piece of a larger input.
FirstChunk = false
LastChunk = false 		The next call is a middle chunk. Intermediate data pieces.
FirstChunk = false
LastChunk = true 		The next call is the final chunk. Last piece of a larger input.
FirstChunk = true
LastChunk = true 		The next call is a complete single-call operation. Default behavior for normal one-shot compression or decompression.
Important: Not every method is chunk-aware. Methods such as CompressBd, DecompressBd, CompressBytesENC, and CompressStringENC are documented as not FirstChunk / LastChunk aware.

Text, Charset, and ENC Methods

Feature Controlled By Applies To Guidance
String to bytes before compression Charset CompressString, CompressStringENC, CompressStr, CompressSb Set Charset = "utf-8" unless another encoding is required.
Bytes to string after decompression Charset DecompressString, DecompressStringENC, DecompressSb Use the same charset that was used to create the original text bytes.
Compressed bytes represented as text EncodingMode Methods ending in ENC. Use base64 for general-purpose text-safe transport, or another supported encoding when required.
ENC method rule: Compression methods ending in ENC return compressed binary data as an encoded string. Decompression methods ending in ENC expect the input string to use the same EncodingMode.

File and Stream Processing

Method What It Does Why It Matters
CompressFile Compresses a source file and writes compressed data to a destination file. Processes internally in streaming mode, allowing files of any size to be compressed with stable memory usage.
DecompressFile Decompresses a source file and writes restored data to a destination file. Processes internally in streaming mode and does not require loading the entire file into memory.
CompressStream Compresses from a stream source and writes compressed data to a stream sink. Suitable for very large or even continuous streams.
DecompressStream Decompresses from a stream source and writes restored data to a stream sink. Suitable for very large or continuous streams with stable memory usage.

Compression with Encryption

Method Purpose Important Details
CompressEncryptFile Compresses and encrypts a source file, writing the result to a destination file. Uses JsonObject crypt parameters. Compression and encryption are performed internally in streaming mode, so files of any size can be processed without loading the whole file into memory.
DecryptDecompressFile Decrypts and decompresses a file, writing the restored data to a destination file. This is the reverse operation of CompressEncryptFile.

Method Summary by Category

Category Members Purpose
Algorithm and options Algorithm, DeflateLevel, UncommonOptions Select the compression algorithm, tune deflate/zlib level, and enable rare compatibility behavior.
Text conversion Charset, EncodingMode Control text-to-byte conversion and encoded-string representation of compressed bytes.
Chunk control FirstChunk, LastChunk Mark the beginning and end of chunk-aware compression or decompression sequences.
Byte arrays CompressBytes, CompressBytes2, CompressBytesENC, DecompressBytes, DecompressBytes2, DecompressBytesENC Compress or decompress byte-oriented data.
Strings and text builders CompressString, CompressStringENC, CompressStr, CompressSb, DecompressString, DecompressStringENC, DecompressSb Compress and decompress text using the configured charset.
BinData CompressBd, CompressBd2, DecompressBd, DecompressBd2 Work with Chilkat BinData buffers.
Files and streams CompressFile, DecompressFile, CompressStream, DecompressStream Process large files or streams with stable memory usage.
Compress/encrypt CompressEncryptFile, DecryptDecompressFile Compress and encrypt a file, or reverse the operation.
Async workflow LoadTaskCaller Load the caller of a completed asynchronous task.
Diagnostics and abort callbacks HeartbeatMs, LastErrorText Configure AbortCheck callback frequency and inspect diagnostic information.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Compressed data cannot be decompressed Algorithm Confirm the same algorithm family is used for decompression as was used for compression.
Text appears corrupted after decompression Charset Confirm the charset matches the encoding of the original text bytes. Prefer utf-8 for new applications.
Encoded compressed string fails to decode or decompress EncodingMode The decompression method must use the same encoding mode used when the compressed data was encoded.
Chunked decompression fails FirstChunk, LastChunk Verify that the first, middle, and final chunks are marked correctly, and that the chosen method is chunk-aware.
Unexpected BinData contents CompressBd, DecompressBd, CompressBd2, DecompressBd2 The in-place methods modify the input BinData. The Bd2 methods leave input unchanged and append to output.
Large file uses too much memory in application code CompressFile, DecompressFile, CompressStream, DecompressStream Use file or stream methods so Chilkat can process the data internally in streaming mode.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected compression, decompression, file, stream, encryption, or async behavior.

Common Pitfalls

Pitfall Better Approach
Relying on the computer's ANSI charset for text compression. Set Charset = "utf-8" unless a different encoding is specifically required.
Using a different EncodingMode for decompression than compression. Use the same EncodingMode for methods ending in ENC.
Assuming all methods are chunk-aware. Check the method documentation. Some methods, especially certain ENC and in-place BinData methods, are not chunk-aware.
Using ppmd in new applications. Use one of the supported algorithms: deflate, zlib, bzip2, or lzw.
Expecting CompressBd to preserve the input buffer. Use CompressBd2 if the input BinData should remain unchanged.
Forgetting that zlib is not identical to raw deflate. Use zlib when a zlib header is expected; use deflate for deflate data without the zlib wrapper.
Ignoring diagnostics after a failed operation. Check LastErrorText for details.

Best Practices

Recommendation Reason
Set Algorithm explicitly. It makes the compressed data format clear and avoids ambiguity.
Use Charset = "utf-8" for text unless another charset is required. UTF-8 is the best default for modern text workflows.
Use file and stream methods for large data. They process data internally in streaming mode with stable memory usage.
Use EncodingMode = "base64" when compressed bytes must be stored or transmitted as text. Base64 is usually the safest general-purpose text representation for binary compressed data.
Use Bd2 methods when input should remain unchanged. CompressBd2 and DecompressBd2 append to a separate output object.
Use chunk-aware methods only with correct FirstChunk and LastChunk settings. Correct chunk boundaries are required for reliable multi-call compression and decompression.
Leave UncommonOptions empty unless compatibility behavior is needed. The supported option is specialized and normally unnecessary.
Check LastErrorText after failures. It provides useful diagnostic detail for failed or unexpected behavior.

Summary

Chilkat.Compression is a flexible compression class for working with compressed bytes, text, files, streams, and Chilkat buffer objects. It supports deflate, zlib, bzip2, and lzw, provides encoded-string convenience methods, supports chunk-aware processing for selected methods, and includes streaming file and stream operations for large data.

The most important practical guidance is to set Algorithm explicitly, use Charset = "utf-8" for text unless another encoding is required, match EncodingMode for ENC compression and decompression methods, use file or stream methods for large data, use the Bd2 methods when input buffers should remain unchanged, and inspect LastErrorText whenever an operation fails.