@spec add_table(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  [String.t()],
  boolean() | nil
) :: :ok | {:error, String.t()}

Adds a new table to a spreadsheet.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet where the table will be created
• table_name - Internal name of the table (must be unique within the workbook)
• display_name - Display name shown to users
• start_cell - Top-left cell of the table range (e.g., "A1")
• end_cell - Bottom-right cell of the table range (e.g., "D10")
• columns - List of column names for the table headers
• has_totals_row - Optional boolean indicating if the table should include a totals row

Examples

# Create a sales data table
{:ok, :ok} = Table.add_table(
  spreadsheet,
  "Sheet1",
  "SalesTable",
  "Sales Data",
  "A1",
  "D10",
  ["Region", "Product", "Sales", "Date"],
  true  # Include totals row
)

Returns {:ok, :ok} on success or {:error, reason} on failure.

@spec add_table_column(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t() | nil,
  String.t() | nil
) :: {:ok, :ok} | {:error, String.t()}

Adds a new column to an existing table.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table to modify
• column_name - Name of the new column
• totals_row_function - Optional function for the totals row ("sum", "count", "average", etc.)
• totals_row_label - Optional custom label for the totals row

Examples

Table.add_table_column(
  spreadsheet,
  "Sheet1",
  "SalesTable",
  "Total",
  "sum",
  "Grand Total"
)

Returns :ok on success or {:error, reason} on failure.

@spec count_tables(UmyaSpreadsheet.Spreadsheet.t(), String.t()) ::
  {:ok, non_neg_integer()} | {:error, String.t()}

Counts the number of tables in a worksheet.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet to count tables in

Examples

{:ok, count} = Table.count_tables(spreadsheet, "Sheet1")
# count = 3

Returns {:ok, integer} with the number of tables on success.

@spec get_table(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, String.t()}

Gets a specific table by name from a worksheet.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table to retrieve

Returns

A map containing table information with keys:

• "name" - Internal table name
• "display_name" - Display name
• "start_cell" - Top-left cell reference
• "end_cell" - Bottom-right cell reference
• "columns" - List of column names
• "has_totals_row" - Boolean indicating if totals row is enabled
• "style_info" - Map with styling information (if table has custom styling)

Examples

{:ok, table} = Table.get_table(spreadsheet, "Sheet1", "SalesTable")
# table = %{"name" => "SalesTable", "display_name" => "Sales Data", ...}

@spec get_table_columns(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  {:ok, [map()]} | {:error, String.t()}

Gets column information for a specific table.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table

Returns

A list of maps, each containing column information with keys:

• "name" - Column name
• "totals_row_label" - Custom label for totals row (if set)
• "totals_row_function" - Function used in totals row (e.g., "sum", "count")

Examples

{:ok, columns} = Table.get_table_columns(spreadsheet, "Sheet1", "SalesTable")
# columns = [%{"name" => "Region", "totals_row_function" => "none"}, ...]

@spec get_table_style(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, String.t()}

Gets table style information for a specific table.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table

Returns

A map containing style information with keys:

• "name" - Style name (e.g., "TableStyleLight1")
• "show_first_column" - Boolean indicating if first column is highlighted
• "show_last_column" - Boolean indicating if last column is highlighted
• "show_row_stripes" - Boolean indicating if row stripes are shown
• "show_column_stripes" - Boolean indicating if column stripes are shown

Examples

{:ok, style} = Table.get_table_style(spreadsheet, "Sheet1", "SalesTable")
# style = %{"name" => "TableStyleLight1", "show_first_column" => "true", ...}

@spec get_table_totals_row(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  {:ok, boolean()} | {:error, String.t()}

Gets the totals row visibility status for a specific table.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table

Examples

{:ok, has_totals_row?} = Table.get_table_totals_row(spreadsheet, "Sheet1", "SalesTable")
# has_totals_row? = true or false

Returns {:ok, boolean} if successful, {:error, reason} otherwise.

@spec get_tables(UmyaSpreadsheet.Spreadsheet.t(), String.t()) ::
  {:ok, [map()]} | {:error, String.t()}

Gets all tables from a worksheet.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet to get tables from

Returns

A list of maps, each containing table information with keys:

• "name" - Internal table name
• "display_name" - Display name
• "start_cell" - Top-left cell reference
• "end_cell" - Bottom-right cell reference
• "columns" - List of column names
• "has_totals_row" - Boolean indicating if totals row is enabled
• "style_info" - Map with styling information (if table has custom styling)

Examples

{:ok, tables} = Table.get_tables(spreadsheet, "Sheet1")
# tables = [%{"name" => "SalesTable", "display_name" => "Sales Data", ...}]

@spec has_tables(UmyaSpreadsheet.Spreadsheet.t(), String.t()) ::
  {:ok, boolean()} | {:error, String.t()}

Checks if a worksheet has any tables.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet to check

Examples

{:ok, has_tables?} = Table.has_tables(spreadsheet, "Sheet1")
# has_tables? = true or false

Returns {:ok, boolean} if successful, {:error, reason} otherwise.

@spec modify_table_column(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t() | nil,
  String.t() | nil,
  String.t() | nil
) :: {:ok, :ok} | {:error, String.t()}

Modifies an existing table column.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table to modify
• old_column_name - Current name of the column to modify
• new_column_name - Optional new name for the column
• totals_row_function - Optional function for the totals row
• totals_row_label - Optional custom label for the totals row

Examples

# Rename a column and change its totals function
Table.modify_table_column(
  spreadsheet,
  "Sheet1",
  "SalesTable",
  "Sales",
  "Revenue",
  "sum",
  "Total Revenue"
)

Returns :ok on success or {:error, reason} on failure.

@spec remove_table(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  {:ok, :ok} | {:error, String.t()}

Removes a table from a worksheet by name.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table to remove

Examples

Table.remove_table(spreadsheet, "Sheet1", "SalesTable")

Returns :ok on success or {:error, reason} on failure.

@spec remove_table_style(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  {:ok, :ok} | {:error, String.t()}

Removes table style information, reverting to default styling.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table to remove styling from

Examples

Table.remove_table_style(spreadsheet, "Sheet1", "SalesTable")

Returns :ok on success or {:error, reason} on failure.

@spec set_table_style(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  String.t(),
  String.t(),
  boolean(),
  boolean(),
  boolean(),
  boolean()
) :: {:ok, :ok} | {:error, String.t()}

Sets table style information.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table to style
• style_name - Name of the table style to apply
• show_first_col - Boolean to highlight the first column
• show_last_col - Boolean to highlight the last column
• show_row_stripes - Boolean to show alternating row colors
• show_col_stripes - Boolean to show alternating column colors

Examples

Table.set_table_style(
  spreadsheet,
  "Sheet1",
  "SalesTable",
  "TableStyleLight1",
  true,   # Highlight first column
  true,   # Highlight last column
  true,   # Show row stripes
  false   # Don't show column stripes
)

Returns :ok on success or {:error, reason} on failure.

@spec set_table_totals_row(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  String.t(),
  boolean()
) ::
  {:ok, :ok} | {:error, String.t()}

Sets the visibility of the totals row for a table.

Parameters

• spreadsheet - A spreadsheet struct
• sheet_name - Name of the sheet containing the table
• table_name - Internal name of the table to modify
• show_totals_row - Boolean indicating whether to show the totals row

Examples

# Show the totals row
Table.set_table_totals_row(spreadsheet, "Sheet1", "SalesTable", true)

# Hide the totals row
Table.set_table_totals_row(spreadsheet, "Sheet1", "SalesTable", false)

Returns :ok on success or {:error, reason} on failure.