Chilkat Gzip Class Overview

The Chilkat.Gzip class provides functionality for working with GZIP compression in both file-based and in-memory scenarios. It supports compressing and decompressing:

  • Files (.gz, .tar.gz)
  • Strings (with charset conversion)
  • Binary data (byte[], BinData)
  • Encoded data (Base64, Hex, etc.)

It also allows embedding metadata such as filenames, timestamps, and comments within the GZIP format.

Core Capabilities

1. Compression

  • Compress files → .gz
  • Compress strings → binary or encoded output
  • Compress memory → .gz in memory or file
  • In-place compression via BinData

2. Decompression

  • Uncompress .gz files
  • Extract to memory, file, or string
  • In-place decompression
  • Handle encoded compressed data

3. Format Detection

  • Check if data or file is GZIP (ExamineFile, IsGzip, etc.)

4. Encoding Support

  • Base64, Hex, URL, Quoted-Printable, etc.
  • Encode/decode helpers included

5. Streaming Extraction

  • .tar.gz extraction (UnTarGz) with:
    • No temp files
    • Constant memory usage

Key Properties

Compression Behavior

  • CompressionLevel (0–9) Controls compression ratio vs speed (default = 6)

Embedded Metadata

  • Filename → embedded name inside .gz
  • Comment → optional text comment
  • LastModStr / SetDt → timestamp inside archive
  • ExtraData → custom binary metadata

Execution Control

  • AbortCurrent → cancel long operations
  • HeartbeatMs → interval for abort checks

Output Behavior

  • UseCurrentDate → override stored timestamp on extraction

Diagnostics

  • LastErrorText → detailed error/debug info

Method Categories

File-Based Compression

  • CompressFile
  • CompressFile2 (custom embedded filename)
  • CompressMemToFile
  • CompressStringToFile

File-Based Decompression

  • UncompressFile
  • UncompressMemToFile
  • UncompressBdToFile

In-Memory Operations

  • CompressMemory
  • UncompressMemory
  • CompressFileToMem
  • UncompressFileToMem

️ Important limitation:

  • 4GB max for uncompressed size in memory operations

String-Based Operations

  • CompressString
  • CompressStringENC
  • UncompressString
  • UncompressStringENC

Supports charset conversion:

  • utf-8, iso-8859-1, shift_JIS, etc.

BinData / StringBuilder

  • CompressBd, UncompressBd
  • CompressSb

Encoding Utilities

  • Encode, Decode

Format Detection

  • ExamineFile
  • ExamineMemory
  • IsGzip

Advanced / Special

  • UnTarGz → extract .tar.gz safely and efficiently
  • DeflateStringENC / InflateStringENC (raw deflate — not full gzip format)
  • XfdlToXml Converts base64+gzip XFDL data to XML

Important Notes & Gotchas

1. GZIP vs Deflate

  • Compress* → produces GZIP format
  • DeflateStringENC → produces raw deflate (no GZIP wrapper)

2. Embedded Filename Behavior

  • CompressFile2 allows control over extracted filename
  • UncompressFile ignores embedded name and uses provided output path

3. Memory Limits

  • 4GB limit applies to:
    • CompressMemory
    • UncompressMemory
    • UncompressFileToMem

4. Charset Handling

  • String compression always involves:
    1. Convert string → bytes using charset
    2. Compress bytes

5. Error Handling Pattern

Always check:

if (!success) {
    Console.WriteLine(gzip.LastErrorText);
}

Summary

Chilkat.Gzip is a full-featured GZIP utility class that covers:

  • File ↔ memory ↔ string workflows
  • Encoding-aware compression
  • Metadata embedding
  • Safe .tar.gz extraction
  • Format detection and validation

It’s designed to be flexible across:

  • High-level use (files, strings)
  • Low-level control (binary data, encoding, metadata)