Table, TableRow, And TableCell¶

featherdoc::Table edits Word table structure and table-level metadata. featherdoc::TableRow edits row metadata and visible cell text. featherdoc::TableCell edits cell content, size, merge state, borders, shading, margins, and paragraphs.

Indexing, Units, And Return Semantics¶

Table APIs use zero-based indexes. row_index addresses visible table rows, cell_index addresses visible cells in that row, and grid_column addresses the resolved Word grid column after spans are considered. Width, indent, margin, and spacing values use twips. Methods returning std::optional<T> return an empty value when the target cannot be resolved; methods returning bool report whether the table XML was changed.

Common Tasks¶

Use these entry points for common table workflows:

Create a table: call Document::append_table(...) or TemplatePart::append_table(...).
Locate cells safely: use find_row(...), find_cell(...), or find_cell_by_grid_column(...) and check the returned std::optional.
Fill a rectangular data region: use set_row_texts(...), set_rows_texts(...), or set_cell_block_texts(...).
Make layout deterministic: set table_layout_mode::fixed, set_width_twips(...), and set_column_width_twips(...).
Format row or cell details: use TableRow for repeat-header and height metadata, and TableCell for merge, shading, margins, borders, and paragraph content.

Success And Failure Semantics¶

Return shape	Success	Failure or no-op
`std::optional<TableRow>`	Contains a row handle for an existing visible row.	Empty when the row index is outside the current table.
`std::optional<TableCell>`	Contains a cell handle after visible-cell or grid-column resolution.	Empty when the row, visible cell, or resolved grid column is unavailable.
`bool`	`true` means every requested cell/layout/border mutation was applied.	`false` means at least one target was missing, invalid, or unchanged.
`TableRow` / `TableCell`	Returned handles point at inserted or appended table nodes.	Treat the returned handle as the editing entry for the new row or cell.
`std::optional<T>` inspection	Contains existing table, row, or cell metadata.	Empty means the requested metadata is not present or cannot be resolved.

Short Example¶

auto table = doc.body_template().append_table(2, 2);
table.set_row_texts(0, {"Name", "Status"});
table.set_row_texts(1, {"Ada", "Approved"});

if (auto cell = table.find_cell(1, 1)) {
    cell->set_fill_color("D9EAF7");
}

Typed Signature Guide¶

Signature	Parameters	Return semantics
`std::optional<TableRow> find_row(std::size_t row_index)`	`row_index`: zero-based visible row index.	Empty when the row does not exist.
`std::optional<TableCell> find_cell(std::size_t row_index, std::size_t cell_index)`	`row_index`: row index. `cell_index`: visible cell index in that row.	Empty when the row or cell cannot be resolved.
`std::optional<TableCell> find_cell_by_grid_column(std::size_t row_index, std::size_t grid_column)`	`row_index`: row index. `grid_column`: resolved Word grid column.	Empty when the grid column maps to no visible cell.
`bool set_cell_text(std::size_t row_index, std::size_t cell_index, const std::string &text)`	`row_index` and `cell_index`: visible cell location. `text`: replacement text.	`true` when the target cell text was replaced.
`bool set_rows_texts(std::size_t start_row_index, const std::vector<std::vector<std::string>> &rows)`	`start_row_index`: first target row. `rows`: row/cell text matrix.	`true` when every addressed cell in the block was updated.
`bool set_cell_block_texts(std::size_t start_row_index, std::size_t start_cell_index, const std::vector<std::vector<std::string>> &rows)`	`start_row_index` and `start_cell_index`: block origin. `rows`: rectangular text matrix.	`true` when the addressed rectangular block was updated.
`bool set_column_width_twips(std::size_t column_index, std::uint32_t width_twips)`	`column_index`: zero-based grid column. `width_twips`: column width in twips.	`true` when the grid column width was updated.
`bool set_border(table_border_edge edge, border_definition border)`	`edge`: table border edge. `border`: style, size, color, and spacing.	`true` when the border definition was written.
`bool TableRow::set_texts(const std::vector<std::string> &texts)`	`texts`: visible cell texts for the current row.	`true` when all provided cells were updated.
`bool TableCell::merge_right(std::size_t additional_cells = 1U)`	`additional_cells`: count of cells to merge to the right.	`true` when horizontal merge metadata was applied.
`bool TableCell::merge_down(std::size_t additional_rows = 1U)`	`additional_rows`: count of rows to merge downward.	`true` when vertical merge metadata was applied.
`bool TableCell::set_margin_twips(cell_margin_edge edge, std::uint32_t margin_twips)`	`edge`: cell margin edge. `margin_twips`: margin value in twips.	`true` when the cell margin was updated.

Table Structure And Lookup¶

Method	Returns	Purpose
`next()`	`Table &`	Advance the table iterator to the next table.
`has_next() const`	`bool`	Check whether the table iterator can advance.
`rows()`	`TableRow &`	Access the row iterator for this table.
`find_row(row_index)`	`std::optional<TableRow>`	Look up a row by zero-based row index.
`find_cell(row_index, cell_index)`	`std::optional<TableCell>`	Look up a visible cell by row and visible cell index.
`find_cell_by_grid_column(row_index, grid_column)`	`std::optional<TableCell>`	Look up a cell by resolved grid column.
`set_cell_text(row_index, cell_index, text)`	`bool`	Replace visible cell text.
`set_cell_text_by_grid_column(row_index, grid_column, text)`	`bool`	Replace cell text by resolved grid column.
`set_row_texts(row_index, texts)`	`bool`	Replace visible cell text for one row.
`set_rows_texts(start_row_index, rows)`	`bool`	Replace a rectangular row block.
`set_cell_block_texts(start_row_index, start_cell_index, rows)`	`bool`	Replace a rectangular cell block from a row/cell origin.
`append_row(std::size_t cell_count = 1U)`	`TableRow`	Append a row with the requested number of cells.

Table Layout, Style, And Borders¶

Method	Returns	Purpose
`width_twips() const`	`std::optional<std::uint32_t>`	Read table width.
`set_width_twips(width_twips)`	`bool`	Set table width in twips.
`column_width_twips(column_index) const`	`std::optional<std::uint32_t>`	Read one grid column width.
`set_column_width_twips(column_index, width_twips)`	`bool`	Set one grid column width.
`layout_mode() const`	`std::optional<table_layout_mode>`	Read autofit or fixed layout mode.
`set_layout_mode(table_layout_mode layout_mode)`	`bool`	Set table layout mode.
`alignment() const`	`std::optional<table_alignment>`	Read table alignment.
`set_alignment(table_alignment alignment)`	`bool`	Set table alignment.
`indent_twips() const`	`std::optional<std::uint32_t>`	Read table indent.
`set_indent_twips(indent_twips)`	`bool`	Set table indent.
`cell_spacing_twips() const`	`std::optional<std::uint32_t>`	Read spacing between table cells.
`set_cell_spacing_twips(spacing_twips)`	`bool`	Set spacing between table cells.
`position() const`	`std::optional<table_position>`	Read floating table position metadata.
`set_position(table_position position)`	`bool`	Set floating table position metadata.
`style_id() const`	`std::optional<std::string>`	Read table style id.
`set_style_id(style_id)`	`bool`	Set table style id.
`style_look() const`	`std::optional<table_style_look>`	Read table style look flags.
`set_style_look(table_style_look style_look)`	`bool`	Set table style look flags.
`border(table_border_edge edge) const`	`std::optional<border_inspection_summary>`	Read one table border edge.
`set_border(table_border_edge edge, border_definition border)`	`bool`	Set one table border edge.

TableRow¶

Method	Returns	Purpose
`cells()`	`TableCell &`	Access the cell iterator for this row.
`find_cell(cell_index)`	`std::optional<TableCell>`	Look up a visible cell by index.
`find_cell_by_grid_column(grid_column)`	`std::optional<TableCell>`	Look up a cell by resolved grid column.
`height_twips() const`	`std::optional<std::uint32_t>`	Read row height.
`height_rule() const`	`std::optional<row_height_rule>`	Read the row height rule.
`set_height_twips(height_twips, row_height_rule)`	`bool`	Set row height and rule.
`cant_split() const`	`bool`	Check whether the row is prevented from splitting across pages.
`set_cant_split()` / `clear_cant_split()`	`bool`	Toggle row split prevention.
`repeats_header() const`	`bool`	Check whether this row repeats as a header row.
`set_repeats_header()` / `clear_repeats_header()`	`bool`	Toggle repeated header row metadata.
`set_texts(texts)`	`bool`	Replace all visible cell text in this row.
`insert_row_before()` / `insert_row_after()`	`TableRow`	Insert a row next to the current row.
`append_cell()`	`TableCell`	Append a cell to this row.

TableCell¶

Method	Returns	Purpose
`paragraphs()`	`Paragraph &`	Access paragraphs inside the cell.
`get_text() const`	`std::string`	Read flattened cell text.
`set_text(const std::string &text) const`	`bool`	Replace cell text.
`insert_cell_before()` / `insert_cell_after()`	`TableCell`	Insert a cell next to the current cell.
`width_twips() const`	`std::optional<std::uint32_t>`	Read cell width.
`set_width_twips(width_twips)`	`bool`	Set cell width in twips.
`column_span() const`	`std::size_t`	Read horizontal span.
`column_index() const`	`std::optional<std::size_t>`	Read resolved grid column index.
`merge_right(additional_cells = 1U)`	`bool`	Horizontally merge with cells to the right.
`merge_down(additional_rows = 1U)`	`bool`	Vertically merge with cells below.
`unmerge_right()` / `unmerge_down()`	`bool`	Remove horizontal or vertical merge state.
`vertical_merge() const`	`cell_vertical_merge`	Read vertical merge state.
`row_span() const`	`std::size_t`	Read vertical span.
`vertical_alignment() const`	`std::optional<cell_vertical_alignment>`	Read cell vertical alignment.
`set_vertical_alignment(alignment)`	`bool`	Set cell vertical alignment.
`text_direction() const`	`std::optional<cell_text_direction>`	Read text direction.
`set_text_direction(direction)`	`bool`	Set text direction.
`fill_color() const`	`std::optional<std::string>`	Read cell shading color.
`set_fill_color(fill_color)`	`bool`	Set cell shading color.
`margin_twips(cell_margin_edge edge) const`	`std::optional<std::uint32_t>`	Read one cell margin.
`set_margin_twips(edge, margin_twips)`	`bool`	Set one cell margin.
`border(cell_border_edge edge) const`	`std::optional<border_inspection_summary>`	Read one cell border edge.
`set_border(cell_border_edge edge, border_definition border)`	`bool`	Set one cell border edge.

Example¶

auto table = doc.body_template().append_table(2, 3);
table.set_layout_mode(featherdoc::table_layout_mode::fixed);
table.set_width_twips(9000);
table.set_row_texts(0, {"SKU", "Name", "Quantity"});

auto header = table.find_row(0);
if (header) {
    header->set_repeats_header();
}

auto sku = table.find_cell(0, 0);
if (sku) {
    sku->set_fill_color("D9EAF7");
    sku->set_vertical_alignment(featherdoc::cell_vertical_alignment::center);
}