
calamine
纯 Rust 电子表格库
在 Rust 中使用零拷贝反序列化读取 XLS、XLSX、XLSM、XLSB、ODS 等格式。
什么是 calamine?
calamine 是一个高性能、纯 Rust 库,用于读取和反序列化 Excel 和 OpenDocument 电子表格文件。它支持 XLS、XLSX、XLSM、XLSB、ODS 等格式,专注于快速、安全、零拷贝的数据提取。calamine 设计注重可靠性和最小依赖,避免使用外部系统库,仅依赖纯 Rust 实现。其 API 使开发者能够高效提取单元格值、处理 VBA 项目并解析公式,无需复杂的设置或运行时开销。
该库在性能关键的应用中表现出色,提供的处理速度显著快于 Python、C# 和 Go 等替代方案。通过内置的 Serde 集成,calamine 能够无缝地将电子表格数据映射到 Rust 结构体。它支持大文件的惰性加载、标题行配置,以及可选的 chrono 日期/时间支持和图片数据提取等功能。无论您是构建 CLI 工具、Web 后端还是嵌入式系统,calamine 都能在各平台上提供稳健、可预测的性能。
开始使用 calamine
要开始使用 calamine,请通过 Cargo 将其添加到您的 Rust 项目中。您可以直接使用 cargo add calamine 安装,或手动将依赖添加到您的 Cargo.toml。该库可在 crates.io 获取,源码托管在 calamine GitHub。如需高级用法,请启用可选特性,例如用于日期/时间支持的 chrono 或用于图像数据提取的 picture。该库在稳定版 Rust 上可顺利编译,无需外部二进制文件或系统库。
通过 Cargo 安装 calamine
cargo add calamine基于 Serde 的电子表格反序列化
calamine 提供强大的 Serde 集成,可将电子表格数据直接映射到 Rust 结构体。使用 RangeDeserializerBuilder,开发者可以定义强类型的数据模型,并自动将行反序列化为结构化记录。该库包含诸如 deserialize_as_f64_or_none 和 deserialize_as_f64_or_string 等辅助函数,以优雅地处理混合类型列。此方法确保类型安全,减少样板代码,并实现数据结构的编译时验证。它特别适用于数据管道、报告工具和 ETL 应用程序,在可靠性和性能至关重要的场景中。
将电子表格行反序列化为 Rust 结构体
use calamine::{deserialize_as_f64_or_none, open_workbook, RangeDeserializerBuilder, Reader, Xlsx};
use serde::Deserialize;
#[derive(Deserialize)]
struct Record {
metric: String,
#[serde(deserialize_with = "deserialize_as_f64_or_none")]
value: Option,
}
let mut excel: Xlsx<_> = open_workbook("file.xlsx")?;
let range = excel.worksheet_range("Sheet1")?;
let iter = RangeDeserializerBuilder::with_headers(&["metric", "value"]).from_range(&range)?;
for result in iter {
let record: Record = result?;
println!("{:?}", record);
} VBA 项目和公式提取
calamine 能够从 Excel 文件中提取 VBA 项目模块和公式定义。开发者可以从模块中检索 VBA 代码,检测损坏的引用,并检查已定义的名称及其公式。此功能对于迁移工具、审计实用程序和遗留系统分析至关重要。API 提供对 VBA 元数据的结构化访问,并支持简单和复杂的工作簿检查场景。无论是出于安全分析宏还是转换遗留 Excel 逻辑,calamine 都提供对隐藏工作簿内容的精确低层访问。
提取 VBA 代码和已定义名称
use calamine::{open_workbook_auto, Reader};
let mut workbook = open_workbook_auto("file.xlsx")?;
if let Ok(Some(vba)) = workbook.vba_project() {
let module = vba.get_module("Module1").unwrap();
println!("{}", module);
for ref in vba.get_references() {
if ref.is_missing() { println!("Broken: {}", ref.name); }
}
}
for (name, formula) in workbook.defined_names() {
println!("{}: {}", name, formula);
}惰性加载和大文件处理
calamine 支持对 XLSX 和 XLSB 文件进行惰性加载,使得在不一次性将所有工作表加载到内存中的情况下高效处理大型电子表格。通过配置标题行并使用基于范围的迭代,开发者可以最小化内存占用并最大化吞吐量。此功能对于资源受限的无服务器函数、CLI 工具和嵌入式部署尤为有价值。基准测试显示,calamine 在读取超过 100 万行时的内存开销极低,相比 openpyxl 和 ClosedXML 等替代方案更具优势,使其成为大规模数据摄取管道的理想选择。
高效处理大型电子表格
use calamine::{open_workbook, Reader, Xlsx};
let mut excel: Xlsx<_> = open_workbook("large.xlsx")?;
let range = excel
.worksheet_range("Sheet1")?
.expect("Sheet not found");
for row in range.rows() {
// Process row without loading entire file
process_row(row);
}性能优化与基准测试
calamine 提供卓越的性能,在不到 25 秒的时间内处理 4100 万个单元格——比 Python、C# 和 Go 库快最高达 9.4 倍。其零拷贝设计和最小堆分配显著降低了 CPU 和内存使用。对 186MB XLSX 文件的基准测试显示,calamine 仅使用 186MB 磁盘读取,而 excelize 则需要 1.5GB。该库的确定性内存行为和低 GC 压力使其适用于实时和对延迟敏感的应用。开发者受益于可预测的资源使用和在各种工作负载下保持一致的吞吐量。
