model_context

Defined in header: <ixion/model_context.hpp>

class model_context

This class stores all cell values of different types organized in multiple sheets. It also stores named expressions both in global scope and sheet-local scope.

Public Functions

model_context()

model_context(const rc_size_t &sheet_size)

~model_context()

formula_result_wait_policy_t get_formula_result_wait_policy() const

Query the current policy on what to do when a formula cell result is being requested while the result has not yet been computed.

void notify(formula_event_t event)

This method is used to notify the model access implementer of formula events.

Parameters:

event – event type.

const config &get_config() const

dirty_cell_tracker &get_cell_tracker()

const dirty_cell_tracker &get_cell_tracker() const

bool is_empty(const abs_address_t &addr) const

bool is_empty(const abs_range_t &range) const

cell_t get_celltype(const abs_address_t &addr) const

cell_value_t get_cell_value_type(const abs_address_t &addr) const

double get_numeric_value(const abs_address_t &addr) const

Get a numeric representation of the cell value at specified position. If the cell at the specified position is a formula cell and its result has not yet been computed, it will block until the result becomes available.

Parameters:

addr – position of the cell.

Returns:

numeric representation of the cell value.

bool get_boolean_value(const abs_address_t &addr) const

string_id_t get_string_identifier(const abs_address_t &addr) const

std::string_view get_string_value(const abs_address_t &addr) const

Get a string value associated with the cell at the specified position. It returns a valid string value only when the cell is a string cell, or is a formula cell containing a string result. Otherwise, it returns a nullptr.

Parameters:

addr – position of the cell.

Returns:

pointer to a string value if the cell stores a valid string value, else nullptr.

const formula_cell *get_formula_cell(const abs_address_t &addr) const

formula_cell *get_formula_cell(const abs_address_t &addr)

formula_result get_formula_result(const abs_address_t &addr) const

const named_expression_t *get_named_expression(sheet_t sheet, std::string_view name) const

Get a named expression token set associated with specified name if present. It first searches the local sheet scope for the name, then if it’s not present, it searches the global scope.

Parameters:

• sheet – index of the sheet scope to search in.

• name – name of the expression.

Returns:

const pointer to the token set if exists, nullptr otherwise.

double count_range(const abs_range_t &range, values_t values_type) const

matrix get_range_value(const abs_range_t &range) const

Obtain range value in matrix form. Multi-sheet ranges are not supported. If the specified range consists of multiple sheets, it throws an exception.

Parameters:

range – absolute, single-sheet range address. Multi-sheet ranges are not allowed.

Returns:

range value represented as matrix.

std::unique_ptr<iface::session_handler> create_session_handler() const

Session handler instance receives various events from the formula interpretation run, in order to respond to those events. This is optional; the model context implementation is not required to provide a handler.

Returns:

a new session handler instance. It may be nullptr.

iface::table_handler *get_table_handler()

Table interface provides access to all table ranges stored in the document model. A table is a 2-dimensional range of cells that include named columns. It is used when resolving a table reference that refers to a cell or a range of cells by the table name and/or column name.

Returns:

non-null pointer to the table storage inside the model, or nullptr if no table is present or supported by the model implementation.

const iface::table_handler *get_table_handler() const

string_id_t append_string(std::string_view s)

Append a new string to the string pool. The string being passed will be inserted into the pool with a new string ID which is the current maximum ID incremented by one.

Note

This function will not check for duplicates in the pool. An empty string will also be inserted into the pool.

Parameters:

s – String to append to the pool.

Returns:

Integer value associated with the appended string.

string_id_t add_string(std::string_view s)

Try to add a new string to the indexed string pool. If the same string already exists in the pool, the existing id is returned and no new entry is added.

Parameters:

s – string to try to add to the pool.

Returns:

integer id representing the string.

const std::string *get_string(string_id_t identifier) const

sheet_t get_sheet_index(std::string_view name) const

Get the index of sheet from sheet name. If the sheet name doesn’t exist, it returns a value equal to ixion::invalid_sheet.

Parameters:

name – sheet name.

Returns:

0-based sheet index, or ixion::invalid_sheet in case the document doesn’t have a sheet by the specified name.

std::string_view get_sheet_name(sheet_t sheet) const

Get the name of a sheet specified by a 0-based sheet index.

Parameters:

sheet – 0-based sheet index.

Throws:

std::invalid_argument – When the sheet index is invalid.

Returns:

Name of the sheet if the sheet index is valid.

void set_sheet_name(sheet_t sheet, std::string name)

Set a new name to an existing sheet.

Parameters:

• sheet – 0-based sheet index.

• name – New name of a sheet.

Throws:

std::invalid_argument – When the sheet index is invalid.

rc_size_t get_sheet_size() const

Get the size of a sheet.

Returns:

sheet size.

size_t get_sheet_count() const

Return the number of sheets.

Returns:

number of sheets.

void set_sheet_size(const rc_size_t &sheet_size)

void set_config(const config &cfg)

void empty_cell(const abs_address_t &addr)

void set_numeric_cell(const abs_address_t &addr, double val)

void set_boolean_cell(const abs_address_t &adr, bool val)

void set_string_cell(const abs_address_t &addr, std::string_view s)

void set_string_cell(const abs_address_t &addr, string_id_t identifier)

cell_access get_cell_access(const abs_address_t &addr) const

void fill_down_cells(const abs_address_t &src, size_t n_dst)

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

Parameters:

• src – position of the source cell to copy the value from.

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

formula_cell *set_formula_cell(const abs_address_t &addr, formula_tokens_t tokens)

Set a formula cell at a specified address.

Parameters:

• addr – address at which to set a formula cell.

• tokens – formula tokens to put into the formula cell.

Returns:

pointer to the formula cell instance inserted into the model.

formula_cell *set_formula_cell(const abs_address_t &addr, const formula_tokens_store_ptr_t &tokens)

Set a formula cell at a specified address. This variant takes a formula tokens store that can be shared between multiple formula cell instances.

Parameters:

• addr – address at which to set a formula cell.

• tokens – formula tokens to put into the formula cell.

Returns:

pointer to the formula cell instance inserted into the model.

formula_cell *set_formula_cell(const abs_address_t &addr, const formula_tokens_store_ptr_t &tokens, formula_result result)

Set a formula cell at a specified address. This variant takes a formula tokens store that can be shared between multiple formula cell instances.

Parameters:

• addr – address at which to set a formula cell.

• tokens – formula tokens to put into the formula cell.

• result – cached result of this formula cell.

Returns:

pointer to the formula cell instance inserted into the model.

void set_grouped_formula_cells(const abs_range_t &group_range, formula_tokens_t tokens)

void set_grouped_formula_cells(const abs_range_t &group_range, formula_tokens_t tokens, formula_result result)

abs_range_t get_data_range(sheet_t sheet) const

void set_named_expression(std::string name, formula_tokens_t expr)

Set a named expression associated with a string name in the global scope.

Parameters:

• name – name of the expression.

• expr – formula tokens to use for the named expression.

void set_named_expression(std::string name, const abs_address_t &origin, formula_tokens_t expr)

Set a named expression associated with a string name in the global scope.

Parameters:

• name – name of the expression.

• origin – position of the origin cell. Origin cell is relevant only when you need to convert the tokens into a string representation.

• expr – formula tokens to use for the named expression.

void set_named_expression(sheet_t sheet, std::string name, formula_tokens_t expr)

Set a named expression associated with a string name in a sheet-local scope.

Parameters:

• sheet – 0-based index of the sheet to register this expression with.

• name – name of the expression.

• expr – formula tokens to use for the named expression.

void set_named_expression(sheet_t sheet, std::string name, const abs_address_t &origin, formula_tokens_t expr)

Set a named expression associated with a string name in a sheet-local scope.

Parameters:

• sheet – 0-based index of the sheet to register this expression with.

• name – name of the expression.

• origin – position of the origin cell. Origin cell is relevant only when you need to convert the tokens into a string representation.

• expr – formula tokens to use for the named expression.

sheet_t append_sheet(std::string name)

Append a new sheet to the model. The caller must ensure that the name of the new sheet is unique within the model context. When the name being used for the new sheet already exists, it throws a model_context_error exception.

Parameters:

name – name of the sheet to be inserted.

Throws:

model_context_error –

Returns:

sheet index of the inserted sheet.

void set_cell_values(sheet_t sheet, std::initializer_list<input_row> rows)

A convenient way to mass-insert a range of cell values. You can use a nested initializet list representing a range of cell values. The outer list represents rows.

Parameters:

• sheet – sheet index.

• rows – nested list of cell values. The outer list represents rows.

void set_session_handler_factory(session_handler_factory *factory)

void set_table_handler(iface::table_handler *handler)

size_t get_string_count() const

void dump_strings() const

string_id_t get_identifier_from_string(std::string_view s) const

Get an integer string ID from a string value. If the string value doesn’t exist in the pool, the value equal to empty_string_id gets returned.

Deprecated:

Only strings registered via append_string live in the indexed string pool. Strings written through set_string_cell with a string_view go to a separate inline pool and are not visible here. Read cell strings via get_string_value instead.

Parameters:

s – string value.

Returns:

string_id_t integer string ID associated with the string value given.

std::string_view intern_string(std::string_view s)

Intern a string into the inline string pool and return a stable string view instance valid for the lifetime of the model.

Parameters:

s – String to intern.

Returns:

Stable view into pool-owned storage.

model_iterator get_model_iterator(sheet_t sheet, rc_direction_t dir, const abs_rc_range_t &range) const

Get an immutable iterator that lets you iterate cell values in one sheet one at a time. The caller has to ensure that the model content does not change for the duration of the iteration.

Parameters:

• sheet – sheet index.

• dir – direction of the iteration.

• range – range on the specified sheet to iterate over.

Returns:

model iterator instance.

model_cell_range iterate_cells(sheet_t sheet, rc_direction_t dir, const abs_rc_range_t &range) const

Get an STL-compliant range over cell values in one sheet. Supports range-for and STL/range algorithms. The caller has to ensure that the model content does not change for the duration of the iteration.

Parameters:

• sheet – Sheet index.

• dir – Direction of the iteration.

• range – Range on the specified sheet to iterate over.

Returns:

Cell range instance.

named_expressions_iterator get_named_expressions_iterator() const

Get an iterator for global named expressions.

named_expressions_iterator get_named_expressions_iterator(sheet_t sheet) const

Get an interator for sheet-local named expressions.

Parameters:

sheet – 0-based index of the sheet where the named expressions are stored.

void walk(sheet_t sheet, const abs_rc_range_t &range, column_block_callback_t cb) const

bool empty() const

struct input_cell

Cell value only to be used to input a collection of cells to sheet. Formula cells are not supported.

Public Types

using value_type = std::variant<bool, double, std::string_view>

Public Functions

input_cell(std::nullptr_t)

Initializes the cell to be empty.

input_cell(bool b)

Boolean cell value.

input_cell(const char *s)

The char array must be null-terminated.

input_cell(double v)

Numeric cell value.

input_cell(const input_cell &other)

Public Members

cell_t type

value_type value

class input_row

Public Functions

input_row(std::initializer_list<input_cell> cells)

const std::initializer_list<input_cell> &cells() const

class session_handler_factory

Constructs a new iface::session_handler instance for each formula-cell evaluation.

The factory indirection exists so cell calculation can run in parallel: each cell-evaluation thread asks the factory for its own handler instance, so handlers accumulate per-cell trace state without sharing mutable data across threads. The host configures the factory once via set_session_handler_factory; the model and the formula interpreter call create per cell to obtain a fresh handler.

Public Functions

virtual std::unique_ptr<iface::session_handler> create() const

virtual ~session_handler_factory()