1. Что это и зачем нужна

calamine — это высокопроизводительная библиотека для чтения файлов Excel (форматы .xlsx, .xls, .xlsb, .ods) на языке Rust. Она написана на чистом Rust без внешних зависимостей, что делает её идеальным выбором для проектов, где важны скорость, безопасность памяти и кроссплатформенность. В отличие от многих других библиотек, calamine не требует установки Microsoft Office или Java Runtime Environment.

Основное назначение calamine — извлечение данных из электронных таблиц. Она поддерживает чтение ячеек, строк, столбцов, листов, а также работу с формулами, датами, числами и строками. Библиотека особенно полезна для автоматизации обработки отчётов, импорта данных из Excel в базы данных, анализа больших таблиц и создания конвейеров обработки данных (ETL).

calamine спроектирована с акцентом на производительность: она использует потоковое чтение и ленивую загрузку данных, что позволяет обрабатывать файлы размером в сотни мегабайт без значительного потребления оперативной памяти. Библиотека активно поддерживается сообществом Rust и используется в таких известных проектах, как rust-xlsxwriter и tauri.

2. Установка

Для добавления calamine в проект Rust выполните команду в терминале:

cargo add calamine

Или вручную добавьте зависимость в файл Cargo.toml:

[dependencies]
calamine = "0.24"

После этого выполните cargo build, чтобы загрузить и скомпилировать библиотеку. Убедитесь, что у вас установлен Rust (рекомендуется версия 1.65+).

3. Быстрый старт

Минимальный пример чтения данных из Excel файла:

use calamine::{open_workbook, Reader, Xlsx};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Открываем файл
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx")?;
    
    // Получаем первый лист
    let sheet_name = workbook.sheet_names()[0].clone();
    let range = workbook.worksheet_range(&sheet_name)?;
    
    // Выводим содержимое
    for row in range.rows() {
        for cell in row {
            print!("{:?}\t", cell);
        }
        println!();
    }
    
    Ok(())
}

Этот код открывает файл data.xlsx, читает первый лист и выводит все ячейки в консоль. Обратите внимание на использование open_workbook — универсальной функции для открытия файлов любого поддерживаемого формата.

4. Основные методы и функции

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("report.xlsx").expect("Cannot open file");
    println!("File opened successfully");
}

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
    let names = workbook.sheet_names();
    println!("Листы: {:?}", names);
}

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
    let range = workbook.worksheet_range("Sheet1").unwrap();
    println!("Загружено {} строк", range.height());
}

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
    let range = workbook.worksheet_range("Sheet1").unwrap();
    
    for (i, row) in range.rows().enumerate() {
        println!("Строка {}: {} ячеек", i, row.len());
    }
}

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
    let range = workbook.worksheet_range("Sheet1").unwrap();
    
    for (data, cell) in range.cells() {
        println!("Ячейка ({}, {}): {:?}", cell.row, cell.col, data);
    }
}

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
    let range = workbook.worksheet_range("Sheet1").unwrap();
    
    if let Some(value) = range.get_value(0, 0) {
        println!("Значение A1: {:?}", value);
    }
}

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
    let range = workbook.worksheet_range("Sheet1").unwrap();
    
    println!("Таблица {}x{}", range.height(), range.width());
}

use calamine::{open_workbook, Xlsx, Data};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
    let range = workbook.worksheet_range("Sheet1").unwrap();
    
    for row in range.rows() {
        if let Some(name) = row[0].get_string() {
            if let Some(salary) = row[1].get_float() {
                println!("{}: {}", name, salary);
            }
        }
    }
}

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("formulas.xlsx").unwrap();
    let formulas = workbook.worksheet_formula("Sheet1").unwrap();
    
    for (formula, cell) in formulas.cells() {
        println!("Ячейка ({}, {}): {}", cell.row, cell.col, formula);
    }
}

use calamine::{open_workbook, Xlsx};

fn main() {
    let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
    
    while workbook.has_next_sheet() {
        workbook.next_sheet().unwrap();
        let range = workbook.worksheet_range_at(workbook.current_sheet_index().unwrap()).unwrap();
        println!("Лист {}: {} строк", workbook.current_sheet_index().unwrap(), range.height());
    }
}

5. Реальный практический пример

Ниже представлен полноценный пример программы, которая читает Excel-файл с данными о сотрудниках, фильтрует их по отделу и выводит статистику. Файл employees.xlsx содержит столбцы: Name, Department, Salary, HireDate.

use calamine::{open_workbook, Reader, Xlsx, Data};
use std::collections::HashMap;

#[derive(Debug)]
struct Employee {
    name: String,
    department: String,
    salary: f64,
    hire_date: String,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Открываем файл
    let mut workbook: Xlsx<_> = open_workbook("employees.xlsx")?;
    let sheet_name = workbook.sheet_names()[0].clone();
    let range = workbook.worksheet_range(&sheet_name)?;
    
    // 2. Парсим данные
    let mut employees: Vec<Employee> = Vec::new();
    let mut errors: Vec<String> = Vec::new();
    
    for (row_idx, row) in range.rows().enumerate().skip(1) { // Пропускаем заголовок
        if row.len() < 4 {
            errors.push(format!("Строка {}: недостаточно столбцов", row_idx + 1));
            continue;
        }
        
        let name = match row[0].get_string() {
            Some(s) => s.clone(),
            None => {
                errors.push(format!("Строка {}: имя не является строкой", row_idx + 1));
                continue;
            }
        };
        
        let department = match row[1].get_string() {
            Some(s) => s.clone(),
            None => {
                errors.push(format!("Строка {}: отдел не является строкой", row_idx + 1));
                continue;
            }
        };
        
        let salary = match row[2].get_float() {
            Some(f) => f,
            None => {
                errors.push(format!("Строка