kkpcn/CppUtils

Fork 0

黄杰 29e3498feb 添加项目文件。

2025-06-05 10:06:43 +08:00

5.0 KiB

Raw Permalink Blame History

ZlibCpp - zlib C++面向对象封装库

概述

ZlibCpp是对经典zlib压缩库的C++面向对象封装，提供了现代C++风格的API，支持多种数据格式和压缩策略。

特性

🔧 面向对象设计: 使用现代C++设计模式
📦 多格式支持: 支持Zlib、Gzip、Raw Deflate格式
🚀 高性能: 基于原始zlib库，保持高效性能
🛡️ 异常安全: 完整的异常处理机制
📝 易于使用: 提供简单的静态方法和流式API
🔍 丰富的工具: 包含校验和计算、格式检测等工具

核心类结构

ZlibException 异常类层次

ZlibException (基类)
├── ZlibMemoryException (内存错误)
├── ZlibDataException (数据错误)
├── ZlibStreamException (流错误)
├── ZlibBufferException (缓冲区错误)
└── ZlibVersionException (版本错误)

主要类

ZlibBase: 基础抽象类
ZlibCompressor: 压缩器类
ZlibDecompressor: 解压缩器类
ZlibUtils: 工具类，提供便捷的静态方法

快速开始

包含头文件

#include "ZlibCpp.h"
using namespace ZlibCpp;

基本用法

1. 简单压缩/解压缩

// 压缩字符串
std::string data = "Hello, World!";
auto compressed = ZlibUtils::Compress(data);

// 解压缩
std::string decompressed = ZlibUtils::DecompressToString(compressed);

2. 指定压缩级别和格式

auto compressed = ZlibUtils::Compress(data, 
    CompressionLevel::BestCompression, 
    DataFormat::Gzip);

3. 流式压缩

ZlibCompressor compressor(CompressionLevel::DefaultCompression, DataFormat::Zlib);

// 分块压缩
auto chunk1 = compressor.Compress(data1);
auto chunk2 = compressor.Compress(data2);
auto final = compressor.Finish();

// 合并结果
std::vector<uint8_t> result;
result.insert(result.end(), chunk1.begin(), chunk1.end());
result.insert(result.end(), chunk2.begin(), chunk2.end());
result.insert(result.end(), final.begin(), final.end());

压缩级别

enum class CompressionLevel {
    NoCompression = 0,        // 不压缩
    BestSpeed = 1,           // 最快速度
    BestCompression = 9,     // 最佳压缩
    DefaultCompression = -1  // 默认压缩
};

数据格式

enum class DataFormat {
    Zlib = 0,    // 标准zlib格式 (RFC 1950)
    Gzip = 16,   // Gzip格式 (RFC 1952)
    Raw = -1     // 原始deflate格式 (RFC 1951)
};

高级用法

文件压缩

// 压缩文件
bool success = ZlibUtils::CompressFile("input.txt", "output.zlib", 
    CompressionLevel::BestCompression);

// 解压缩文件
bool success = ZlibUtils::DecompressFile("output.zlib", "restored.txt");

校验和计算

std::vector<uint8_t> data = {0x12, 0x34, 0x56, 0x78};

uint32_t adler32 = ZlibUtils::CalculateAdler32(data);
uint32_t crc32 = ZlibUtils::CalculateCRC32(data);

格式检测

auto format = ZlibUtils::DetectFormat(compressed_data);
switch (format) {
    case DataFormat::Zlib:
        std::cout << "Zlib格式" << std::endl;
        break;
    case DataFormat::Gzip:
        std::cout << "Gzip格式" << std::endl;
        break;
    case DataFormat::Raw:
        std::cout << "Raw deflate格式" << std::endl;
        break;
}

编码工具

// Base64编码
std::string base64 = ZlibUtils::Base64Encode(data);
auto decoded = ZlibUtils::Base64Decode(base64);

// 十六进制编码
std::string hex = ZlibUtils::HexEncode(data);
auto hex_decoded = ZlibUtils::HexDecode(hex);

异常处理

try {
    auto compressed = ZlibUtils::Compress(data);
    auto decompressed = ZlibUtils::DecompressToString(compressed);
}
catch (const ZlibMemoryException& e) {
    std::cout << "内存不足: " << e.what() << std::endl;
}
catch (const ZlibDataException& e) {
    std::cout << "数据错误: " << e.what() << std::endl;
}
catch (const ZlibException& e) {
    std::cout << "zlib错误: " << e.what() << std::endl;
}

性能特点

高效内存管理: 使用内存池减少内存分配开销
流式处理: 支持大文件的流式压缩，避免内存溢出
缓冲区优化: 使用8KB缓冲区平衡内存使用和性能
异常安全: RAII设计确保资源正确释放

构建要求

C++11或更高版本
Visual Studio 2017或更新版本 (Windows)
或支持C++11的GCC/Clang (Linux/macOS)

版本信息

std::cout << "库版本: " << ZlibCpp::GetLibraryVersion() << std::endl;
std::cout << "zlib版本: " << ZlibCpp::GetZlibVersion() << std::endl;

示例程序

运行main.cpp中的测试程序可以看到完整的功能演示：

# 编译并运行
# Visual Studio: 直接构建项目
# 或使用命令行编译所有源文件

许可证

本项目基于zlib许可证，与原始zlib库保持一致。

贡献

欢迎提交Issue和Pull Request来改进这个库。

注意: 这个库是对原始zlib的封装，保持了zlib的所有性能特性，同时提供了更友好的C++接口。

5.0 KiB Raw Permalink Blame History Unescape Escape