Model Context¶
Examples¶
Refer to the Using model_context class section for code examples on how
to use the model_context
class.
API Reference¶
-
class
ixion
::
model_context
: public ixion::iface::formula_model_access¶ This class stores all data relevant to current session. You can think of this like a document model for each formula calculation run. Note that only those methods called from the formula interpreter are specified in the interface; this explains why accessors for the most part only have the ‘get’ method not paired with its ‘set’ counterpart.
Public Functions
-
model_context
()¶
-
~model_context
() override¶
-
void
notify
(formula_event_t event) override¶ This method is used to notify the model access implementer of events.
- Parameters
event
: event type.
-
dirty_cell_tracker &
get_cell_tracker
() override¶
-
const dirty_cell_tracker &
get_cell_tracker
() const override¶
-
bool
is_empty
(const abs_address_t &addr) const override¶
-
celltype_t
get_celltype
(const abs_address_t &addr) const override¶
-
double
get_numeric_value
(const abs_address_t &addr) const override¶ 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.
- Return
numeric representation of the cell value.
- Parameters
addr
: position of the cell.
-
bool
get_boolean_value
(const abs_address_t &addr) const override¶
-
string_id_t
get_string_identifier
(const abs_address_t &addr) const override¶
-
const std::string *
get_string_value
(const abs_address_t &addr) const override¶ 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.
- Return
pointer to a string value if the cell stores a valid string value, else nullptr.
- Parameters
addr
: position of the cell.
-
const formula_cell *
get_formula_cell
(const abs_address_t &addr) const override¶
-
formula_cell *
get_formula_cell
(const abs_address_t &addr) override¶
-
formula_result
get_formula_result
(const abs_address_t &addr) const override¶
-
const named_expression_t *
get_named_expression
(sheet_t sheet, const std::string &name) const override¶ 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.
- Return
const pointer to the token set if exists, nullptr otherwise.
- Parameters
sheet
: index of the sheet scope to search in.name
: name of the expression.
-
double
count_range
(const abs_range_t &range, const values_t &values_type) const override¶
-
matrix
get_range_value
(const abs_range_t &range) const override¶ Obtain range value in matrix form. Multi-sheet ranges are not supported. If the specified range consists of multiple sheets, it throws an exception.
- Return
range value represented as matrix.
- Parameters
range
: absolute, single-sheet range address. Multi-sheet ranges are not allowed.
-
std::unique_ptr<iface::session_handler>
create_session_handler
() override¶ 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.
- Return
a new session handler instance. It may be nullptr.
-
iface::table_handler *
get_table_handler
() override¶ 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.
- Return
non-NULL pointer to the table storage inside the model, or NULL if no table is present or supported by the model implementation.
-
const iface::table_handler *
get_table_handler
() const override¶
-
string_id_t
append_string
(const char *p, size_t n) override¶
-
string_id_t
add_string
(const char *p, size_t n) override¶
-
const std::string *
get_string
(string_id_t identifier) const override¶
-
sheet_t
get_sheet_index
(const char *p, size_t n) const override¶ Get the index of sheet from sheet name.
- Return
sheet index
- Parameters
p
: pointer to the first character of the sheet name string.n
: length of the sheet name string.
-
size_t
get_sheet_count
() const override¶ Return the number of sheets.
- Return
number of sheets.
-
void
erase_cell
(const abs_address_t &addr)¶
-
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, const char *p, size_t n)¶
-
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.
- Return
pointer to the formula cell instance inserted into the model.
- Parameters
addr
: address at which to set a formula cell.tokens
: formula tokens to put into the formula cell.
-
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.
- Return
pointer to the formula cell instance inserted into the model.
- Parameters
addr
: address at which to set a formula cell.tokens
: formula tokens to put into the formula cell.
-
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.
- Return
pointer to the formula cell instance inserted into the model.
- 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.
-
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
(const char *p, size_t n, formula_tokens_t expr)¶ Set a named expression associated with a string name in the global scope.
- Parameters
p
: pointer to the string buffer that contains the name of the expression.n
: length of the buffer containing the name.expr
: formula tokens to use for the named expression.
-
void
set_named_expression
(const char *p, size_t n, const abs_address_t &origin, formula_tokens_t expr)¶ Set a named expression associated with a string name in the global scope.
- Parameters
p
: pointer to the string buffer that contains the name of the expression.n
: length of the buffer containing the name.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, const char *p, size_t n, 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.p
: pointer to the string buffer that contains the name of the expression.n
: length of the buffer containing the name.expr
: formula tokens to use for the named expression.
-
void
set_named_expression
(sheet_t sheet, const char *p, size_t n, 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.p
: pointer to the string buffer that contains the name of the expression.n
: length of the buffer containing the name.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
(const char *p, size_t n)¶ 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 {} exception. p pointer to the char array storing the name of the inserted sheet. n size of the sheet name char array. sheet index of the inserted sheet.
-
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 {} exception. name name of the sheet to be inserted. 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
(const char *p, size_t n) const¶
-
const column_store_t *
get_column
(sheet_t sheet, col_t col) const¶ Get column storage.
- Return
const pointer to column storage, or NULL in case sheet index or column index is out of bound.
- Parameters
sheet
: sheet index.col
: column index.
-
const column_stores_t *
get_columns
(sheet_t sheet) const¶ Get an array of column stores for the entire sheet.
- Return
const pointer to an array of column stores, or nullptr in case the sheet index is out of bound.
- Parameters
sheet
: sheet index.
-
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.
- Return
model iterator instance.
- Parameters
sheet
: sheet index.dir
: direction of the iteration. Currently, only horizontal direction is supported.range
: range on the specified sheet to iterate over.
-
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.
-
abs_address_set_t
get_all_formula_cells
() const¶ - Deprecated:
This is not generic enough and should be replaced. This functionality should be realized via model_iterator in the future.
-
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 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
-
celltype_t
type
¶
-
bool
boolean
¶
-
double
numeric
¶
-
const char *
string
¶
-
union ixion::model_context::input_cell::[anonymous]
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
¶
-
-
struct
ixion
::
config
¶ This structure store parameters that influence various aspects of the ixion formula engine.
Public Members
-
char
sep_function_arg
¶ Function argument separator. By default it’s ‘,’.
-
char
sep_matrix_column
¶ Matrix column separator.
-
char
sep_matrix_row
¶ Matrix row separator.
-
int8_t
output_precision
¶ Precision to use when converting a numeric value to a string representation. A negative value indicates an unspecified precision.
-
char
-
class
ixion
::
model_iterator
¶ Public Functions
-
model_iterator
()¶
-
model_iterator
(const model_iterator&) = delete¶
-
model_iterator
(model_iterator &&other)¶
-
~model_iterator
()¶
-
model_iterator &
operator=
(const model_iterator&) = delete¶
-
model_iterator &
operator=
(model_iterator &&other)¶
-
bool
has
() const¶
-
void
next
()¶
-
struct
cell
¶ Public Functions
-
cell
()¶
-
cell
(row_t _row, col_t _col, string_id_t _s)¶
-
cell
(row_t _row, col_t _col, const formula_cell *_f)¶
Public Members
-
celltype_t
type
¶
-
bool
boolean
¶
-
double
numeric
¶
-
string_id_t
string
¶
-
const formula_cell *
formula
¶
-
union ixion::model_iterator::cell::[anonymous]
value
¶
-
-