calamine

 
 

Libreria Rust pura per fogli di calcolo

Leggi XLS, XLSX, XLSM, XLSB, ODS e altro con deserializzazione senza copie in Rust.

Che cos'è calamine?

calamine è una libreria Rust pura ad alte prestazioni per la lettura e la deserializzazione di file di fogli di calcolo Excel e OpenDocument. Supporta formati come XLS, XLSX, XLSM, XLSB, ODS e altri, concentrandosi su un'estrazione dei dati veloce, sicura e senza copie. Progettata per l'affidabilità e con dipendenze minime, calamine evita librerie di sistema esterne e si basa esclusivamente su implementazioni Rust pure. La sua API consente agli sviluppatori di estrarre efficientemente i valori delle celle, gestire progetti VBA e analizzare le formule senza configurazioni complesse o overhead di runtime.

La libreria eccelle nelle applicazioni critiche per le prestazioni, offrendo un'elaborazione significativamente più veloce rispetto alle alternative in Python, C# e Go. Con l'integrazione Serde incorporata, calamine consente una mappatura fluida dei dati dei fogli di calcolo su strutture Rust. Supporta il caricamento pigro per file di grandi dimensioni, la configurazione della riga di intestazione e funzionalità opzionali come il supporto a date/ora di chrono e l'estrazione di dati di immagini. Che tu stia creando strumenti CLI, backend web o sistemi embedded, calamine fornisce prestazioni robuste e prevedibili su tutte le piattaforme.

Previous Next

Iniziare con calamine

Inizia a usare calamine, aggiungendolo al tuo progetto Rust tramite Cargo. Puoi installarlo direttamente usando cargo add calamine o aggiungere manualmente la dipendenza al tuo Cargo.toml. La libreria è disponibile su crates.io e il suo codice sorgente è ospitato su calamine GitHub. Per un uso avanzato, abilita le funzionalità opzionali come chrono per il supporto di data/ora o picture per l'estrazione di dati immagine. La libreria si compila correttamente su Rust stabile e non richiede binari o librerie di sistema esterne.

Installa calamine tramite Cargo

cargo add calamine

Deserializzazione di fogli di calcolo basata su Serde

calamine fornisce una potente integrazione Serde per mappare i dati dei fogli di calcolo direttamente su struct Rust. Utilizzando RangeDeserializerBuilder, gli sviluppatori possono definire modelli di dati fortemente tipizzati e deserializzare automaticamente le righe in record strutturati. La libreria include funzioni di supporto come deserialize_as_f64_or_none e deserialize_as_f64_or_string per gestire agevolmente colonne di tipo misto. Questo approccio garantisce la sicurezza dei tipi, riduce il boilerplate e consente la validazione a tempo di compilazione delle strutture dati. È particolarmente utile per pipeline di dati, strumenti di reporting e applicazioni ETL dove affidabilità e prestazioni sono critiche.

Deserializza le righe del foglio di calcolo in struct 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);
}

Estrazione di progetti VBA e formule

calamine consente l'estrazione dei moduli di progetto VBA e delle definizioni di formule dai file Excel. Gli sviluppatori possono recuperare il codice VBA dai moduli, rilevare riferimenti interrotti e ispezionare i nomi definiti e le loro formule. Questa funzionalità è essenziale per gli strumenti di migrazione, le utility di audit e l'analisi di sistemi legacy. L'API fornisce un accesso strutturato ai metadati VBA e supporta scenari di introspezione della cartella di lavoro sia semplici che complessi. Che tu stia analizzando macro per la sicurezza o convertendo la logica Excel legacy, calamine offre un accesso preciso a basso livello ai contenuti nascosti della cartella di lavoro.

Estrai codice VBA e nomi definiti

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);
}

Caricamento pigro e gestione di file di grandi dimensioni

calamine supporta il caricamento lazy per i file XLSX e XLSB, consentendo un'elaborazione efficiente di grandi fogli di calcolo senza caricare tutti i fogli in memoria contemporaneamente. Configurando le righe di intestazione e utilizzando l'iterazione basata su intervalli, gli sviluppatori possono ridurre al minimo l'impronta di memoria e massimizzare il throughput. Questa funzionalità è particolarmente preziosa per le funzioni serverless, gli strumenti da riga di comando (CLI) e le distribuzioni embedded dove le risorse sono limitate. I benchmark mostrano che calamine legge più di 1 M di righe con un overhead di memoria minimo rispetto ad alternative come openpyxl e ClosedXML, rendendolo ideale per pipeline di ingestione dati su larga scala.

Elabora grandi fogli di calcolo in modo efficiente

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);
}

Ottimizzazione delle prestazioni e benchmark

calamine offre prestazioni eccezionali, elaborando 41 milioni di celle in meno di 25 secondi—superando le librerie Python, C# e Go fino a 9,4x. Il suo design zero-copy e le allocazioni heap minime riducono significativamente l'uso di CPU e memoria. I benchmark su un file XLSX da 186 MB mostrano che calamine utilizza solo 186 MB di letture su disco rispetto a 1,5 GB per excelize. Il comportamento deterministico della memoria della libreria e la bassa pressione sul GC la rendono adatta ad applicazioni in tempo reale e sensibili alla latenza. Gli sviluppatori beneficiano di un utilizzo prevedibile delle risorse e di una larghezza di banda costante su carichi di lavoro diversi.

 Italiano