--- product: Chilkat product_version: 11.7.0 language: pascal language_label: Lazarus Pascal class: Compression license: bundle deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/pascal_CompressionRef.html --- # Chilkat Compression — Lazarus Pascal — v11.7.0 > Chilkat 11.7.0 · language=pascal · class=Compression > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/Compression.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/guide.md`. ## Purpose **Compress and decompress bytes, text, files, and streams with a flexible API.** `Chilkat.Compression` provides a general-purpose API for compressing and decompressing data in memory, files, and streams. It supports multiple algorithms, text charset conversion, encoded output, chunked processing, and streaming operations for large data. **Multiple algorithms** Supports `deflate`, `zlib`, `bzip2`, and `lzw`. **Flexible data types** Work with byte arrays, strings, `BinData`, `StringBuilder`, files, and streams. **Chunked processing** Process data incrementally with `FirstChunk` and `LastChunk` for chunk-aware methods. **Encoded output** Return compressed bytes as text using encodings such as `base64`, `hex`, and others. **Streaming support** Compress or decompress large files and streams with stable memory usage. **Compression + encryption** Combine compression and encryption in file workflows with integrated methods. **Tip:** For text compression, explicitly set `Charset = "utf-8"` unless another encoding is required. For encoded compressed data, set `EncodingMode` to the desired output format. For an extended overview, see [Compression Class Overview](https://www.chilkatsoft.com/compression_class_overview.asp). See also [Binary Encodings](https://www.chilkatsoft.com/binary_encodings.asp) for supported encoded output formats. ## Object creation, unlocking and error handling **Create / Free** ```pascal uses Chilkat.Compression; var obj: TCompression; begin obj := TCompression.Create; try if not obj.IsValid then raise Exception.Create('Failed to create a TCompression instance.'); // ... use obj ... finally obj.Free; end; end; ``` `constructor Create;` Allocates the underlying CkCompression object and returns a new TCompression instance. Simply adding **Chilkat.Compression** to the unit's `uses` clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check `obj.IsValid` after calling `Create`; it is `False` if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed). `destructor Destroy; override;` Every TCompression created by calling `Create` should eventually be released by calling `.Free` (inherited from `TObject`). The destructor automatically disposes the underlying CkCompression handle. A native (unmanaged) memory leak occurs if the object is never freed. Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Lazarus Pascal. ## Members common to every Chilkat class Documented once per language in `common-members.md`; listed here so this page is self-contained. | Property | Signature | Access | Meaning | |---|---|---|---| | `DebugLogFilePath` | `property DebugLogFilePath: string read GetDebugLogFilePath write SetDebugLogFilePath;` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. | | `LastErrorHtml` | `property LastErrorHtml: string read GetLastErrorHtml;` | read-only | Provides HTML-formatted information about the last called method or property. | | `LastErrorText` | `property LastErrorText: string read GetLastErrorText;` | read-only | Provides plain text information about the last called method or property. | | `LastErrorXml` | `property LastErrorXml: string read GetLastErrorXml;` | read-only | Provides XML-formatted information about the last called method or property. | | `LastMethodSuccess` | `property LastMethodSuccess: Boolean read GetLastMethodSuccess write SetLastMethodSuccess;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. | | `VerboseLogging` | `property VerboseLogging: Boolean read GetVerboseLogging write SetVerboseLogging;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. | | `Version` | `property Version: string read GetVersion;` | read-only | Version of the component/library, such as "10.1.0" | ## Member index | Member | Kind | Signature | |---|---|---| | `Algorithm` | property, read/write | `property Algorithm: string read GetAlgorithm write SetAlgorithm;` | | `Charset` | property, read/write | `property Charset: string read GetCharset write SetCharset;` | | `DeflateLevel` | property, read/write | `property DeflateLevel: Integer read GetDeflateLevel write SetDeflateLevel;` | | `EncodingMode` | property, read/write | `property EncodingMode: string read GetEncodingMode write SetEncodingMode;` | | `FirstChunk` | property, read/write | `property FirstChunk: Boolean read GetFirstChunk write SetFirstChunk;` | | `HeartbeatMs` | property, read/write | `property HeartbeatMs: Integer read GetHeartbeatMs write SetHeartbeatMs;` | | `LastChunk` | property, read/write | `property LastChunk: Boolean read GetLastChunk write SetLastChunk;` | | `UncommonOptions` | property, read/write | `property UncommonOptions: string read GetUncommonOptions write SetUncommonOptions;` | | `CompressBd` | method | `// bd is a TBinData object. function CompressBd(bd: TChilkatBase): Boolean;` | | `CompressBd2` | method | `// bdIn is a TBinData object. // bdOut is a TBinData object. function CompressBd2(bdIn: TChilkatBase;     bdOut: TChilkatBase): Boolean;` | | `CompressEncryptFile` | method | `// cryptParams is a TJsonObject object. function CompressEncryptFile(cryptParams: TChilkatBase;     const srcPath: string;     const destPath: string): Boolean;` | | `CompressFile` | method | `function CompressFile(const srcPath: string;     const destPath: string): Boolean;` | | `CompressSb` | method | `// sb is a TStringBuilder object. // binData is a TBinData object. function CompressSb(sb: TChilkatBase;     binData: TChilkatBase): Boolean;` | | `CompressStream` | method | `// strm is a TStream object. function CompressStream(strm: TChilkatBase): Boolean;` | | `CompressStringENC` | method | `function CompressStringENC(const str: string): string;` | | `DecompressBd` | method | `// bd is a TBinData object. function DecompressBd(bd: TChilkatBase): Boolean;` | | `DecompressBd2` | method | `// bdIn is a TBinData object. // bdOut is a TBinData object. function DecompressBd2(bdIn: TChilkatBase;     bdOut: TChilkatBase): Boolean;` | | `DecompressFile` | method | `function DecompressFile(const srcPath: string;     const destPath: string): Boolean;` | | `DecompressSb` | method | `// binData is a TBinData object. // sb is a TStringBuilder object. function DecompressSb(binData: TChilkatBase;     sb: TChilkatBase): Boolean;` | | `DecompressStream` | method | `// strm is a TStream object. function DecompressStream(strm: TChilkatBase): Boolean;` | | `DecompressStringENC` | method | `function DecompressStringENC(const encodedCompressedData: string): string;` | | `DecryptDecompressFile` | method | `// cryptParams is a TJsonObject object. function DecryptDecompressFile(cryptParams: TChilkatBase;     const srcPath: string;     const destPath: string): Boolean;` | | `LoadTaskCaller` | method | `// task is a TTask object. function LoadTaskCaller(task: TChilkatBase): Boolean;` | ## Properties ### Compression.Algorithm `Chilkat 11.7.0 · pascal · Compression · Algorithm · property · read/write` ```pascal property Algorithm: string read GetAlgorithm write SetAlgorithm; ``` Specifies the compression algorithm to use. Supported values are `deflate`, `zlib`, `gzip`, `bzip2`, and `lzw`. The `zlib` option is the deflate algorithm with a zlib header. The `gzip` option (starting in v11.7.0) is the deflate algorithm in the gzip format (RFC 1952): a gzip header, the deflate data, and a trailer with the CRC-32 and size of the uncompressed data. When decompressing in one call, the CRC-32 and size are checked. Before v11.7.0, `gzip` was not recognized and was treated as `deflate`. **Note:** `ppmd` is deprecated and should not be used. It was only available on 32-bit systems and specifically used the J variant. New applications should use one of the supported algorithms listed above. ### Compression.Charset `Chilkat 11.7.0 · pascal · Compression · Charset · property · read/write` ```pascal property Charset: string read GetCharset write SetCharset; ``` **Full documentation for this property (same in every language):** [How Character Encoding (Charset) Affects Compression and Decompression](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/how_charset_affects_compression.md) · [Full List of Character Encodings Supported by Chilkat](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/charsets_supported_by_chilkat.md) Specifies the character encoding used when converting text to bytes before compression, and bytes back to text after decompression. The current default is the computer’s ANSI charset, such as Windows-1252 on many Western Windows systems. However, most modern applications should explicitly set this property to `utf-8`. **Recommendation:** Set `Charset = "utf-8"` unless you specifically need compatibility with another encoding. ### Compression.DeflateLevel `Chilkat 11.7.0 · pascal · Compression · DeflateLevel · property · read/write · since 9.5.0.73` ```pascal property DeflateLevel: Integer read GetDeflateLevel write SetDeflateLevel; ``` Sets the compression level used by the `deflate` and `zlib` algorithms. - `0` means no compression. - `9` means maximum compression. - The default value is `6`. Higher values may produce smaller output but can require more processing time. ### Compression.EncodingMode `Chilkat 11.7.0 · pascal · Compression · EncodingMode · property · read/write` ```pascal property EncodingMode: string read GetEncodingMode write SetEncodingMode; ``` **Full documentation for this property (same in every language):** [Binary Encodings Supported by Chilkat](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/binary_encodings.md) Specifies the text encoding used by methods whose names end in `ENC`, such as `CompressBytesENC` and `DecompressStringENC`. Compression methods ending in `ENC` return compressed binary data as an encoded string. Decompression methods ending in `ENC` expect the input string to use this same encoding. Valid values include: - `base64` - `hex` - `url` - `quoted-printable` ### Compression.FirstChunk `Chilkat 11.7.0 · pascal · Compression · FirstChunk · property · read/write · since 11.0.0` ```pascal property FirstChunk: Boolean read GetFirstChunk write SetFirstChunk; ``` Indicates that the next chunk-aware compression or decompression call is the first chunk in a sequence. The default value is `True`. When both `FirstChunk` and `LastChunk` are `True`, the method call is treated as a complete, single-call compression or decompression operation. ### Compression.HeartbeatMs `Chilkat 11.7.0 · pascal · Compression · HeartbeatMs · property · read/write` ```pascal property HeartbeatMs: Integer read GetHeartbeatMs write SetHeartbeatMs; ``` **Full documentation for this property (same in every language):** [Event Callback Examples](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/event_callback_examples.md) Specifies the interval, in milliseconds, between `AbortCheck` event callbacks. This allows an application to periodically check whether a long-running operation should be aborted. The default value is `0`, which disables `AbortCheck` callbacks. ### Compression.LastChunk `Chilkat 11.7.0 · pascal · Compression · LastChunk · property · read/write · since 11.0.0` ```pascal property LastChunk: Boolean read GetLastChunk write SetLastChunk; ``` Indicates that the next chunk-aware compression or decompression call is the final chunk in a sequence. The default value is `True`. When both `FirstChunk` and `LastChunk` are `True`, the input is treated as the complete data set and processed in a single call. ### Compression.UncommonOptions `Chilkat 11.7.0 · pascal · Compression · UncommonOptions · property · read/write · since 11.0.0` ```pascal property UncommonOptions: string read GetUncommonOptions write SetUncommonOptions; ``` Provides a way to enable specialized or uncommon behavior. This property normally remains empty. It may be set to a comma-separated list of keywords. Supported option: - `Crypt2CompressHdr` — Duplicates the compression/decompression header behavior used by the deprecated and removed Crypt2 compression functions. ## Methods ### Compression.CompressBd `Chilkat 11.7.0 · pascal · Compression · CompressBd · method · since 9.5.0.66` ```pascal // bd is a TBinData object. function CompressBd(bd: TChilkatBase): Boolean; ``` Compresses the data contained in a `BinData` object. The `BinData` object is modified to contain the compressed result. This method is not `FirstChunk` / `LastChunk` aware. Returns True for success, False for failure. ### Compression.CompressBd2 `Chilkat 11.7.0 · pascal · Compression · CompressBd2 · method · since 11.0.0` ```pascal // bdIn is a TBinData object. // bdOut is a TBinData object. function CompressBd2(bdIn: TChilkatBase;     bdOut: TChilkatBase): Boolean; ``` Compresses the data in one `BinData` object and appends the compressed output to another `BinData` object. The input `BinData` is not modified. This method is `FirstChunk` / `LastChunk` aware. Returns True for success, False for failure. ### Compression.CompressEncryptFile `Chilkat 11.7.0 · pascal · Compression · CompressEncryptFile · method · since 9.5.0.99` ```pascal // cryptParams is a TJsonObject object. function CompressEncryptFile(cryptParams: TChilkatBase;     const srcPath: string;     const destPath: string): Boolean; ``` Compresses and encrypts a file, writing the result to a destination file. The compression and encryption are performed internally in streaming mode, so files of any size can be processed without loading the entire file into memory. Returns True for success, False for failure. ### Compression.CompressFile `Chilkat 11.7.0 · pascal · Compression · CompressFile · method` ```pascal function CompressFile(const srcPath: string;     const destPath: string): Boolean; ``` Compresses a source file and writes the compressed data to a destination file. The file is processed internally in streaming mode, allowing files of any size to be compressed with stable memory usage. Returns True for success, False for failure. ### Compression.CompressSb `Chilkat 11.7.0 · pascal · Compression · CompressSb · method · since 9.5.0.73` ```pascal // sb is a TStringBuilder object. // binData is a TBinData object. function CompressSb(sb: TChilkatBase;     binData: TChilkatBase): Boolean; ``` Compresses the text contained in a `StringBuilder` and appends the compressed bytes to a `BinData` object. Text is converted to bytes according to the `Charset` property. This method is `FirstChunk` / `LastChunk` aware. Returns True for success, False for failure. ### Compression.CompressStream `Chilkat 11.7.0 · pascal · Compression · CompressStream · method · since 9.5.0.56` ```pascal // strm is a TStream object. function CompressStream(strm: TChilkatBase): Boolean; ``` Compresses data from a stream source and writes the compressed data to the stream sink. The operation is performed in streaming mode, making it suitable for very large or even continuous streams while maintaining stable memory usage. Returns True for success, False for failure. ### Compression.CompressStringENC `Chilkat 11.7.0 · pascal · Compression · CompressStringENC · method` ```pascal function CompressStringENC(const str: string): string; ``` Compresses a string and returns the compressed result as an encoded string. The string is first converted to bytes using `Charset`, then compressed, and finally encoded according to `EncodingMode`. This method is not `FirstChunk` / `LastChunk` aware. Returns True for success, False for failure. ### Compression.DecompressBd `Chilkat 11.7.0 · pascal · Compression · DecompressBd · method · since 9.5.0.66` ```pascal // bd is a TBinData object. function DecompressBd(bd: TChilkatBase): Boolean; ``` Decompresses the compressed data contained in a `BinData` object. The `BinData` object is modified to contain the decompressed result. This method is not `FirstChunk` / `LastChunk` aware. Returns True for success, False for failure. ### Compression.DecompressBd2 `Chilkat 11.7.0 · pascal · Compression · DecompressBd2 · method · since 11.0.0` ```pascal // bdIn is a TBinData object. // bdOut is a TBinData object. function DecompressBd2(bdIn: TChilkatBase;     bdOut: TChilkatBase): Boolean; ``` Decompresses the data in one `BinData` object and appends the decompressed output to another `BinData` object. The input `BinData` is not modified. This method is `FirstChunk` / `LastChunk` aware. Returns True for success, False for failure. ### Compression.DecompressFile `Chilkat 11.7.0 · pascal · Compression · DecompressFile · method` ```pascal function DecompressFile(const srcPath: string;     const destPath: string): Boolean; ``` Decompresses a source file and writes the decompressed data to a destination file. The file is processed internally in streaming mode, allowing files of any size to be decompressed without loading the entire file into memory. Returns True for success, False for failure. ### Compression.DecompressSb `Chilkat 11.7.0 · pascal · Compression · DecompressSb · method · since 9.5.0.73` ```pascal // binData is a TBinData object. // sb is a TStringBuilder object. function DecompressSb(binData: TChilkatBase;     sb: TChilkatBase): Boolean; ``` Decompresses compressed data from a `BinData` object and appends the resulting text to a `StringBuilder`. The decompressed bytes are converted to text using the `Charset` property. This method is `FirstChunk` / `LastChunk` aware. Returns True for success, False for failure. ### Compression.DecompressStream `Chilkat 11.7.0 · pascal · Compression · DecompressStream · method · since 9.5.0.56` ```pascal // strm is a TStream object. function DecompressStream(strm: TChilkatBase): Boolean; ``` Decompresses data from a stream source and writes the decompressed data to the stream sink. The operation is performed in streaming mode, making it suitable for very large or continuous streams while maintaining stable memory usage. Returns True for success, False for failure. ### Compression.DecompressStringENC `Chilkat 11.7.0 · pascal · Compression · DecompressStringENC · method` ```pascal function DecompressStringENC(const encodedCompressedData: string): string; ``` Decompresses compressed data supplied as an encoded string and returns the resulting text. The input string is decoded according to `EncodingMode`, then decompressed. The resulting bytes are converted to text using `Charset`. This method is not `FirstChunk` / `LastChunk` aware. Returns True for success, False for failure. ### Compression.DecryptDecompressFile `Chilkat 11.7.0 · pascal · Compression · DecryptDecompressFile · method · since 9.5.0.99` ```pascal // cryptParams is a TJsonObject object. function DecryptDecompressFile(cryptParams: TChilkatBase;     const srcPath: string;     const destPath: string): Boolean; ``` Decrypts and decompresses a file, writing the restored data to a destination file. This is the reverse operation of `CompressEncryptFile`. Returns True for success, False for failure. ### Compression.LoadTaskCaller `Chilkat 11.7.0 · pascal · Compression · LoadTaskCaller · method · since 9.5.0.80` ```pascal // task is a TTask object. function LoadTaskCaller(task: TChilkatBase): Boolean; ``` Loads the caller of the task's async method. Returns True for success, False for failure. ## Events and callbacks Chilkat for Pascal supports three synchronous event callbacks: `OnAbortCheck`, `OnPercentDone`, and `OnProgressInfo`. Each is a property of the class; assign a method of one of your own objects (an *of object* handler) to receive the callbacks, or assign `nil` to unhook. The handler types are declared in the `Chilkat.Base` unit: ```pascal TChilkatAbortCheckEvent = function(Sender: TChilkatBase): Boolean of object; TChilkatPercentDoneEvent = function(Sender: TChilkatBase; PctDone: Integer): Boolean of object; TChilkatProgressInfoEvent = procedure(Sender: TChilkatBase; const Name, Value: string) of object; ``` All Chilkat methods are synchronous, so callbacks are invoked on the thread that called the method -- if the method was called from the main thread, it is safe to access UI elements from the handler. The `HeartbeatMs` property controls the frequency of `OnAbortCheck` callbacks (the default of 0 means no AbortCheck events fire). Returning `True` from an `OnAbortCheck` or `OnPercentDone` handler aborts the running method. ### Compression.AbortCheck (event) `Chilkat 11.7.0 · pascal · Compression · AbortCheck · event` ```pascal // TChilkatAbortCheckEvent = function(Sender: TChilkatBase): Boolean of object; property OnAbortCheck: TChilkatAbortCheckEvent; ``` Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the `HeartbeatMs` property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second. **Event callback implementation:** ```pascal // A handler is a method of one of your own classes, e.g. a form: function TMyObject.CompressionAbortCheck(Sender: TChilkatBase): Boolean; begin // Called every HeartbeatMs milliseconds while a method is running. // Return True to abort the method; return False to continue. Result := False; end; ``` **To add an event handler:** ```pascal compression := TCompression.Create; compression.HeartbeatMs := 250; // fire OnAbortCheck 4 times per second compression.OnAbortCheck := MyObject.CompressionAbortCheck; ``` ### Compression.PercentDone (event) `Chilkat 11.7.0 · pascal · Compression · PercentDone · event` ```pascal // TChilkatPercentDoneEvent = function(Sender: TChilkatBase; PctDone: Integer): Boolean of object; property OnPercentDone: TChilkatPercentDoneEvent; ``` This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The `pctDone` argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have `pctDone` equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100). The PercentDone callback also acts as an `AbortCheck` event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination. To abort the operation, set the `abort` output argument to `True`. This will cause the method to terminate and return a failure status or corresponding failure value. **Event callback implementation:** ```pascal // A handler is a method of one of your own classes, e.g. a form: function TMyObject.CompressionPercentDone(Sender: TChilkatBase; PctDone: Integer): Boolean; begin // PctDone ranges from 1 to 100. WriteLn('Percent done: ', PctDone); // Return True to abort the method; return False to continue. Result := False; end; ``` **To add an event handler:** ```pascal compression := TCompression.Create; compression.OnPercentDone := MyObject.CompressionPercentDone; ``` ### Compression.ProgressInfo (event) `Chilkat 11.7.0 · pascal · Compression · ProgressInfo · event` ```pascal // TChilkatProgressInfoEvent = procedure(Sender: TChilkatBase; const Name, Value: string) of object; property OnProgressInfo: TChilkatProgressInfoEvent; ``` This event callback provides `tag name`/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory. Note: Some Chilkat methods don't fire any ProgressInfo events. **Event callback implementation:** ```pascal // A handler is a method of one of your own classes, e.g. a form: procedure TMyObject.CompressionProgressInfo(Sender: TChilkatBase; const Name, Value: string); begin WriteLn(Name, ': ', Value); end; ``` **To add an event handler:** ```pascal compression := TCompression.Create; compression.OnProgressInfo := MyObject.CompressionProgressInfo; ``` ## Related classes [`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/BinData.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/JsonObject.md), [`Stream`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/Stream.md), [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/StringBuilder.md)