excelerate 0.15.0

Read, write and recalculate spreadsheets: xlsx, xls, ods, csv, html, and a 518-function formula engine
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
//! The sheet around the cells: its extent, merges, row and column geometry,
//! how it is shown, and how it and the workbook are locked.

#[cfg(feature = "write")]
use super::convert::at_index;
use super::convert::{col_at, object, opt_str, row_at};
use super::{Book, js};
use crate::coordinate::Col;
#[cfg(feature = "write")]
use crate::coordinate::Range;
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
impl Book {
    /// The used range of a sheet as `A1:D9`, or `undefined` if it holds
    /// nothing. This is the rectangle to walk; the sheet itself is sparse.
    #[wasm_bindgen(js_name = usedRange)]
    #[must_use]
    pub fn used_range(&self, sheet: usize) -> Option<String> {
        self.workbook
            .sheet(sheet)?
            .dimension()
            .map(|r| r.to_string())
    }

    /// The used range of a sheet as `"A1:D20"` without walking the rows;
    /// `undefined` for an empty sheet.
    ///
    /// Rows are exact, columns an upper bound: removing a cell never narrows
    /// them. `usedRange` answers the same until a cell in an edge column is
    /// removed, and walks the rows after that to give the exact rectangle.
    #[wasm_bindgen(js_name = usedRangeHint)]
    pub fn used_range_hint(&self, sheet: usize) -> Result<Option<String>, JsError> {
        Ok(self
            .sheet_of(sheet)?
            .dimension_hint()
            .map(|r| r.to_string()))
    }

    /// The merged areas of a sheet, as `"A1:C1"` strings in the order the file
    /// lists them.
    #[wasm_bindgen(js_name = mergedRanges)]
    pub fn merged_ranges(&self, sheet: usize) -> Result<Vec<String>, JsError> {
        Ok(self
            .sheet_of(sheet)?
            .merges
            .iter()
            .map(ToString::to_string)
            .collect())
    }

    /// The merged areas of a sheet as numbers: four per area, `[r1, c1, r2,
    /// c2]`, rows and columns 1-based.
    ///
    /// One typed array instead of a JS string per area, which is what a sheet
    /// carrying three hundred thousand of them needs.
    #[wasm_bindgen(js_name = mergedRangesAt)]
    pub fn merged_ranges_at(&self, sheet: usize) -> Result<js_sys::Uint32Array, JsError> {
        let out: Vec<u32> = self
            .sheet_of(sheet)?
            .merges
            .iter()
            .flat_map(|area| {
                [
                    area.start.row.one_based(),
                    area.start.col.one_based(),
                    area.end.row.one_based(),
                    area.end.col.one_based(),
                ]
            })
            .collect();
        Ok(js_sys::Uint32Array::from(&out[..]))
    }

    /// Whether a sheet has a tab: `"visible"`, `"hidden"` or `"veryHidden"`.
    ///
    /// `sheetNames` lists every sheet, hidden ones included, because that is
    /// what the index of every other call counts.
    #[wasm_bindgen(js_name = sheetVisibility)]
    pub fn sheet_visibility(&self, sheet: usize) -> Result<String, JsError> {
        Ok(self
            .sheet_of(sheet)?
            .visibility
            .as_str()
            .unwrap_or("visible")
            .to_owned())
    }

    /// Whether a row is hidden. `row` is the number a user sees.
    #[wasm_bindgen(js_name = rowHidden)]
    pub fn row_hidden(&self, sheet: usize, row: u32) -> Result<bool, JsError> {
        let at = row_at(row)?;
        Ok(self
            .sheet_of(sheet)?
            .rows
            .get(&at)
            .is_some_and(|props| props.hidden))
    }

    /// How deeply a row is grouped: 0 when it is not, 1 for the outermost
    /// group, and so on. `row` is the number a user sees.
    #[wasm_bindgen(js_name = rowLevel)]
    pub fn row_level(&self, sheet: usize, row: u32) -> Result<u8, JsError> {
        let row = row_at(row)?;
        Ok(self.sheet_of(sheet)?.row_outline_level(row))
    }

    /// The same for a column, named by its letters: `columnLevel(0, "C")`.
    #[wasm_bindgen(js_name = columnLevel)]
    pub fn column_level(&self, sheet: usize, column: &str) -> Result<u8, JsError> {
        let col = Col::from_letters(column).map_err(js)?;
        Ok(self.sheet_of(sheet)?.column_outline_level(col))
    }

    /// The width of a column in characters, or `undefined` when the sheet
    /// leaves it to the default. `column` is 1-based.
    #[wasm_bindgen(js_name = columnWidth)]
    pub fn column_width(&self, sheet: usize, column: u32) -> Result<Option<f64>, JsError> {
        let col = col_at(column)?;
        Ok(self.sheet_of(sheet)?.column_width(col))
    }

    /// The height of a row in points, or `undefined` when the sheet leaves it
    /// to the default. `row` is the number a user sees.
    #[wasm_bindgen(js_name = rowHeight)]
    pub fn row_height(&self, sheet: usize, row: u32) -> Result<Option<f64>, JsError> {
        let at = row_at(row)?;
        Ok(self.sheet_of(sheet)?.row_height(at))
    }

    /// How the sheet is frozen and shown.
    #[wasm_bindgen(js_name = sheetView, unchecked_return_type = "SheetViewInfo")]
    pub fn sheet_view(&self, sheet: usize) -> Result<JsValue, JsError> {
        let view = &self.sheet_of(sheet)?.view;
        let frozen = view
            .pane
            .as_ref()
            .filter(|pane| pane.state != crate::model::PaneState::Split);
        Ok(object(&[
            (
                "frozenRows",
                JsValue::from_f64(frozen.map_or(0.0, |pane| f64::from(pane.y_split))),
            ),
            (
                "frozenColumns",
                JsValue::from_f64(frozen.map_or(0.0, |pane| f64::from(pane.x_split))),
            ),
            (
                "zoom",
                view.zoom_scale
                    .map_or(JsValue::NULL, |z| JsValue::from_f64(f64::from(z))),
            ),
            ("showGridLines", JsValue::from_bool(view.show_grid_lines)),
            (
                "showRowColHeaders",
                JsValue::from_bool(view.show_row_col_headers),
            ),
            ("rightToLeft", JsValue::from_bool(view.right_to_left)),
            (
                "topLeftCell",
                opt_str(view.top_left_cell.map(|at| at.to_string()).as_deref()),
            ),
        ]))
    }

    /// Whether a sheet is locked, and whether the lock has a password.
    #[wasm_bindgen(js_name = sheetProtection, unchecked_return_type = "ProtectionInfo")]
    pub fn sheet_protection(&self, sheet: usize) -> Result<JsValue, JsError> {
        let protection = &self.sheet_of(sheet)?.protection;
        Ok(lock(
            protection.sheet.unwrap_or(false),
            protection.password.is_some(),
        ))
    }

    /// Whether that password unlocks the sheet. `false` for a sheet with no
    /// password on it, and for a hash this crate cannot check.
    #[wasm_bindgen(js_name = verifySheetPassword)]
    pub fn verify_sheet_password(&self, sheet: usize, password: &str) -> Result<bool, JsError> {
        Ok(self
            .sheet_of(sheet)?
            .protection
            .password
            .as_ref()
            .is_some_and(|hash| hash.verify(password)))
    }

    /// Whether the workbook's structure is locked, and whether behind a
    /// password.
    #[wasm_bindgen(js_name = workbookProtection, unchecked_return_type = "ProtectionInfo")]
    #[must_use]
    pub fn workbook_protection(&self) -> JsValue {
        let protection = &self.workbook.protection;
        lock(
            protection.lock_structure.unwrap_or(false),
            protection.workbook_password.is_some(),
        )
    }
}

#[cfg(feature = "write")]
#[wasm_bindgen]
impl Book {
    /// Merges a block of cells: `merge(0, "A1:C1")`.
    pub fn merge(&mut self, sheet: usize, range: &str) -> Result<(), JsError> {
        let area = Range::parse(range).map_err(js)?;
        let merges = &mut self.sheet_mut(sheet)?.merges;
        if !merges.contains(&area) {
            merges.push(area);
        }
        Ok(())
    }

    /// Takes a merge back out. Answers whether there was one.
    pub fn unmerge(&mut self, sheet: usize, range: &str) -> Result<bool, JsError> {
        let area = Range::parse(range).map_err(js)?;
        let merges = &mut self.sheet_mut(sheet)?.merges;
        let before = merges.len();
        merges.retain(|m| *m != area);
        Ok(merges.len() != before)
    }

    /// Gives a sheet a tab or takes it away: `"visible"`, `"hidden"` or
    /// `"veryHidden"`.
    ///
    /// A very hidden sheet is not in the dialog Excel offers for unhiding one.
    /// Either way the sheet keeps its index, which is what every other call
    /// counts.
    #[wasm_bindgen(js_name = setSheetVisibility)]
    pub fn set_sheet_visibility(&mut self, sheet: usize, state: &str) -> Result<(), JsError> {
        if !matches!(state, "visible" | "hidden" | "veryHidden") {
            return Err(JsError::new(
                r#"visibility is "visible", "hidden" or "veryHidden""#,
            ));
        }
        self.sheet_mut(sheet)?.visibility = crate::model::SheetVisibility::parse(state);
        Ok(())
    }

    /// Sets the width of a column in characters of the default font, or gives
    /// it back to the sheet default with `undefined`. `column` is 1-based.
    ///
    /// A run of columns that covered this one is split around it, so the
    /// neighbours keep the width they had.
    #[wasm_bindgen(js_name = setColumnWidth)]
    pub fn set_column_width(
        &mut self,
        sheet: usize,
        column: u32,
        width: Option<f64>,
    ) -> Result<(), JsError> {
        let col = col_at(column)?;
        self.sheet_mut(sheet)?.set_column_width(col, width);
        Ok(())
    }

    /// Sets the height of a row in points, or gives it back to the sheet
    /// default with `undefined`. `row` is the number a user sees.
    #[wasm_bindgen(js_name = setRowHeight)]
    pub fn set_row_height(
        &mut self,
        sheet: usize,
        row: u32,
        height: Option<f64>,
    ) -> Result<(), JsError> {
        let at = row_at(row)?;
        self.sheet_mut(sheet)?.set_row_height(at, height);
        Ok(())
    }

    /// Hides a column, or shows it again. `column` is 1-based.
    #[wasm_bindgen(js_name = setColumnHidden)]
    pub fn set_column_hidden(
        &mut self,
        sheet: usize,
        column: u32,
        hidden: bool,
    ) -> Result<(), JsError> {
        let col = col_at(column)?;
        self.sheet_mut(sheet)?.set_column_hidden(col, hidden);
        Ok(())
    }

    /// Hides a row, or shows it again.
    #[wasm_bindgen(js_name = setRowHidden)]
    pub fn set_row_hidden(&mut self, sheet: usize, row: u32, hidden: bool) -> Result<(), JsError> {
        let at = row_at(row)?;
        self.sheet_mut(sheet)?.set_row_hidden(at, hidden);
        Ok(())
    }

    /// Freezes the first `rows` rows and `columns` columns, so they stay put
    /// while the rest scrolls. `freezePanes(0, 1, 0)` pins the header row;
    /// `freezePanes(0, 0, 0)` unfreezes.
    #[wasm_bindgen(js_name = freezePanes)]
    pub fn freeze_panes(&mut self, sheet: usize, rows: u32, columns: u32) -> Result<(), JsError> {
        use crate::model::{Pane, PanePosition, PaneState};
        let pane = if rows == 0 && columns == 0 {
            None
        } else {
            Some(Pane {
                x_split: columns,
                y_split: rows,
                top_left_cell: Some(at_index(rows + 1, columns + 1)?),
                active_pane: match (rows, columns) {
                    (0, _) => PanePosition::TopRight,
                    (_, 0) => PanePosition::BottomLeft,
                    _ => PanePosition::BottomRight,
                },
                state: PaneState::Frozen,
            })
        };
        self.sheet_mut(sheet)?.view.pane = pane;
        Ok(())
    }

    /// The zoom a reader opens the sheet at, in percent; `undefined` gives it
    /// back to 100.
    #[wasm_bindgen(js_name = setZoom)]
    pub fn set_zoom(&mut self, sheet: usize, percent: Option<u32>) -> Result<(), JsError> {
        if percent.is_some_and(|z| !(10..=400).contains(&z)) {
            return Err(JsError::new("a zoom is between 10 and 400 percent"));
        }
        self.sheet_mut(sheet)?.view.zoom_scale = percent;
        Ok(())
    }

    /// Shows or hides the grid lines, and the row and column headings with
    /// `headers`.
    #[wasm_bindgen(js_name = setShowGridLines)]
    pub fn set_show_grid_lines(
        &mut self,
        sheet: usize,
        show: bool,
        headers: Option<bool>,
    ) -> Result<(), JsError> {
        let view = &mut self.sheet_mut(sheet)?.view;
        view.show_grid_lines = show;
        if let Some(headers) = headers {
            view.show_row_col_headers = headers;
        }
        Ok(())
    }

    /// Locks a sheet against editing, optionally behind a password.
    ///
    /// This is the lock Excel offers under "Protect Sheet": it stops a user
    /// editing, it does not encrypt anything. The password is stored as Excel
    /// stores it - SHA-512 over a random salt, 100,000 spins - and
    /// `verifySheetPassword` checks it back.
    #[wasm_bindgen(js_name = protectSheet)]
    #[expect(
        clippy::needless_pass_by_value,
        reason = "an optional string crosses the wasm boundary owned"
    )]
    pub fn protect_sheet(&mut self, sheet: usize, password: Option<String>) -> Result<(), JsError> {
        let hash = hash(password.as_deref())?;
        let protection = &mut self.sheet_mut(sheet)?.protection;
        protection.sheet = Some(true);
        protection.password = hash;
        Ok(())
    }

    /// Unlocks a sheet, password and all.
    #[wasm_bindgen(js_name = unprotectSheet)]
    pub fn unprotect_sheet(&mut self, sheet: usize) -> Result<(), JsError> {
        self.sheet_mut(sheet)?.protection = crate::model::protection::SheetProtection::default();
        Ok(())
    }

    /// Locks the structure of the workbook: which sheets there are, and their
    /// order. `windows` locks the window layout as well.
    #[wasm_bindgen(js_name = protectWorkbook)]
    #[expect(
        clippy::needless_pass_by_value,
        reason = "an optional string crosses the wasm boundary owned"
    )]
    pub fn protect_workbook(
        &mut self,
        password: Option<String>,
        windows: Option<bool>,
    ) -> Result<(), JsError> {
        let protection = &mut self.workbook.protection;
        protection.workbook_password = hash(password.as_deref())?;
        protection.lock_structure = Some(true);
        protection.lock_windows = windows;
        Ok(())
    }

    /// Unlocks the workbook.
    #[wasm_bindgen(js_name = unprotectWorkbook)]
    pub fn unprotect_workbook(&mut self) {
        self.workbook.protection = crate::model::protection::WorkbookProtection::default();
    }
}

/// `ProtectionInfo`: whether something is locked, and behind a password.
fn lock(locked: bool, has_password: bool) -> JsValue {
    object(&[
        ("locked", JsValue::from_bool(locked)),
        ("hasPassword", JsValue::from_bool(has_password)),
    ])
}

/// A password hashed the way Excel hashes it, if one was given.
#[cfg(feature = "write")]
fn hash(password: Option<&str>) -> Result<Option<crate::model::protection::PasswordHash>, JsError> {
    password
        .map(|word| {
            crate::model::protection::PasswordHash::new(word)
                .ok_or_else(|| JsError::new("the password could not be hashed"))
        })
        .transpose()
}