Skip to main content

ExcelTable

office_toolkit::excel

Struct ExcelTable 

Source 
pub struct ExcelTable {
    pub name: String,
    pub range: String,
    pub columns: Vec<TableColumn>,
    pub show_totals_row: bool,
    pub sort_state: Option<SortState>,
    pub table_style_name: Option<String>,
}
Expand description

A structured (ListObject) table (<table>, CT_Table) — extended for per-column calculated-column formulas and totals-row functions, and for table_style_name.

Fields§

§name: String

The table’s name, shown in Excel’s Name Manager/Table Design tab (must be unique within the workbook, not validated here).

§range: String

The table’s full range, header row included (e.g. "A1:D6").

§columns: Vec<TableColumn>

The table’s columns, in order, matching the header row’s actual cell text (not written into <sheetData> by this crate — the caller is responsible for the header row’s own cell values matching each column’s name, same “caller keeps the two in sync” posture as ConditionalFormattingRule::range referencing real cells).

§show_totals_row: bool

Whether the table shows a totals row as its last row.

§sort_state: Option<SortState>

This table’s remembered sort order (<sortState>, CT_SortState). Confirmed against sml.xsd: under <table> (CT_Table’s own sequence), sortState is a direct sibling of autoFilter, not nested inside it — distinct from Sheet::sort_state, which is nested inside a plain worksheet-level <autoFilter> (CT_AutoFilter’s own sequence puts sortState after filterColumn*). Storage only: writing this records what Excel would show if the user reopened the table’s sort dialog, it does not itself reorder sheet.rows — the caller remains responsible for the data actually being in that order, same “caller keeps things in sync” posture as AutoFilterColumn.

§table_style_name: Option<String>

The named table style applied to this table (<tableStyleInfo name="..">). None keeps this crate’s own long-standing default, TableStyleMedium2 (Excel’s built-in “Table Style Medium 2”, the first entry in its table style gallery) — same behavior as before this point existed. Some can name either one of Excel’s own dozens of built-in styles (e.g. "TableStyleLight9") or a custom TableStyle declared in Workbook::table_styles — this crate does not itself validate that a Some name actually resolves to something Excel recognizes, same “caller’s responsibility” posture as elsewhere (e.g. Sheet.name’s character-limit note).

Implementations§

Source§

impl ExcelTable

Source

pub fn new<S>( name: impl Into<String>, range: impl Into<String>, columns: Vec<S>, ) -> ExcelTable
where S: Into<String>,

Creates a table with no totals row, from a list of plain column names (no calculated-column formula, no totals-row function on any column yet) — the common case. Use ExcelTable::with_columns instead for full control over each TableColumn.

Examples found in repository?
examples/xlsx_tables.rs (lines 23-27)
16fn main() -> office_toolkit::Result<()> {
17    let path = output_path("xlsx_tables.xlsx");
18
19    let plain_sheet = Sheet::new("Plain table")
20        .with_row(Row::new().with_text("Name").with_text("Score"))
21        .with_row(Row::new().with_text("Alice").with_number(92.0))
22        .with_row(Row::new().with_text("Bob").with_number(87.0))
23        .with_table(ExcelTable::new(
24            "ScoresTable",
25            "A1:B3",
26            vec!["Name", "Score"],
27        ));
28
29    let calculated_sheet = Sheet::new("Calculated and totals")
30        .with_row(
31            Row::new()
32                .with_text("Item")
33                .with_text("Qty")
34                .with_text("Unit price")
35                .with_text("Line total"),
36        )
37        .with_row(
38            Row::new()
39                .with_text("Widget")
40                .with_number(3.0)
41                .with_number(9.99)
42                .with_cell(Cell::formula("B2*C2").with_cached_value(29.97)),
43        )
44        .with_row(
45            Row::new()
46                .with_text("Gadget")
47                .with_number(2.0)
48                .with_number(19.99)
49                .with_cell(Cell::formula("B3*C3").with_cached_value(39.98)),
50        )
51        .with_row(Row::new().with_cell(Cell::text("Total")))
52        .with_table(
53            ExcelTable::with_columns(
54                "OrdersTable",
55                "A1:D4",
56                vec![
57                    TableColumn::new("Item"),
58                    TableColumn::new("Qty").with_totals_row_function(TotalsRowFunction::Sum),
59                    TableColumn::new("Unit price"),
60                    TableColumn::new("Line total")
61                        .with_calculated_formula(
62                            "OrdersTable[[#This Row],[Qty]]*OrdersTable[[#This Row],[Unit price]]",
63                        )
64                        .with_totals_row_function(TotalsRowFunction::Sum),
65                ],
66            )
67            .with_totals_row(true),
68        );
69
70    let styled_sheet = Sheet::new("Custom style and sort")
71        .with_row(Row::new().with_text("City").with_text("Population"))
72        .with_row(Row::new().with_text("Springfield").with_number(120_000.0))
73        .with_row(Row::new().with_text("Shelbyville").with_number(95_000.0))
74        .with_table(
75            ExcelTable::new("CitiesTable", "A1:B3", vec!["City", "Population"])
76                .with_table_style_name("CustomTableStyle")
77                .with_sort_state(
78                    SortState::new("A2:B3")
79                        .with_condition(SortCondition::new("B2:B3").with_descending(true)),
80                ),
81        );
82
83    let workbook = Workbook::new()
84        .with_table_style(
85            TableStyle::new("CustomTableStyle")
86                .with_element(TableStyleElement::new(
87                    TableStyleElementType::HeaderRow,
88                    CellFormat::new()
89                        .with_bold(true)
90                        .with_fill_color("FF2E74B5")
91                        .with_font_color("FFFFFFFF"),
92                ))
93                .with_element(TableStyleElement::new(
94                    TableStyleElementType::FirstRowStripe,
95                    CellFormat::new().with_fill_color("FFF2F2F2"),
96                )),
97        )
98        .with_sheet(plain_sheet)
99        .with_sheet(calculated_sheet)
100        .with_sheet(styled_sheet);
101
102    workbook.save_to_file(&path)?;
103    println!("Wrote {}", path.display());
104    Ok(())
105}
Source

pub fn with_columns( name: impl Into<String>, range: impl Into<String>, columns: Vec<TableColumn>, ) -> ExcelTable

Creates a table from a list of fully-specified TableColumns.

Examples found in repository?
examples/xlsx_tables.rs (lines 53-66)
16fn main() -> office_toolkit::Result<()> {
17    let path = output_path("xlsx_tables.xlsx");
18
19    let plain_sheet = Sheet::new("Plain table")
20        .with_row(Row::new().with_text("Name").with_text("Score"))
21        .with_row(Row::new().with_text("Alice").with_number(92.0))
22        .with_row(Row::new().with_text("Bob").with_number(87.0))
23        .with_table(ExcelTable::new(
24            "ScoresTable",
25            "A1:B3",
26            vec!["Name", "Score"],
27        ));
28
29    let calculated_sheet = Sheet::new("Calculated and totals")
30        .with_row(
31            Row::new()
32                .with_text("Item")
33                .with_text("Qty")
34                .with_text("Unit price")
35                .with_text("Line total"),
36        )
37        .with_row(
38            Row::new()
39                .with_text("Widget")
40                .with_number(3.0)
41                .with_number(9.99)
42                .with_cell(Cell::formula("B2*C2").with_cached_value(29.97)),
43        )
44        .with_row(
45            Row::new()
46                .with_text("Gadget")
47                .with_number(2.0)
48                .with_number(19.99)
49                .with_cell(Cell::formula("B3*C3").with_cached_value(39.98)),
50        )
51        .with_row(Row::new().with_cell(Cell::text("Total")))
52        .with_table(
53            ExcelTable::with_columns(
54                "OrdersTable",
55                "A1:D4",
56                vec![
57                    TableColumn::new("Item"),
58                    TableColumn::new("Qty").with_totals_row_function(TotalsRowFunction::Sum),
59                    TableColumn::new("Unit price"),
60                    TableColumn::new("Line total")
61                        .with_calculated_formula(
62                            "OrdersTable[[#This Row],[Qty]]*OrdersTable[[#This Row],[Unit price]]",
63                        )
64                        .with_totals_row_function(TotalsRowFunction::Sum),
65                ],
66            )
67            .with_totals_row(true),
68        );
69
70    let styled_sheet = Sheet::new("Custom style and sort")
71        .with_row(Row::new().with_text("City").with_text("Population"))
72        .with_row(Row::new().with_text("Springfield").with_number(120_000.0))
73        .with_row(Row::new().with_text("Shelbyville").with_number(95_000.0))
74        .with_table(
75            ExcelTable::new("CitiesTable", "A1:B3", vec!["City", "Population"])
76                .with_table_style_name("CustomTableStyle")
77                .with_sort_state(
78                    SortState::new("A2:B3")
79                        .with_condition(SortCondition::new("B2:B3").with_descending(true)),
80                ),
81        );
82
83    let workbook = Workbook::new()
84        .with_table_style(
85            TableStyle::new("CustomTableStyle")
86                .with_element(TableStyleElement::new(
87                    TableStyleElementType::HeaderRow,
88                    CellFormat::new()
89                        .with_bold(true)
90                        .with_fill_color("FF2E74B5")
91                        .with_font_color("FFFFFFFF"),
92                ))
93                .with_element(TableStyleElement::new(
94                    TableStyleElementType::FirstRowStripe,
95                    CellFormat::new().with_fill_color("FFF2F2F2"),
96                )),
97        )
98        .with_sheet(plain_sheet)
99        .with_sheet(calculated_sheet)
100        .with_sheet(styled_sheet);
101
102    workbook.save_to_file(&path)?;
103    println!("Wrote {}", path.display());
104    Ok(())
105}
Source

pub fn with_totals_row(self, show: bool) -> ExcelTable

Sets whether the table shows a totals row and returns it for chaining.

Examples found in repository?
examples/xlsx_tables.rs (line 67)
16fn main() -> office_toolkit::Result<()> {
17    let path = output_path("xlsx_tables.xlsx");
18
19    let plain_sheet = Sheet::new("Plain table")
20        .with_row(Row::new().with_text("Name").with_text("Score"))
21        .with_row(Row::new().with_text("Alice").with_number(92.0))
22        .with_row(Row::new().with_text("Bob").with_number(87.0))
23        .with_table(ExcelTable::new(
24            "ScoresTable",
25            "A1:B3",
26            vec!["Name", "Score"],
27        ));
28
29    let calculated_sheet = Sheet::new("Calculated and totals")
30        .with_row(
31            Row::new()
32                .with_text("Item")
33                .with_text("Qty")
34                .with_text("Unit price")
35                .with_text("Line total"),
36        )
37        .with_row(
38            Row::new()
39                .with_text("Widget")
40                .with_number(3.0)
41                .with_number(9.99)
42                .with_cell(Cell::formula("B2*C2").with_cached_value(29.97)),
43        )
44        .with_row(
45            Row::new()
46                .with_text("Gadget")
47                .with_number(2.0)
48                .with_number(19.99)
49                .with_cell(Cell::formula("B3*C3").with_cached_value(39.98)),
50        )
51        .with_row(Row::new().with_cell(Cell::text("Total")))
52        .with_table(
53            ExcelTable::with_columns(
54                "OrdersTable",
55                "A1:D4",
56                vec![
57                    TableColumn::new("Item"),
58                    TableColumn::new("Qty").with_totals_row_function(TotalsRowFunction::Sum),
59                    TableColumn::new("Unit price"),
60                    TableColumn::new("Line total")
61                        .with_calculated_formula(
62                            "OrdersTable[[#This Row],[Qty]]*OrdersTable[[#This Row],[Unit price]]",
63                        )
64                        .with_totals_row_function(TotalsRowFunction::Sum),
65                ],
66            )
67            .with_totals_row(true),
68        );
69
70    let styled_sheet = Sheet::new("Custom style and sort")
71        .with_row(Row::new().with_text("City").with_text("Population"))
72        .with_row(Row::new().with_text("Springfield").with_number(120_000.0))
73        .with_row(Row::new().with_text("Shelbyville").with_number(95_000.0))
74        .with_table(
75            ExcelTable::new("CitiesTable", "A1:B3", vec!["City", "Population"])
76                .with_table_style_name("CustomTableStyle")
77                .with_sort_state(
78                    SortState::new("A2:B3")
79                        .with_condition(SortCondition::new("B2:B3").with_descending(true)),
80                ),
81        );
82
83    let workbook = Workbook::new()
84        .with_table_style(
85            TableStyle::new("CustomTableStyle")
86                .with_element(TableStyleElement::new(
87                    TableStyleElementType::HeaderRow,
88                    CellFormat::new()
89                        .with_bold(true)
90                        .with_fill_color("FF2E74B5")
91                        .with_font_color("FFFFFFFF"),
92                ))
93                .with_element(TableStyleElement::new(
94                    TableStyleElementType::FirstRowStripe,
95                    CellFormat::new().with_fill_color("FFF2F2F2"),
96                )),
97        )
98        .with_sheet(plain_sheet)
99        .with_sheet(calculated_sheet)
100        .with_sheet(styled_sheet);
101
102    workbook.save_to_file(&path)?;
103    println!("Wrote {}", path.display());
104    Ok(())
105}
Source

pub fn with_sort_state(self, sort_state: SortState) -> ExcelTable

Sets this table’s remembered sort order and returns it for chaining.

Examples found in repository?
examples/xlsx_tables.rs (lines 77-80)
16fn main() -> office_toolkit::Result<()> {
17    let path = output_path("xlsx_tables.xlsx");
18
19    let plain_sheet = Sheet::new("Plain table")
20        .with_row(Row::new().with_text("Name").with_text("Score"))
21        .with_row(Row::new().with_text("Alice").with_number(92.0))
22        .with_row(Row::new().with_text("Bob").with_number(87.0))
23        .with_table(ExcelTable::new(
24            "ScoresTable",
25            "A1:B3",
26            vec!["Name", "Score"],
27        ));
28
29    let calculated_sheet = Sheet::new("Calculated and totals")
30        .with_row(
31            Row::new()
32                .with_text("Item")
33                .with_text("Qty")
34                .with_text("Unit price")
35                .with_text("Line total"),
36        )
37        .with_row(
38            Row::new()
39                .with_text("Widget")
40                .with_number(3.0)
41                .with_number(9.99)
42                .with_cell(Cell::formula("B2*C2").with_cached_value(29.97)),
43        )
44        .with_row(
45            Row::new()
46                .with_text("Gadget")
47                .with_number(2.0)
48                .with_number(19.99)
49                .with_cell(Cell::formula("B3*C3").with_cached_value(39.98)),
50        )
51        .with_row(Row::new().with_cell(Cell::text("Total")))
52        .with_table(
53            ExcelTable::with_columns(
54                "OrdersTable",
55                "A1:D4",
56                vec![
57                    TableColumn::new("Item"),
58                    TableColumn::new("Qty").with_totals_row_function(TotalsRowFunction::Sum),
59                    TableColumn::new("Unit price"),
60                    TableColumn::new("Line total")
61                        .with_calculated_formula(
62                            "OrdersTable[[#This Row],[Qty]]*OrdersTable[[#This Row],[Unit price]]",
63                        )
64                        .with_totals_row_function(TotalsRowFunction::Sum),
65                ],
66            )
67            .with_totals_row(true),
68        );
69
70    let styled_sheet = Sheet::new("Custom style and sort")
71        .with_row(Row::new().with_text("City").with_text("Population"))
72        .with_row(Row::new().with_text("Springfield").with_number(120_000.0))
73        .with_row(Row::new().with_text("Shelbyville").with_number(95_000.0))
74        .with_table(
75            ExcelTable::new("CitiesTable", "A1:B3", vec!["City", "Population"])
76                .with_table_style_name("CustomTableStyle")
77                .with_sort_state(
78                    SortState::new("A2:B3")
79                        .with_condition(SortCondition::new("B2:B3").with_descending(true)),
80                ),
81        );
82
83    let workbook = Workbook::new()
84        .with_table_style(
85            TableStyle::new("CustomTableStyle")
86                .with_element(TableStyleElement::new(
87                    TableStyleElementType::HeaderRow,
88                    CellFormat::new()
89                        .with_bold(true)
90                        .with_fill_color("FF2E74B5")
91                        .with_font_color("FFFFFFFF"),
92                ))
93                .with_element(TableStyleElement::new(
94                    TableStyleElementType::FirstRowStripe,
95                    CellFormat::new().with_fill_color("FFF2F2F2"),
96                )),
97        )
98        .with_sheet(plain_sheet)
99        .with_sheet(calculated_sheet)
100        .with_sheet(styled_sheet);
101
102    workbook.save_to_file(&path)?;
103    println!("Wrote {}", path.display());
104    Ok(())
105}
Source

pub fn with_table_style_name(self, name: impl Into<String>) -> ExcelTable

Sets this table’s named style and returns it for chaining. See table_style_name’s doc comment.

Examples found in repository?
examples/xlsx_tables.rs (line 76)
16fn main() -> office_toolkit::Result<()> {
17    let path = output_path("xlsx_tables.xlsx");
18
19    let plain_sheet = Sheet::new("Plain table")
20        .with_row(Row::new().with_text("Name").with_text("Score"))
21        .with_row(Row::new().with_text("Alice").with_number(92.0))
22        .with_row(Row::new().with_text("Bob").with_number(87.0))
23        .with_table(ExcelTable::new(
24            "ScoresTable",
25            "A1:B3",
26            vec!["Name", "Score"],
27        ));
28
29    let calculated_sheet = Sheet::new("Calculated and totals")
30        .with_row(
31            Row::new()
32                .with_text("Item")
33                .with_text("Qty")
34                .with_text("Unit price")
35                .with_text("Line total"),
36        )
37        .with_row(
38            Row::new()
39                .with_text("Widget")
40                .with_number(3.0)
41                .with_number(9.99)
42                .with_cell(Cell::formula("B2*C2").with_cached_value(29.97)),
43        )
44        .with_row(
45            Row::new()
46                .with_text("Gadget")
47                .with_number(2.0)
48                .with_number(19.99)
49                .with_cell(Cell::formula("B3*C3").with_cached_value(39.98)),
50        )
51        .with_row(Row::new().with_cell(Cell::text("Total")))
52        .with_table(
53            ExcelTable::with_columns(
54                "OrdersTable",
55                "A1:D4",
56                vec![
57                    TableColumn::new("Item"),
58                    TableColumn::new("Qty").with_totals_row_function(TotalsRowFunction::Sum),
59                    TableColumn::new("Unit price"),
60                    TableColumn::new("Line total")
61                        .with_calculated_formula(
62                            "OrdersTable[[#This Row],[Qty]]*OrdersTable[[#This Row],[Unit price]]",
63                        )
64                        .with_totals_row_function(TotalsRowFunction::Sum),
65                ],
66            )
67            .with_totals_row(true),
68        );
69
70    let styled_sheet = Sheet::new("Custom style and sort")
71        .with_row(Row::new().with_text("City").with_text("Population"))
72        .with_row(Row::new().with_text("Springfield").with_number(120_000.0))
73        .with_row(Row::new().with_text("Shelbyville").with_number(95_000.0))
74        .with_table(
75            ExcelTable::new("CitiesTable", "A1:B3", vec!["City", "Population"])
76                .with_table_style_name("CustomTableStyle")
77                .with_sort_state(
78                    SortState::new("A2:B3")
79                        .with_condition(SortCondition::new("B2:B3").with_descending(true)),
80                ),
81        );
82
83    let workbook = Workbook::new()
84        .with_table_style(
85            TableStyle::new("CustomTableStyle")
86                .with_element(TableStyleElement::new(
87                    TableStyleElementType::HeaderRow,
88                    CellFormat::new()
89                        .with_bold(true)
90                        .with_fill_color("FF2E74B5")
91                        .with_font_color("FFFFFFFF"),
92                ))
93                .with_element(TableStyleElement::new(
94                    TableStyleElementType::FirstRowStripe,
95                    CellFormat::new().with_fill_color("FFF2F2F2"),
96                )),
97        )
98        .with_sheet(plain_sheet)
99        .with_sheet(calculated_sheet)
100        .with_sheet(styled_sheet);
101
102    workbook.save_to_file(&path)?;
103    println!("Wrote {}", path.display());
104    Ok(())
105}

Trait Implementations§

Source§

impl Clone for ExcelTable

Source§

fn clone(&self) -> ExcelTable

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for ExcelTable

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl PartialEq for ExcelTable

Source§

fn eq(&self, other: &ExcelTable) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for ExcelTable

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.