Sheet import

The following interfaces handle importing of contents and properties related to individual sheets.

class import_sheet

Interface for importing the content and properties of a sheet.

Public Functions

virtual ~import_sheet()
virtual import_sheet_view *get_sheet_view()

Get an optional interface for importing properties that are specific to a view of a sheet.

Returns:

pointer to the interface for importing view properties, or a nullptr if the implementor doesn’t support it.

virtual import_sheet_properties *get_sheet_properties()

Get an optional interface for importing sheet properties.

Returns:

pointer to the interface for importing sheet properties, or a nullptr if the implementor doesn’t support it.

virtual import_data_table *get_data_table()

Get an optional interface for importing data tables. Note that the implementer may decide not to support this feature in which case this method should return a nullptr.

The implementor should initialize the internal state of the temporary data table object when this method is called.

Returns:

pointer to the data table interface object, or a nullptr if the implementor doesn’t support it.

virtual import_auto_filter *get_auto_filter()

Get an optional interface for importing auto filter ranges.

The implementor should initialize the internal state of the temporary auto filter object when this method is called.

Returns:

pointer to the auto filter interface object, or a nullptr if the implementor doesn’t support it.

virtual import_table *get_table()

Get an interface for importing tables.

The implementor should initialize the internal state of the temporary table object when this method is called.

Returns:

pointer to the table interface object, or nullptr if the implementer doesn’t support importing of tables.

virtual import_conditional_format *get_conditional_format()

Get an optional interface for importing conditional formats.

Returns:

pointer to the conditional format interface object, or nullptr if the implementer doesn’t support importing conditional formats.

virtual import_named_expression *get_named_expression()

Get an optional interface for importing sheet-local named expressions.

Returns:

pointer to the sheet-local named expression interface, or a nullptr if the implementor doesn’t support it.

virtual import_array_formula *get_array_formula()

Get an optional interface for importing array formulas. An array formula is a formula expression applied to a range of cells where each cell may have a different result value.

Returns:

pointer to the array formula import interface, or a nullptr if the implementor doesn’t support it.

virtual import_formula *get_formula()

Get an optional interface for importing formula cells.

Returns:

pointer to the formula interface object, or a nullptr if the implementer doesn’t support importing of formula cells.

virtual void set_auto(row_t row, col_t col, std::string_view s) = 0

Set raw string value to a cell and have the implementation auto-recognize its data type.

Parameters:
  • row – row ID

  • col – column ID

  • s – raw string value.

virtual void set_string(row_t row, col_t col, string_id_t sindex) = 0

Set string value to a cell.

Parameters:
  • row – row ID

  • col – column ID

  • sindex – 0-based string index in the shared string table.

virtual void set_value(row_t row, col_t col, double value) = 0

Set numerical value to a cell.

Parameters:
  • row – row ID

  • col – column ID

  • value – value being assigned to the cell.

virtual void set_bool(row_t row, col_t col, bool value) = 0

Set a boolean value to a cell.

Parameters:
  • row – row ID

  • col – col ID

  • value – boolean value being assigned to the cell

virtual void set_date_time(row_t row, col_t col, int year, int month, int day, int hour, int minute, double second) = 0

Set date and time value to a cell.

Parameters:
  • row – row ID

  • col – column ID

  • year – 1-based value representing year

  • month – 1-based value representing month, varying from 1 through 12.

  • day – 1-based value representing day, varying from 1 through 31.

  • hour – the hour of a day, ranging from 0 through 23.

  • minute – the minute of an hour, ranging from 0 through 59.

  • second – the second of a minute, ranging from 0 through 59.

virtual void set_format(row_t row, col_t col, size_t xf_index) = 0

Set cell format to specified cell. The cell format is referred to by the xf (cell format) index in the styles table.

Note

This method gets called after both set_column_format() and set_row_format().

Parameters:
  • row – row ID

  • col – column ID

  • xf_index – 0-based xf (cell format) index

virtual void set_format(row_t row_start, col_t col_start, row_t row_end, col_t col_end, size_t xf_index) = 0

Set cell format to specified cell range. The cell format is referred to by the xf (cell format) index in the styles table.

Parameters:
  • row_start – start row ID

  • col_start – start column ID

  • row_end – end row ID

  • col_end – end column ID

  • xf_index – 0-based xf (cell format) index

virtual void set_column_format(col_t col, col_t col_span, std::size_t xf_index) = 0

Set cell format to a specified column. The cell format is referred to by the xf (cell format) index in the styles table.

Note

This method gets called first before set_row_format() or set_format() variants.

Parameters:
  • col – column ID

  • col_span – number of contiguous columns to apply the format to. It must be at least one.

  • xf_index – 0-based xf (cell format) index

virtual void set_row_format(row_t row, std::size_t xf_index) = 0

Set cell format to a specified row. The cell format is referred to by the xf (cell format) index in the styles table.

Note

This method gets called after set_column_format() but before set_format().

Parameters:
  • row – row ID

  • xf_index – 0-based xf (cell format) index

virtual void fill_down_cells(row_t src_row, col_t src_col, row_t range_size) = 0

Duplicate the value of the source cell to one or more cells located immediately below it.

Parameters:
  • src_row – row ID of the source cell

  • src_col – column ID of the source cell

  • range_size – number of cells below the source cell to copy the source cell value to. It must be at least one.

virtual range_size_t get_sheet_size() const = 0

Get the size of the sheet.

Returns:

structure containing the numbers of rows and columns of the sheet.

class import_sheet_properties

Interface for importing sheet properties. Sheet properties include:

  • column widths and row heights,

  • hidden flags for columns and rows, and

  • merged cell ranges.

These properties are independent of the cell contents of a sheet.

Public Functions

virtual ~import_sheet_properties()
virtual void set_column_width(col_t col, col_t col_span, double width, orcus::length_unit_t unit) = 0

Set a column width to one or more columns.

Parameters:
  • col – 0-based position of the first column.

  • col_span – number of contiguous columns to apply the width to.

  • width – column width to apply.

  • unit – unit of measurement to use for the width value.

virtual void set_column_hidden(col_t col, col_t col_span, bool hidden) = 0

Set a column hidden flag to one or more columns.

Parameters:
  • col – 0-based position of the first column.

  • col_span – number of contiguous columns to apply the flag to.

  • hidden – flag indicating whether or not the columns are hidden.

virtual void set_row_height(row_t row, double height, orcus::length_unit_t unit) = 0

Set a row height to specified row.

Todo:

Convert this to take a raw span.

Parameters:
  • row – 0-based position of a row.

  • height – new row height value to set.

  • unit – unit of the new row height value.

virtual void set_row_hidden(row_t row, bool hidden) = 0

Set a row hidden flag to a specified row.

Todo:

Convert this to take a raw span.

Parameters:
  • row – 0-based position of a row.

  • hidden – flag indicating whether or not the row is hidden.

virtual void set_merge_cell_range(const range_t &range) = 0

Set a merged cell range.

Parameters:

range – structure containing the top-left and bottom-right positions of a merged cell range.

class import_data_table

Interface for importing data tables.

Public Functions

virtual ~import_data_table()
virtual void set_type(data_table_type_t type) = 0

Set the type of a data table. A data table can either:

  • be a single-variable column-oriented,

  • be a single-variable row-oriented, or

  • use two variables that use both column and row.

Parameters:

type – type of a data table.

virtual void set_range(const range_t &range) = 0

Set the range of a data table.

Parameters:

range – range of a data table.

virtual void set_first_reference(std::string_view ref, bool deleted) = 0

Set the reference of the first input cell.

Parameters:
  • ref – reference of the first input cell.

  • deleted – whether or not this input cell has been deleted.

virtual void set_second_reference(std::string_view ref, bool deleted) = 0

Set the reference of the second input cell but only if the data table uses two variables.

Note

This method gets called only if the data table uses two variables.

Parameters:
  • ref – reference of the second input cell.

  • deleted – whether or not this input cell has been deleted.

virtual void commit() = 0

Store the current data table data in the buffer to the backend sheet storage.

class import_auto_filter

Interface for importing auto filters.

Importing a single auto filter would roughly follow the following flow:

import_auto_filter* iface = ... ;

range_t range;
range.first.column = 0;
range.first.row = 0;
range.last.column = 3;
range.last.row = 1000;
iface->set_range(range); // Auto filter is applied for A1:D1001.

// Column A is filtered for a value of "A".
iface->set_column(0);
iface->append_column_match_value("A");
iface->commit_column();

// Column D is filtered for values of 1 and 4.
iface->set_column(3);
iface->append_column_match_value("1");
iface->append_column_match_value("4");
iface->commit_column();

// Push the autofilter data in the current buffer to the sheet store.
iface->commit();

Public Functions

virtual ~import_auto_filter()
virtual void set_range(const range_t &range) = 0

Specify the range where the auto filter is applied.

Parameters:

range – structure containing the top-left and bottom-right positions of the auto filter range.

virtual void set_column(col_t col) = 0

Specify the column position of a filter. The position is relative to the first column in the auto filter range. This method gets called at the beginning of each column filter data. The implementor may initialize the column filter data buffer when this method is called.

Note

This column position is relative to the first column in the autofilter range.

Parameters:

col – 0-based column position of a filter relative to the first column of the auto filter range.

virtual void append_column_match_value(std::string_view value) = 0

Append a match value to the current column filter. A single column filter may have one or more match values.

Parameters:

value – match value to append to the current column filter.

virtual void commit_column() = 0

Commit the current column filter data to the current auto filter buffer. The implementor may clear the current column filter buffer after this call.

virtual void commit() = 0

Commit current auto filter data stored in the buffer to the sheet store.

class import_conditional_format

This is an optional interface to import conditional formatting.

In general, a single conditional format consists of:

  • a cell range the format is applied to, and

  • one or more rule entries.

Each rule entry consists of:

  • a type of rule,

  • zero or more rule properties, and

  • zero or more conditions depending on the rule type.

Lastly, each condition consists of:

  • a formula, value, or string,

  • an optional color.

The flow of the import process varies depending on the type of the conditional formatting being imported. The following is an example of importing a conditional formatting that consists of a rule that applies a format when the cell value is greather than 2:

import_conditional_format* iface = ... ;

iface->set_range("A2:A13");
iface->set_xf_id(14); // apply differential format (dxf) whose ID is 14
iface->set_type(conditional_format_t::condition); // rule entry type
iface->set_operator(condition_operator_t::expression);
iface->set_operator(condition_operator_t::greater);

iface->set_formula("2");
iface->commit_condition();

iface->commit_entry();

iface->commit_format();

Todo:

Revise this API for simplification.

Public Functions

virtual ~import_conditional_format()
virtual void set_color(color_elem_t alpha, color_elem_t red, color_elem_t green, color_elem_t blue) = 0

Sets the color of the current condition. only valid for type == databar or type == colorscale.

virtual void set_formula(std::string_view formula) = 0

Sets the formula, value or string of the current condition.

virtual void set_condition_type(condition_type_t type) = 0

Sets the type for the formula, value or string of the current condition. Only valid for type = iconset, databar or colorscale.

virtual void set_date(condition_date_t date) = 0

Only valid for type = date.

virtual void commit_condition() = 0

commits the current condition to the current entry.

virtual void set_icon_name(std::string_view name) = 0

Name of the icons to use in the current entry. only valid for type = iconset

virtual void set_databar_gradient(bool gradient) = 0

Use a gradient for the current entry. only valid for type == databar

virtual void set_databar_axis(databar_axis_t axis) = 0

Position of the 0 axis in the current entry. only valid for type == databar.

virtual void set_databar_color_positive(color_elem_t alpha, color_elem_t red, color_elem_t green, color_elem_t blue) = 0

Databar color for positive values. only valid for type == databar.

virtual void set_databar_color_negative(color_elem_t alpha, color_elem_t red, color_elem_t green, color_elem_t blue) = 0

Databar color for negative values. only valid for type == databar.

virtual void set_min_databar_length(double length) = 0

Sets the minimum length for a databar. only valid for type == databar.

virtual void set_max_databar_length(double length) = 0

Sets the maximum length for a databar. only valid for type == databar.

virtual void set_show_value(bool show) = 0

Don’t show the value in the cell. only valid for type = databar, iconset, colorscale.

virtual void set_iconset_reverse(bool reverse) = 0

Use the icons in reverse order. only valid for type == iconset.

virtual void set_xf_id(size_t xf) = 0

TODO: In OOXML the style is stored as dxf and in ODF as named style.

virtual void set_operator(condition_operator_t condition_type) = 0

Sets the current operation used for the current entry. only valid for type == condition

virtual void set_type(conditional_format_t type) = 0
virtual void commit_entry() = 0
virtual void set_range(std::string_view range) = 0
virtual void set_range(row_t row_start, col_t col_start, row_t row_end, col_t col_end) = 0
virtual void commit_format() = 0
class import_table

Interface for table. A table is a range of cells within a sheet that consists of one or more data columns with a header row that contains their labels.

Public Functions

virtual ~import_table()
virtual import_auto_filter *get_auto_filter()

Get an optional interface for importing auto filter data stored as part of a table.

The implementor should initialize the internal state of the temporary auto filter object when this method is called.

Returns:

pointer to the auto filter interface object, or a nullptr if the implementor doesn’t support it.

virtual void set_identifier(size_t id) = 0

Set an integral identifier unique to the table.

Parameters:

id – identifier associated with the table.

virtual void set_range(const range_t &range) = 0

Set a 2-dimensional cell range associated with the table.

Parameters:

range – cell range associated with the table.

virtual void set_totals_row_count(size_t row_count) = 0

Set the number of totals rows.

Parameters:

row_count – number of totals rows.

virtual void set_name(std::string_view name) = 0

Set the internal name of the table.

Parameters:

name – name of the table.

virtual void set_display_name(std::string_view name) = 0

Set the displayed name of the table.

Parameters:

name – displayed name of the table.

virtual void set_column_count(size_t n) = 0

Set the number of columns the table contains.

Note

This method gets called before the column data gets imported. The implementor can use this call to initialize the buffer for storing the column data.

Parameters:

n – number of columns in the table.

virtual void set_column_identifier(size_t id) = 0

Set an integral identifier for a column.

Parameters:

id – integral identifier for a column.

virtual void set_column_name(std::string_view name) = 0

Set a name of a column.

Parameters:

name – name of a column.

virtual void set_column_totals_row_label(std::string_view label) = 0

Set the totals row label for a column.

Parameters:

label – row label for a column.

virtual void set_column_totals_row_function(totals_row_function_t func) = 0

Set the totals row function for a column.

Parameters:

func – totals row function for a column.

virtual void commit_column() = 0

Push and append the column data stored in the current column data buffer into the table buffer.

virtual void set_style_name(std::string_view name) = 0

Set the name of a style to apply to the table.

Parameters:

name – name of a style to apply to the table.

virtual void set_style_show_first_column(bool b) = 0

Specify whether or not the first column in the table should have the style applied.

Parameters:

b – whether or not the first column in the table should have the style applied.

virtual void set_style_show_last_column(bool b) = 0

Specify whether or not the last column in the table should have the style applied.

Parameters:

b – whether or not the last column in the table should have the style applied.

virtual void set_style_show_row_stripes(bool b) = 0

Specify whether or not row stripe formatting is applied.

Parameters:

b – whether or not row stripe formatting is applied.

virtual void set_style_show_column_stripes(bool b) = 0

Specify whether or not column stripe formatting is applied.

Parameters:

b – whether or not column stripe formatting is applied.

virtual void commit() = 0

Push the data stored in the table buffer into the document store.

class import_formula

Interface for importing the properties of a single formula cell. A formula cell contains a formula expression that can be computed, and optionally a cached result of the last computation performed on the expression.

Public Functions

virtual ~import_formula()
virtual void set_position(row_t row, col_t col) = 0

Set the position of a cell.

Parameters:
  • row – row position.

  • col – column position.

virtual void set_formula(formula_grammar_t grammar, std::string_view formula) = 0

Set formula string to a cell.

Parameters:
  • grammar – grammar to use to compile the formula string into tokens.

  • formula – formula expression to store.

virtual void set_shared_formula_index(size_t index) = 0

Register the formula stored in a cell as a shared formula to be shared with other cells, if the cell contains a formula string.

If a cell references a shared formula stored in another cell, only specify the index of that shared formula without specifying a formula string of its own. In that case, it is expected that another formula cell registers its formula string for that index.

Parameters:

index – shared string index to register the formula with.

virtual void set_result_string(std::string_view value) = 0

Set cached result of string type.

Parameters:

value – string result value.

virtual void set_result_value(double value) = 0

Set cached result of numeric type.

Parameters:

value – numeric value to set as a cached result.

virtual void set_result_bool(bool value) = 0

Set cached result of boolean type.

Parameters:

value – boolean value to set as a cached result.

virtual void set_result_empty() = 0

Set empty value as a cached result.

virtual void commit() = 0

Commit all the formula data to the specified cell.

class import_array_formula

Interface for importing the properties of an array formula which occupies a range of cells. Cells that are part of an array formula share the same formula expression but may have different calculation results.

Public Functions

virtual ~import_array_formula()
virtual void set_range(const range_t &range) = 0

Set the range of an array formula.

Parameters:

range – range of an array formula.

virtual void set_formula(formula_grammar_t grammar, std::string_view formula) = 0

Set the formula expression of an array formula.

Parameters:
  • grammar – grammar to use to compile the formula string into tokens.

  • formula – formula expression of an array formula.

virtual void set_result_string(row_t row, col_t col, std::string_view value) = 0

Set a cached string result of a cell within the array formula range.

Parameters:
  • row – 0-based row position of a cell.

  • col – 0-based column position of a cell.

  • value – cached string value to set.

virtual void set_result_value(row_t row, col_t col, double value) = 0

Set a cached numeric result of a cell within the array formula range.

Parameters:
  • row – 0-based row position of a cell.

  • col – 0-based column position of a cell.

  • value – cached numeric value to set.

virtual void set_result_bool(row_t row, col_t col, bool value) = 0

Set a cached boolean result of a cell within the array formula range.

Parameters:
  • row – 0-based row position of a cell.

  • col – 0-based column position of a cell.

  • value – cached boolean value to set.

virtual void set_result_empty(row_t row, col_t col) = 0

Set an empty value as a cached result to a cell within the array formula range.

Parameters:
  • row – 0-based row position of a cell.

  • col – 0-based column position of a cell.

virtual void commit() = 0

Push the properties of an array formula currently stored in the buffer to the sheet store.