model_context_loader

Defined in header: <ixion/model_context_loader.hpp>

class model_context_loader

Loads content into a model in bulk. It’s a load-time wrapper on a model the caller owns: it takes the place of model_context for the duration of the load, defers the work that the model_context setters do on every call until finalize(), and can be discarded once the load is done.

The setters write and nothing else. A formula cell doesn’t get validated or registered with the dirty cell tracker until finalize(), so the formula cells don’t depend on the named expressions and tables they reference being loaded first.

Note

Each cell gets written at most once: a setter aimed at a cell that isn’t empty throws model_context_error (loader_cell_not_empty). The model itself doesn’t have to be empty, and more content can be loaded later with a new loader on the same model.

Note

Every sheet a formula references must exist when the formula gets set, and every named expression and table it references must exist when finalize() gets called.

Note

Don’t modify cells or calculate the model through model_context while a loader is working on it, and use one loader at a time per model.

Note

finalize() ends the load: every call on the loader afterwards throws model_context_error (loader_already_finalized). The destructor doesn’t finalize; the formula cells of a loader that never got finalized stay unregistered.

Public Functions

model_context_loader() = delete

model_context_loader(const model_context_loader&) = delete

model_context_loader &operator=(const model_context_loader&) = delete

explicit model_context_loader(model_context &cxt)

Constructor.

Parameters:: cxt – Model to load into. It must outlive the loader.

~model_context_loader()

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_named_expression(std::string name, formula_tokens_t expr)

Set a named expression associated with a string name in the global scope. An existing expression by the same name gets replaced.

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. An existing expression by the same name gets replaced.

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. An existing expression by the same name gets replaced.

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. An existing expression by the same name gets replaced.

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.

void set_table(table_t tab)

Insert a new table into the model. A table is a 2-dimensional range of cells with named columns, referenced by table references in formula expressions.

Parameters:

tab – Table to insert. It must have a non-empty name unique within the model, a valid sheet index and a valid range.

Throws:

std::invalid_argument – When the name is empty, the sheet index is invalid, or the range is invalid.
model_context_error – When a table by the same name already exists in the model.

string_id_t append_string(std::string_view s)

Append a new string to the indexed string pool, without checking for duplicates. An empty string gets appended too.

Parameters:: s – String to append.
Returns:: Identifier of the appended string.

string_id_t add_string(std::string_view s)

Add a string to the indexed string pool, unless the same string is already in it.

Parameters:: s – String to add.
Returns:: Identifier of the string, existing or new.

void set_numeric_cell(const abs_address_t &addr, double val)

Set a numeric value to an empty cell.

Parameters:

addr – Position of the cell.
val – Numeric value.

void set_boolean_cell(const abs_address_t &addr, bool val)

Set a boolean value to an empty cell.

Parameters:

addr – Position of the cell.
val – Boolean value.

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

Set a string value to an empty cell. The string gets stored in the model, so the caller doesn’t need to keep it alive.

Parameters:

addr – Position of the cell.
s – String value.

void set_string_cell(const abs_address_t &addr, string_id_t identifier)

Set a string from the indexed string pool to an empty cell.

Parameters:

addr – Position of the cell.
identifier – Identifier of the string, as returned by append_string() or add_string().

void fill_down_cells(const abs_address_t &src, std::size_t n_dst)

Duplicate the value of the source cell to one or more empty 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.

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

A convenient way to mass-insert a range of cell values into empty cells. You can use a nested initializer 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.

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

Set a formula cell at an empty cell, like model_context::set_formula_cell() except that the cell doesn’t get validated or registered with the dirty cell tracker until finalize().

Parameters:

addr – Address at which to set the 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 an empty cell, like model_context::set_formula_cell() except that the cell doesn’t get validated or registered with the dirty cell tracker until finalize().

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

Parameters:

addr – Address at which to set the 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 an empty cell, like model_context::set_formula_cell() except that the cell doesn’t get validated or registered with the dirty cell tracker until finalize().

This variant takes a formula tokens store that can be shared between multiple formula cell instances, and a cached result.

Parameters:

addr – Address at which to set the formula cell.
tokens – Formula tokens to put into the formula cell.
result – Cached result of the 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)

Set a group of formula cells sharing one set of formula tokens over a range of empty cells, like model_context::set_grouped_formula_cells() except that the group doesn’t get validated or registered with the dirty cell tracker until finalize().

Parameters:

group_range – Range of the group. It must be on one sheet.
tokens – Formula tokens shared by all cells of the group. They are relative to the top-left cell of the group.

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

Set a group of formula cells sharing one set of formula tokens over a range of empty cells, like model_context::set_grouped_formula_cells() except that the group doesn’t get validated or registered with the dirty cell tracker until finalize().

This variant takes a cached result.

Parameters:

group_range – Range of the group. It must be on one sheet.
tokens – Formula tokens shared by all cells of the group. They are relative to the top-left cell of the group.
result – Cached result of the group. It must be a matrix whose dimensions equal those of the group.

Throws:

std::invalid_argument – When the result is not a matrix, or its dimensions differ from those of the group.

void finalize()

Register the formula cells set through the loader with the dirty cell tracker. This ends the load; call it once.

Every cell gets validated before any of them gets registered, so a rejected cell leaves the tracker unchanged. The rejected cell itself stays in the model.

Throws:: model_context_error – When a reference in a formula, including one reached through a named expression, points at an invalid sheet (invalid_sheet_reference), or when called a second time (loader_already_finalized).