calamine

 
 

Чиста Rust‑бібліотека для електронних таблиць

Читати XLS, XLSX, XLSM, XLSB, ODS та інші формати з нульовою копією десеріалізації в Rust.

Що таке calamine?

calamine — це високопродуктивна, чиста бібліотека Rust для читання та десеріалізації файлів електронних таблиць Excel та OpenDocument. Вона підтримує формати, такі як XLS, XLSX, XLSM, XLSB, ODS та інші, орієнтуючись на швидке, безпечне та безкопійне вилучення даних. Розроблена для надійності та мінімальних залежностей, calamine уникає зовнішніх системних бібліотек і покладається виключно на чисті реалізації Rust. Її API дозволяє розробникам ефективно витягати значення клітинок, працювати з VBA‑проєктами та аналізувати формули без складного налаштування чи навантаження під час виконання.

Бібліотека відмінно підходить для застосувань, критичних до продуктивності, забезпечуючи значно швидшу обробку порівняно з альтернативами на Python, C# та Go. Завдяки вбудованій інтеграції з Serde, calamine дозволяє безшовно відображати дані електронних таблиць у структури Rust. Вона підтримує відкладене завантаження великих файлів, налаштування рядка заголовків та додаткові функції, такі як підтримка дат/часу через chrono та вилучення даних зображень. Незалежно від того, чи створюєте ви інструменти CLI, веб‑бекенди або вбудовані системи, calamine забезпечує надійну, передбачувану продуктивність на різних платформах.

Previous Next

Початок роботи з calamine

Щоб почати використовувати calamine, додайте його до вашого Rust‑проекту за допомогою Cargo. Ви можете встановити його безпосередньо, використовуючи cargo add calamine, або вручну додати залежність у ваш Cargo.toml. Бібліотека доступна на crates.io, а її вихідний код розміщений на calamine GitHub. Для розширеного використання увімкніть додаткові функції, такі як chrono для підтримки дати/часу або picture для вилучення даних зображень. Бібліотека успішно компілюється на стабільному Rust і не потребує зовнішніх бінарних файлів чи системних бібліотек.

Встановіть calamine через Cargo

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 дозволяє витягувати модулі VBA‑проекту та визначення формул з файлів Excel. Розробники можуть отримувати код 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 читає понад 1 млн рядків з мінімальними витратами пам'яті порівняно з альтернативами, такими як openpyxl та ClosedXML, що робить його ідеальним для високомасштабних конвеєрів ingest‑даних.

Ефективно обробляти великі електронні таблиці

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 забезпечує виняткову продуктивність, обробляючи 41 мільйон клітинок менш ніж за 25 секунд — перевершуючи бібліотеки Python, C# та Go до 9,4 рази. Її дизайн без копіювання та мінімальні алокації у купі значно знижують використання CPU та пам'яті. Тести на файлі XLSX розміром 186 МБ показали, що calamine читає лише 186 МБ з диска, у порівнянні з 1,5 ГБ у excelize. Детермінована поведінка пам'яті бібліотеки та низький тиск на збирач сміття роблять її придатною для реального часу та застосувань, чутливих до затримок. Розробники отримують передбачуване використання ресурсів та стабільну пропускну здатність у різноманітних навантаженнях.

 Українська