namespace ixion

Enum

cell_t

enum class ixion::cell_t : std::uint8_t

This type represents a raw cell type as stored in ixion::model_context.

Values:

enumerator unknown

unknown cell type.

enumerator string

cell contains a raw string value.

enumerator numeric

cell contains a raw numeric value.

enumerator formula

cell contains a formula object.

enumerator boolean

cell contains a raw boolean value.

enumerator empty

cell is empty and contains absolutely nothing.

cell_value_t

enum class ixion::cell_value_t : std::uint8_t

Similar to cell_t, except that it does not include a formula type. Instead it uses the formula result type to classify its type. The error type refers to an error value in formula cell.

Values:

enumerator unknown

unknown cell value type.

enumerator string

either the cell contains a raw string value, or a calculated formula cell whose result is of string type.

enumerator numeric

either the cell contains a raw numeric value, or a calculated formula cell whose result is of numeric type.

enumerator error

this type corresponds with a formula cell whose result contains an error.

enumerator boolean

either the cell contains a raw boolean value type, or a calculated formula cell whose result is of boolean type.

enumerator empty

the cell is empty and contains nothing whatsoever.

column_block_t

enum class ixion::column_block_t : int

Type of a column block that stores a series of adjacent cell values of the same type.

Values:

enumerator unknown
enumerator empty
enumerator boolean
enumerator numeric
enumerator string
enumerator formula

display_sheet_t

enum class ixion::display_sheet_t

Specifies how to determine whether or not to display a sheet name of a cell or range reference.

Values:

enumerator unspecified

Sheet name display preference is not specified.

enumerator always

Sheet name should be always displayed.

enumerator never

Sheet name should never be displayed.

enumerator only_if_different

Sheet name should be displayed only when the sheet index of a reference is different from that of the position of a referencing cell.

fopcode_t

enum ixion::fopcode_t

formula opcode type

Values:

enumerator fop_unknown
enumerator fop_single_ref
enumerator fop_range_ref
enumerator fop_table_ref
enumerator fop_named_expression
enumerator fop_string
enumerator fop_value
enumerator fop_function
enumerator fop_error
enumerator fop_plus
enumerator fop_minus
enumerator fop_divide
enumerator fop_multiply
enumerator fop_exponent
enumerator fop_concat
enumerator fop_equal
enumerator fop_not_equal
enumerator fop_less
enumerator fop_greater
enumerator fop_less_equal
enumerator fop_greater_equal
enumerator fop_open
enumerator fop_close
enumerator fop_sep
enumerator fop_array_row_sep
enumerator fop_array_open
enumerator fop_array_close
enumerator fop_invalid_formula

formula_error_t

enum class ixion::formula_error_t : std::uint8_t

Formula error types. Note that only the official (i.e. non-internal) error types have their corresponding error strings. Use the get_formula_error_name() function to convert an enum member value of this type to its string representation.

Values:

enumerator no_error
enumerator ref_result_not_available
enumerator division_by_zero
enumerator invalid_expression
enumerator name_not_found
enumerator no_range_intersection
enumerator invalid_value_type
enumerator no_value_available
enumerator no_result_error
enumerator stack_error
enumerator general_error

formula_event_t

enum class ixion::formula_event_t

Formula event type used for event notification during calculation of formula cells.

Values:

enumerator calculation_begins

Start of the calculations of formula cells.

enumerator calculation_ends

End of the calculations of formula cells.

formula_function_t

enum class ixion::formula_function_t : uint16_t

Enum that represents built-in formula functions.

Values:

enumerator func_unknown
enumerator func_abs
enumerator func_acos
enumerator func_acosh
enumerator func_acot
enumerator func_acoth
enumerator func_address
enumerator func_aggregate
enumerator func_and
enumerator func_arabic
enumerator func_areas
enumerator func_asc
enumerator func_asin
enumerator func_asinh
enumerator func_atan
enumerator func_atan2
enumerator func_atanh
enumerator func_avedev
enumerator func_average
enumerator func_averagea
enumerator func_averageif
enumerator func_averageifs
enumerator func_b
enumerator func_bahttext
enumerator func_base
enumerator func_betadist
enumerator func_betainv
enumerator func_binomdist
enumerator func_bitand
enumerator func_bitlshift
enumerator func_bitor
enumerator func_bitrshift
enumerator func_bitxor
enumerator func_ceiling
enumerator func_cell
enumerator func_char
enumerator func_chidist
enumerator func_chiinv
enumerator func_chisqdist
enumerator func_chisqinv
enumerator func_chitest
enumerator func_choose
enumerator func_clean
enumerator func_code
enumerator func_color
enumerator func_column
enumerator func_columns
enumerator func_combin
enumerator func_combina
enumerator func_concat
enumerator func_concatenate
enumerator func_confidence
enumerator func_correl
enumerator func_cos
enumerator func_cosh
enumerator func_cot
enumerator func_coth
enumerator func_count
enumerator func_counta
enumerator func_countblank
enumerator func_countif
enumerator func_countifs
enumerator func_covar
enumerator func_critbinom
enumerator func_csc
enumerator func_csch
enumerator func_cumipmt
enumerator func_cumprinc
enumerator func_current
enumerator func_date
enumerator func_datedif
enumerator func_datevalue
enumerator func_daverage
enumerator func_day
enumerator func_days
enumerator func_days360
enumerator func_db
enumerator func_dcount
enumerator func_dcounta
enumerator func_ddb
enumerator func_dde
enumerator func_decimal
enumerator func_degrees
enumerator func_devsq
enumerator func_dget
enumerator func_dmax
enumerator func_dmin
enumerator func_dollar
enumerator func_dproduct
enumerator func_dstdev
enumerator func_dstdevp
enumerator func_dsum
enumerator func_dvar
enumerator func_dvarp
enumerator func_eastersunday
enumerator func_effect
enumerator func_encodeurl
enumerator func_errortype
enumerator func_euroconvert
enumerator func_even
enumerator func_exact
enumerator func_exp
enumerator func_expondist
enumerator func_fact
enumerator func_false
enumerator func_fdist
enumerator func_filterxml
enumerator func_find
enumerator func_findb
enumerator func_finv
enumerator func_fisher
enumerator func_fisherinv
enumerator func_fixed
enumerator func_floor
enumerator func_forecast
enumerator func_formula
enumerator func_fourier
enumerator func_frequency
enumerator func_ftest
enumerator func_fv
enumerator func_gamma
enumerator func_gammadist
enumerator func_gammainv
enumerator func_gammaln
enumerator func_gauss
enumerator func_gcd
enumerator func_geomean
enumerator func_getpivotdata
enumerator func_goalseek
enumerator func_growth
enumerator func_harmean
enumerator func_hlookup
enumerator func_hour
enumerator func_hyperlink
enumerator func_hypgeomdist
enumerator func_if
enumerator func_iferror
enumerator func_ifna
enumerator func_ifs
enumerator func_index
enumerator func_indirect
enumerator func_info
enumerator func_int
enumerator func_intercept
enumerator func_ipmt
enumerator func_irr
enumerator func_isblank
enumerator func_iserr
enumerator func_iserror
enumerator func_iseven
enumerator func_isformula
enumerator func_islogical
enumerator func_isna
enumerator func_isnontext
enumerator func_isnumber
enumerator func_isodd
enumerator func_isoweeknum
enumerator func_ispmt
enumerator func_isref
enumerator func_istext
enumerator func_jis
enumerator func_kurt
enumerator func_large
enumerator func_lcm
enumerator func_left
enumerator func_leftb
enumerator func_len
enumerator func_lenb
enumerator func_linest
enumerator func_ln
enumerator func_log
enumerator func_log10
enumerator func_logest
enumerator func_loginv
enumerator func_lognormdist
enumerator func_lookup
enumerator func_lower
enumerator func_match
enumerator func_max
enumerator func_maxa
enumerator func_maxifs
enumerator func_mdeterm
enumerator func_median
enumerator func_mid
enumerator func_midb
enumerator func_min
enumerator func_mina
enumerator func_minifs
enumerator func_minute
enumerator func_minverse
enumerator func_mirr
enumerator func_mmult
enumerator func_mod
enumerator func_mode
enumerator func_month
enumerator func_multirange
enumerator func_munit
enumerator func_mvalue
enumerator func_n
enumerator func_na
enumerator func_neg
enumerator func_negbinomdist
enumerator func_networkdays
enumerator func_nominal
enumerator func_normdist
enumerator func_norminv
enumerator func_normsdist
enumerator func_normsinv
enumerator func_not
enumerator func_now
enumerator func_nper
enumerator func_npv
enumerator func_numbervalue
enumerator func_odd
enumerator func_offset
enumerator func_or
enumerator func_pduration
enumerator func_pearson
enumerator func_percentile
enumerator func_percentrank
enumerator func_permut
enumerator func_permutationa
enumerator func_phi
enumerator func_pi
enumerator func_pmt
enumerator func_poisson
enumerator func_power
enumerator func_ppmt
enumerator func_prob
enumerator func_product
enumerator func_proper
enumerator func_pv
enumerator func_quartile
enumerator func_radians
enumerator func_rand
enumerator func_rank
enumerator func_rate
enumerator func_rawsubtract
enumerator func_regex
enumerator func_replace
enumerator func_replaceb
enumerator func_rept
enumerator func_right
enumerator func_rightb
enumerator func_roman
enumerator func_round
enumerator func_rounddown
enumerator func_roundsig
enumerator func_roundup
enumerator func_row
enumerator func_rows
enumerator func_rri
enumerator func_rsq
enumerator func_search
enumerator func_searchb
enumerator func_sec
enumerator func_sech
enumerator func_second
enumerator func_sheet
enumerator func_sheets
enumerator func_sign
enumerator func_sin
enumerator func_sinh
enumerator func_skew
enumerator func_skewp
enumerator func_sln
enumerator func_slope
enumerator func_small
enumerator func_sqrt
enumerator func_standardize
enumerator func_stdev
enumerator func_stdeva
enumerator func_stdevp
enumerator func_stdevpa
enumerator func_steyx
enumerator func_style
enumerator func_substitute
enumerator func_subtotal
enumerator func_sum
enumerator func_sumif
enumerator func_sumifs
enumerator func_sumproduct
enumerator func_sumsq
enumerator func_sumx2my2
enumerator func_sumx2py2
enumerator func_sumxmy2
enumerator func_switch
enumerator func_syd
enumerator func_t
enumerator func_tan
enumerator func_tanh
enumerator func_tdist
enumerator func_text
enumerator func_textjoin
enumerator func_time
enumerator func_timevalue
enumerator func_tinv
enumerator func_today
enumerator func_transpose
enumerator func_trend
enumerator func_trim
enumerator func_trimmean
enumerator func_true
enumerator func_trunc
enumerator func_ttest
enumerator func_type
enumerator func_unichar
enumerator func_unicode
enumerator func_upper
enumerator func_value
enumerator func_var
enumerator func_vara
enumerator func_varp
enumerator func_varpa
enumerator func_vdb
enumerator func_vlookup
enumerator func_wait
enumerator func_webservice
enumerator func_weekday
enumerator func_weeknum
enumerator func_weibull
enumerator func_xor
enumerator func_year
enumerator func_ztest

formula_name_resolver_t

enum class ixion::formula_name_resolver_t

Formula name resolver type specifies how name tokens are resolved.

Values:

enumerator unknown

Unknown syntax.

enumerator excel_a1

Default A1 syntax used in Excel

enumerator excel_r1c1

R1C1 syntax available in Excel

enumerator calc_a1

Default A1 syntax used in Calc

enumerator odff

OpenFormula syntax

enumerator odf_cra

ODF cell-range-address syntax

formula_result_wait_policy_t

enum class ixion::formula_result_wait_policy_t

Type of policy on what to do when querying for the result of a formula cell whose result has not yet been calculated.

Values:

enumerator block_until_done

Querying for the result of a formula cell will block until the calculation is complete.

enumerator throw_exception

Querying for the result of a formula cell that has not yet been calculated will throw an exception.

rc_direction_t

enum class ixion::rc_direction_t

Specifies iterator direction of a ixion::model_context.

Values:

enumerator horizontal

Flows left to right first then top to bottom.

enumerator vertical

Flows top to bottom first then left to right.

table_area_t

enum ixion::table_area_t

Value that specifies the area inside a table.

Values:

enumerator table_area_none
enumerator table_area_data
enumerator table_area_headers
enumerator table_area_totals
enumerator table_area_all

value_t

enum ixion::value_t

Values:

enumerator value_none
enumerator value_string
enumerator value_numeric
enumerator value_boolean
enumerator value_empty

Type aliases

abs_address_set_t

using ixion::abs_address_set_t = std::unordered_set<abs_address_t, abs_address_t::hash>

Type that represents a collection of multiple absolute cell addresses.

abs_range_set_t

using ixion::abs_range_set_t = std::unordered_set<abs_range_t, abs_range_t::hash>

abs_rc_range_set_t

using ixion::abs_rc_range_set_t = std::unordered_set<abs_rc_range_t, abs_rc_range_t::hash>

calc_status_ptr_t

using ixion::calc_status_ptr_t = boost::intrusive_ptr<calc_status>

col_t

using ixion::col_t = std::int32_t

Column index type.

column_block_callback_t

using ixion::column_block_callback_t = std::function<bool(col_t, row_t, row_t, const column_block_shape_t&)>

Callback function type to be used during traversal of column data.

column_block_handle

using ixion::column_block_handle = void*

formula_tokens_store_ptr_t

using ixion::formula_tokens_store_ptr_t = boost::intrusive_ptr<formula_tokens_store>

formula_tokens_t

using ixion::formula_tokens_t = std::vector<formula_token>

rc_t

using ixion::rc_t = row_t

Integer type that is large enough to store either a row or a column index.

row_t

using ixion::row_t = std::int32_t

Row index type.

sheet_t

using ixion::sheet_t = std::int32_t

Sheet index type.

string_id_t

using ixion::string_id_t = std::uint32_t

String ID type.

All string values are converted into integer tokens. You need to call the get_string() method of ixion::model_context to get the actual string value.

table_areas_t

using ixion::table_areas_t = std::int32_t

type that stores a mixture of ixion::table_area_t values.

Constants

column_unset

const col_t ixion::column_unset

Column address not specified. This is used to reference an entire row when a specific row address is given.

column_upper_bound

const col_t ixion::column_upper_bound

Highest number that can be used to reference a column address. Numbers higher than this number are all used as special indices.

empty_string_id

const string_id_t ixion::empty_string_id

Global string ID representing an empty string.

global_scope

const sheet_t ixion::global_scope

Special sheet ID that represents a global scope, as opposed to a sheet-local scope.

invalid_sheet

const sheet_t ixion::invalid_sheet

Special sheet ID that represents an invalid sheet.

row_unset

const row_t ixion::row_unset

Row address not specified. This is used to reference an entire column when a specific column address is given.

row_upper_bound

const row_t ixion::row_upper_bound

Highest number that can be used to reference a row address. Numbers higher than this number are all used as special indices.

Functions

calculate_sorted_cells

void ixion::calculate_sorted_cells(model_context &cxt, const std::vector<abs_range_t> &formula_cells, size_t thread_count)

Calculate all specified formula cells in the order they occur in the sequence.

Parameters:
  • cxt – model context.

  • formula_cells – formula cells to be calculated. The cells will be calculated in the order they appear in the sequence. In a typical use case, this will be the returned value from query_and_sort_dirty_cells.

  • thread_count – number of calculation threads to use. Note that passing 0 will make the process use the main thread only, while passing any number greater than 0 will make the process spawn specified number of calculation threads plus one additional thread to manage the calculation threads.

create_formula_error_tokens

formula_tokens_t ixion::create_formula_error_tokens(model_context &cxt, std::string_view src_formula, std::string_view error)

Create a set of tokens that represent an invalid formula.

This can be used for a cell containing an invalid formula expression, and the error information needs to be preserved.

Parameters:
  • cxt – model context.

  • src_formula – original formula string.

  • error – error string.

Returns:

a set of tokens, the first of which is a token of type fop_error, followed by two string tokens. The second token stores the original formula string, whereas the third one stores the error string. The first token stores the number of tokens that follows as its value of type std::size_t, which is always 2 in the current implementation.

get_api_version_major

int ixion::get_api_version_major()

get_api_version_minor

int ixion::get_api_version_minor()

get_current_time

double ixion::get_current_time()

Get current time in seconds since epoch. Note that the value representing a time may differ from platform to platform. Use this value only to measure relative time.

Returns:

current time in seconds since epoch.

get_formula_error_name

std::string_view ixion::get_formula_error_name(formula_error_t fe)

Get a string representation of a formula error type.

Parameters:

fe – enum value representing a formula error type.

Returns:

null-terminated string representation of the formula error type.

get_formula_function_name

std::string_view ixion::get_formula_function_name(formula_function_t func)

Get a string representation of a formula function opcode.

Parameters:

func – formula function opcode.

Returns:

string representation of the opcode.

get_formula_function_opcode

formula_function_t ixion::get_formula_function_opcode(std::string_view s)

Get a formula function opcode from a formula function name.

Parameters:

s – formula function name.

Returns:

formula function opcode representing the specified name.

get_formula_opcode_name

std::string_view ixion::get_formula_opcode_name(fopcode_t oc)

Get a printable name for a formula opcode. The printable name is to be used only for informational purposes.

Parameters:

oc – formula opcode

Returns:

printable name for a formula opcode.

get_formula_opcode_string

std::string_view ixion::get_formula_opcode_string(fopcode_t oc)

Get the string representation of a simple formula opcode. This function will return a non-empty string only for operator opcodes.

Parameters:

oc – formula opcode

Returns:

string representation of a formula opcode.

get_version_major

int ixion::get_version_major()

get_version_micro

int ixion::get_version_micro()

get_version_minor

int ixion::get_version_minor()

intrusive_ptr_add_ref

inline void ixion::intrusive_ptr_add_ref(formula_tokens_store *p)

intrusive_ptr_release

inline void ixion::intrusive_ptr_release(formula_tokens_store *p)

is_valid_sheet

bool ixion::is_valid_sheet(sheet_t sheet)

Determine whether or not a given sheet index is valid.

Parameters:

sheet – sheet index to test.

Returns:

true if the sheet index is valid, false otherwise.

parse_formula_string

formula_tokens_t ixion::parse_formula_string(model_context &cxt, const abs_address_t &pos, const formula_name_resolver &resolver, std::string_view formula)

Parse a raw formula expression string into formula tokens.

Parameters:
  • cxt – model context.

  • pos – address of the cell that has the formula expression.

  • resolver – name resolver object used to resolve name tokens.

  • formula – raw formula expression string to parse.

Returns:

formula tokens representing the parsed formula expression.

print_formula_token

std::string ixion::print_formula_token(const print_config &config, const model_context &cxt, const abs_address_t &pos, const formula_name_resolver &resolver, const formula_token &token)

Convert an individual formula token into a human-readable string representation.

Parameters:
  • config – Configuration options for printing preferences.

  • cxt – Model context.

  • pos – Address of the cell that has the formula tokens.

  • resolver – Name resolver object used to print name tokens.

  • token – Formula token to convert.

Returns:

string representation of the formula token.

print_formula_tokens

std::string ixion::print_formula_tokens(const print_config &config, const model_context &cxt, const abs_address_t &pos, const formula_name_resolver &resolver, const formula_tokens_t &tokens)

Convert formula tokens into a human-readable string representation.

Parameters:
  • config – Configuration options for printing preferences.

  • cxt – Model context.

  • pos – Address of the cell that has the formula tokens.

  • resolver – Name resolver object used to print name tokens.

  • tokens – Formula tokens to print.

Returns:

string representation of the formula tokens.

query_and_sort_dirty_cells

std::vector<abs_range_t> ixion::query_and_sort_dirty_cells(model_context &cxt, const abs_range_set_t &modified_cells, const abs_range_set_t *dirty_formula_cells = nullptr)

Get a sequence of the positions of all formula cells that track at least one of the specified modified cells either directly or indirectly. Such formula cells are referred to as “dirty” formula cells. The sequence returned from this function is already sorted in topological order based on the dependency relationships between the affected formula cells. Note that if the model contains volatile formula cells, they will be included in the returned sequence each and every time.

Use query_dirty_cells() instead if you don’t need the results to be sorted in order of dependency, to avoid the extra overhead incurred by the sorting.

Parameters:
  • cxt – model context.

  • modified_cells – a collection of non-formula cells whose values have been updated. You can specify one or more ranges of cells rather than individual cell positions.

  • dirty_formula_cells – (optional) a collection of formula cells that are already known to be dirty. These formula cells will be added to the list of the affected formula cells returned from this function. Note that even though this parameter is a set of cell ranges, regular formula cell positions must be given as single cell addresses. Only the positions of grouped formula cells must be given as ranges.

Returns:

an sequence containing the positions of the formula cells that track at least one of the modified cells, as well as those formula cells that are already known to be dirty.

query_dirty_cells

abs_address_set_t ixion::query_dirty_cells(model_context &cxt, const abs_address_set_t &modified_cells)

Get the positions of those formula cells that directly or indirectly depend on the specified source cells.

Parameters:
  • cxt – model context.

  • modified_cells – collection of the postiions of cells that have been modified.

Returns:

collection of the positions of formula cells that directly or indirectly depend on at least one of the specified source cells.

register_formula_cell

void ixion::register_formula_cell(model_context &cxt, const abs_address_t &pos, const formula_cell *cell = nullptr)

Regisiter a formula cell with cell dependency tracker.

Parameters:
  • cxt – model context.

  • pos – address of the cell being registered. In case of grouped cells, the position must be that of teh top-left cell of that group.

  • cell – (optional) pointer to the formula cell object to register. You can skip this parameter, in which case the formula cell object will be fetched from the address of the cell. But passing a pointer will save the overhead of fetching.

to_bool

bool ixion::to_bool(std::string_view s)

to_double

double ixion::to_double(std::string_view s)

to_formula_error_type

formula_error_t ixion::to_formula_error_type(std::string_view s)

Parse a formula error string and convert it to a corresponding enum value.

Parameters:

s – string representation of a formula error type.

Returns:

enum value for a formula error type.

unregister_formula_cell

void ixion::unregister_formula_cell(model_context &cxt, const abs_address_t &pos)

Unregister a formula cell with cell dependency tracker if a formula cell exists at specified cell address. If there is no existing cell at the specified address, or the cell is not a formula cell, this function is a no-op.

Parameters:
  • cxt – model context.

  • pos – address of the cell being unregistered.

Struct

abs_address_t

struct abs_address_t

Stores absolute address, and absolute address only.

Public Types

enum init_invalid

Values:

enumerator invalid

Public Functions

abs_address_t()
abs_address_t(init_invalid)
abs_address_t(sheet_t _sheet, row_t _row, col_t _column)
abs_address_t(const abs_address_t &r)
bool valid() const
::std::string get_name() const

Public Members

sheet_t sheet
row_t row
col_t column
struct hash

Public Functions

size_t operator()(const abs_address_t &addr) const

abs_range_t

struct abs_range_t

Stores absolute range address.

Public Types

enum init_invalid

Values:

enumerator invalid

Public Functions

abs_range_t()
abs_range_t(init_invalid)
abs_range_t(sheet_t _sheet, row_t _row, col_t _col)
abs_range_t(sheet_t _sheet, row_t _row, col_t _col, row_t _row_span, col_t _col_span)
Parameters:
  • _sheet – 0-based sheet index.

  • _row – 0-based row position of the top-left cell of the range.

  • _col – 0-based column position of the top-left cell of the range.

  • _row_span – row length of the range. It must be 1 or greater.

  • _col_span – column length of the range. It must be 1 or greater.

abs_range_t(const abs_address_t &addr)
abs_range_t(const abs_address_t &addr, row_t row_span, col_t col_span)
bool valid() const
void set_all_columns()

Expand the range horizontally to include all columns. The row range will remain unchanged.

void set_all_rows()

Expand the range vertically to include all rows. The column range will remain unchanged.

bool all_columns() const
Returns:

true if the range is unspecified in the horizontal direction i.e. all columns are selected, false otherwise.

bool all_rows() const
Returns:

true if the range is unspecified in the vertical direction i.e. all rows are selected, false otherwise.

bool contains(const abs_address_t &addr) const

Check whether or not a given address is contained within this range.

void reorder()

Reorder range values as needed to ensure the range is valid.

Public Members

abs_address_t first
abs_address_t last
struct hash

Public Functions

size_t operator()(const abs_range_t &range) const

abs_rc_address_t

struct abs_rc_address_t

Public Types

enum init_invalid

Values:

enumerator invalid

Public Functions

abs_rc_address_t()
abs_rc_address_t(init_invalid)
abs_rc_address_t(row_t _row, col_t _column)
abs_rc_address_t(const abs_rc_address_t &r)
abs_rc_address_t(const abs_address_t &r)
bool valid() const

Public Members

row_t row
col_t column
struct hash

Public Functions

size_t operator()(const abs_rc_address_t &addr) const

abs_rc_range_t

struct abs_rc_range_t

Public Types

enum init_invalid

Values:

enumerator invalid

Public Functions

abs_rc_range_t()
abs_rc_range_t(init_invalid)
abs_rc_range_t(const abs_rc_range_t &other)
abs_rc_range_t(const abs_range_t &other)
bool valid() const
void set_all_columns()

Expand the range horizontally to include all columns. The row range will remain unchanged.

void set_all_rows()

Expand the range vertically to include all rows. The column range will remain unchanged.

bool all_columns() const
Returns:

true if the range is unspecified in the horizontal direction i.e. all columns are selected, false otherwise.

bool all_rows() const
Returns:

true if the range is unspecified in the vertical direction i.e. all rows are selected, false otherwise.

bool contains(const abs_rc_address_t &addr) const

Check whether or not a given address is contained within this range.

Public Members

abs_rc_address_t first
abs_rc_address_t last
struct hash

Public Functions

size_t operator()(const abs_rc_range_t &range) const

address_t

struct address_t

Stores either absolute or relative address.

Public Functions

address_t()
address_t(sheet_t _sheet, row_t _row, col_t _column, bool _abs_sheet = true, bool _abs_row = true, bool _abs_column = true)
address_t(const address_t &r)
address_t(const abs_address_t &r)
bool valid() const
abs_address_t to_abs(const abs_address_t &origin) const
::std::string get_name() const
void set_absolute(bool abs)

Public Members

sheet_t sheet
row_t row
col_t column
bool abs_sheet
bool abs_row
bool abs_column
struct hash

Public Functions

size_t operator()(const address_t &addr) const

column_block_shape_t

struct column_block_shape_t

Data that represents the shape of a column block.

Public Functions

column_block_shape_t()
column_block_shape_t(std::size_t _position, std::size_t _size, std::size_t _offset, column_block_t _type, column_block_handle _data)
column_block_shape_t(const column_block_shape_t &other)
column_block_shape_t &operator=(const column_block_shape_t &other)

Public Members

std::size_t position
std::size_t size
std::size_t offset
column_block_t type
column_block_handle data

config

struct config

This structure store parameters that influence various aspects of the ixion formula engine.

Public Functions

config()
config(const config &r)

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.

formula_group_t

struct formula_group_t

This strcuture stores information about grouped formula cells. All formula cells belonging to the same group shares the same set of values.

Public Functions

formula_group_t()
formula_group_t(const formula_group_t &r)
formula_group_t(const rc_size_t &_group_size, uintptr_t _identity, bool _grouped)
~formula_group_t()
formula_group_t &operator=(const formula_group_t &other)

Public Members

rc_size_t size

Size of the formula group.

uintptr_t identity

Unique value identifying the group a cell belongs to. Cells belonging to the same formula group should have the same value.

bool grouped

Boolean value indicating whether or not a cell is grouped.

formula_name_t

struct formula_name_t

Structure that represents the type of a ‘name’ in a formula expression.

A name can be either one of:

  • cell reference

  • range reference

  • table reference

  • named expression

  • function

Public Types

enum name_type

Values:

enumerator invalid
enumerator cell_reference
enumerator range_reference
enumerator table_reference
enumerator named_expression
enumerator function
using value_type = std::variant<address_t, range_t, table_type, formula_function_t>

Public Functions

formula_name_t()
std::string to_string() const

Return a string that represents the data stored internally. Useful for debugging.

Public Members

name_type type
value_type value
struct table_type

Table information for a table reference name. Unlike the ixion::table_t counterpart, we store strings as string views as the resolver doesn’t have access to the string pool.

Public Members

std::string_view name
std::string_view column_first
std::string_view column_last
table_areas_t areas

formula_token

struct formula_token

Represents a single formula token.

Public Types

using value_type = std::variant<address_t, range_t, table_t, formula_error_t, formula_function_t, double, string_id_t, std::string>

Public Functions

formula_token() = delete
formula_token(fopcode_t op)

Constructor for opcode-only token.

Parameters:

op – formula opcode.

formula_token(const address_t &addr)

Constructor for a single-cell reference token. The opcode will be implicitly set to fop_single_ref.

Parameters:

addr – single-cell reference.

formula_token(const range_t &range)

Constructor for a range reference token. The opcode will be implicitly set to fop_range_ref.

Parameters:

range – range reference.

formula_token(const table_t &table)

Constructor for a table reference token. The opcode will be implicitly set to fop_table_ref.

Parameters:

table – table reference.

formula_token(formula_function_t func)

Constructor for a formula function token. The opcode will be implicitly set to fop_function.

Parameters:

func – function name enum value.

formula_token(formula_error_t err)

Constructor for a formula error token. The opcode will be implicitly set to fop_error.

Parameters:

err – error token value.

formula_token(double v)

Constructor for a numeric value token. The opcode will be implicitly set to fop_value.

Parameters:

v – numeric value to be stored in the token.

formula_token(string_id_t sid)

Constructor for a string value token. The opcode will be implicitly set to fop_string.

Parameters:

sid – string ID to be stored in the token.

formula_token(std::string name)

Constructor for a named-expression token. The opcode will be implicitly set to fop_named_expression.

Parameters:

name – named expression to be stored in the token.

formula_token(const formula_token &r)

Copy constructor.

formula_token(formula_token &&r)

Move constructor.

Note

This will be the same as the copy constructor if the stored value is not movable.

~formula_token()
bool operator==(const formula_token &r) const
bool operator!=(const formula_token &r) const

Public Members

const fopcode_t opcode

Opcode that specifies the type of token. The value of this data member should not be modified after construction.

value_type value

Value stored in the token. The type of this value varies depending on the token opcode value.

named_expression_t

struct named_expression_t

Represents a named expression which stores a series of formula tokens.

Public Functions

named_expression_t()
named_expression_t(const abs_address_t &_origin, formula_tokens_t _tokens)
named_expression_t(const named_expression_t&) = delete
named_expression_t(named_expression_t &&other)
~named_expression_t()

Public Members

abs_address_t origin

Origin cell position which affects any relative references stored in the named expression.

formula_tokens_t tokens

Formula tokens.

range_t

struct range_t

Stores range whose component may be relative or absolute.

Public Functions

range_t()
range_t(const address_t &_first, const address_t &_last)
range_t(const range_t &r)
range_t(const abs_range_t &r)
bool valid() const
void set_all_columns()

Expand the range horizontally to include all columns. The row range will remain unchanged.

void set_all_rows()

Expand the range vertically to include all rows. The column range will remain unchanged.

bool all_columns() const
Returns:

true if the range is unspecified in the horizontal direction i.e. all columns are selected, false otherwise.

bool all_rows() const
Returns:

true if the range is unspecified in the vertical direction i.e. all rows are selected, false otherwise.

abs_range_t to_abs(const abs_address_t &origin) const
void set_absolute(bool abs)

Public Members

address_t first
address_t last
struct hash

Public Functions

size_t operator()(const range_t &range) const

rc_address_t

struct rc_address_t

Stores either absolute or relative address, but unlike the address_t counterpart, this struct only stores row and column positions.

Public Functions

rc_address_t()
rc_address_t(row_t _row, col_t _column, bool _abs_row = true, bool _abs_column = true)
rc_address_t(const rc_address_t &r)
rc_address_t(const abs_rc_address_t &r)

Public Members

row_t row
col_t column
bool abs_row
bool abs_column
struct hash

Public Functions

size_t operator()(const rc_address_t &addr) const

rc_range_t

struct rc_range_t

Public Functions

rc_range_t()
rc_range_t(const rc_address_t &_first, const rc_address_t &_last)
rc_range_t(const rc_range_t &r)
rc_range_t(const abs_rc_range_t &r)
bool valid() const
void set_all_columns()

Expand the range horizontally to include all columns. The row range will remain unchanged.

void set_all_rows()

Expand the range vertically to include all rows. The column range will remain unchanged.

bool all_columns() const
Returns:

true if the range is unspecified in the horizontal direction i.e. all columns are selected, false otherwise.

bool all_rows() const
Returns:

true if the range is unspecified in the vertical direction i.e. all rows are selected, false otherwise.

Public Members

rc_address_t first
rc_address_t last
struct hash

Public Functions

size_t operator()(const rc_range_t &range) const

rc_size_t

struct rc_size_t

This structure stores a 2-dimensional size information.

Public Functions

rc_size_t()
rc_size_t(const rc_size_t &other)
rc_size_t(row_t _row, col_t _column)
~rc_size_t()
rc_size_t &operator=(const rc_size_t &other)

Public Members

row_t row
col_t column

table_t

struct table_t

Public Functions

table_t()
bool operator==(const table_t &r) const
bool operator!=(const table_t &r) const

Public Members

string_id_t name
string_id_t column_first
string_id_t column_last
table_areas_t areas

Classes

abs_address_iterator

class abs_address_iterator

Public Functions

abs_address_iterator(const abs_range_t &range, rc_direction_t dir)
~abs_address_iterator()
const_iterator begin() const
const_iterator end() const
const_iterator cbegin() const
const_iterator cend() const
class const_iterator

Public Types

using value_type = abs_address_t

Public Functions

const_iterator()
const_iterator(const const_iterator &r)
const_iterator(const_iterator &&r)
~const_iterator()
const_iterator &operator++()
const_iterator operator++(int)
const_iterator &operator--()
const_iterator operator--(int)
const value_type &operator*() const
const value_type *operator->() const
bool operator==(const const_iterator &r) const
bool operator!=(const const_iterator &r) const

cell_access

class cell_access

This class provides a read-only access to a single cell. It’s more efficient to use this class if you need to make multiple successive queries to the same cell.

Note that an instance of this class will get invalidated when the content of ixion::model_context is modified.

Public Functions

cell_access(cell_access &&other)
cell_access &operator=(cell_access &&other)
~cell_access()
cell_t get_type() const
cell_value_t get_value_type() const
const formula_cell *get_formula_cell() const
formula_result get_formula_result() const
double get_numeric_value() const
bool get_boolean_value() const
std::string_view get_string_value() const
string_id_t get_string_identifier() const
formula_error_t get_error_value() const

dirty_cell_tracker

class dirty_cell_tracker

This class is designed to track in-direct dependencies of dirty formula cells. A “dirty” formula cell is a formula cell whose result needs to be re-calculated because at one or more of its references have updated values.

This class also takes volatile functions into account when determining the status of the formula cell result. A volatile function is a cell function whose value needs to be re-calculated on every re-calculation. One example of a volatile function is NOW(), which returns the current time at the time of calculation.

Public Functions

dirty_cell_tracker(const dirty_cell_tracker&) = delete
dirty_cell_tracker &operator=(const dirty_cell_tracker&) = delete
dirty_cell_tracker()
~dirty_cell_tracker()
void add(const abs_range_t &src, const abs_range_t &dest)

Add a tracking relationship from a source cell or cell range to a destination cell or cell range.

Parameters:
  • src – source cell or cell range that includes reference to (therefore listens to) the range.

  • dest – destination cell or range referenced tracked by the source cell.

void remove(const abs_range_t &src, const abs_range_t &dest)

Remove an existing tracking relationship from a source cell or cell range to a destination cell or cell range. If no such relationship exists, it does nothing.

Parameters:
  • src – cell or cell range that includes reference to the range.

  • dest – cell or range referenced by the cell.

void add_volatile(const abs_range_t &pos)

Register a formula cell located at the specified position as volatile. Note that the caller should ensure that the cell at the specified position is indeed a formula cell.

Parameters:

pos – position of the cell to register as a volatile cell.

void remove_volatile(const abs_range_t &pos)

Remove the specified cell position from the internal set of registered volatile formula cells.

Parameters:

pos – position of the cell to unregister as a volatile cell.

abs_range_set_t query_dirty_cells(const abs_range_t &modified_cell) const
abs_range_set_t query_dirty_cells(const abs_range_set_t &modified_cells) const
std::vector<abs_range_t> query_and_sort_dirty_cells(const abs_range_t &modified_cell) const
std::vector<abs_range_t> query_and_sort_dirty_cells(const abs_range_set_t &modified_cells, const abs_range_set_t *dirty_formula_cells = nullptr) const
std::string to_string() const
bool empty() const

document

class document

Higher level document representation designed to handle both cell value storage as well as formula cell calculations.

Public Functions

document()
document(formula_name_resolver_t cell_address_type)

Constructor with custom cell address type.

Parameters:

cell_address_type – cell address type to use for cell addresses represented by string values.

~document()
void append_sheet(std::string name)
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.

cell_access get_cell_access(const cell_pos &pos) const
void set_numeric_cell(const cell_pos &pos, double val)
void set_string_cell(const cell_pos &pos, std::string_view s)
void set_boolean_cell(const cell_pos &pos, bool val)
void empty_cell(const cell_pos &pos)
double get_numeric_value(const cell_pos &pos) const
std::string_view get_string_value(const cell_pos &pos) const
void set_formula_cell(const cell_pos &pos, std::string_view formula)
void calculate(size_t thread_count)

Calculate all the “dirty” formula cells in the document.

Parameters:

thread_count – number of threads to use to perform calculation. When 0 is specified, it only uses the main thread.

struct cell_pos

Public Types

enum class cp_type

Values:

enumerator string
enumerator address

Public Functions

cell_pos() = delete
cell_pos(const char *p)
cell_pos(std::string_view s)
cell_pos(const std::string &s)
cell_pos(const abs_address_t &addr)
cell_pos(const cell_pos &other)
cell_pos &operator=(const cell_pos &other)

Public Members

cp_type type
std::variant<std::string_view, ixion::abs_address_t> value

file_not_found

class file_not_found : public ixion::general_error

Public Functions

explicit file_not_found(const std::string &fpath)
virtual ~file_not_found() override

formula_cell

class formula_cell

Public Functions

formula_cell(const formula_cell&) = delete
formula_cell &operator=(formula_cell) = delete
formula_cell()
formula_cell(const formula_tokens_store_ptr_t &tokens)
formula_cell(row_t group_row, col_t group_col, const calc_status_ptr_t &cs, const formula_tokens_store_ptr_t &tokens)
~formula_cell()
const formula_tokens_store_ptr_t &get_tokens() const
void set_tokens(const formula_tokens_store_ptr_t &tokens)
double get_value(formula_result_wait_policy_t policy) const
std::string_view get_string(formula_result_wait_policy_t policy) const
void interpret(model_context &context, const abs_address_t &pos)
void check_circular(const model_context &cxt, const abs_address_t &pos)

Determine if this cell contains circular reference by walking through all its reference tokens.

void reset()

Reset cell’s internal state.

std::vector<const formula_token*> get_ref_tokens(const model_context &cxt, const abs_address_t &pos) const

Get a series of all reference tokens included in the formula expression stored in this cell.

Parameters:
  • cxt – model context instance.

  • pos – position of the cell.

Returns:

an array of reference formula tokens. Each element is a pointer to the actual token instance stored in the cell object. Be aware that the pointer is valid only as long as the actual token instance is alive.

const formula_result &get_raw_result_cache(formula_result_wait_policy_t policy) const

Get the cached result without post-processing in case of a grouped formula cell.

Parameters:

policy – action to take in case the result is not yet available.

Returns:

formula result.

formula_result get_result_cache(formula_result_wait_policy_t policy) const

Get the cached result as a single cell. For a non-grouped formula cell, it should be identical to the value from the get_raw_result_cache() call. For a grouped formula cell, you’ll get a single value assigned to the position of the cell in case the original result is a matrix value.

Parameters:

policy – action to take in case the result is not yet available.

Returns:

formula result.

void set_result_cache(formula_result result)

Set a cached result to this formula cell instance.

Parameters:

result – cached result.

formula_group_t get_group_properties() const
abs_address_t get_parent_position(const abs_address_t &pos) const

Get the absolute parent position of a grouped formula cell. If the cell is not grouped, it simply returns the original position passed to this method.

Parameters:

pos – original position from which to calculate the parent position.

Returns:

parent position of the grouped formula cell.

formula_error

class formula_error : public std::exception

Public Functions

explicit formula_error(formula_error_t fe)
explicit formula_error(formula_error_t fe, std::string msg)
formula_error(const formula_error &other)
formula_error(formula_error &&other)
virtual ~formula_error()
virtual const char *what() const noexcept override
formula_error_t get_error() const

formula_name_resolver

class formula_name_resolver

Formula name resolvers resolves a name in a formula expression to a more concrete name type.

Public Functions

formula_name_resolver()
virtual ~formula_name_resolver() = 0
virtual formula_name_t resolve(std::string_view s, const abs_address_t &pos) const = 0

Parse and resolve a reference string.

Parameters:
  • s – reference string to be parsed.

  • pos – base cell position, which influences the resolved reference position(s) containing relative address(es). When the reference string does not contain an explicit sheet name, the sheet address of the base cell position is used.

Returns:

result of the resovled reference.

virtual std::string get_name(const address_t &addr, const abs_address_t &pos, bool sheet_name) const = 0
virtual std::string get_name(const range_t &range, const abs_address_t &pos, bool sheet_name) const = 0
virtual std::string get_name(const table_t &table) const = 0
virtual std::string get_column_name(col_t col) const = 0

Given a numerical representation of column position, return its textural representation.

Parameters:

col – numerical column position.

Returns:

textural representation of column position.

Public Static Functions

static std::unique_ptr<formula_name_resolver> get(formula_name_resolver_t type, const model_context *cxt)

Create a formula name resolver instance according to the requested type.

Parameters:
  • type – type formula name resolver being requested.

  • cxt – document model context for resolving sheet names, or nullptr in case names being resolved don’t contain sheet names.

Returns:

formula name resolver instance created on the heap. The caller is responsible for managing its life cycle.

formula_registration_error

class formula_registration_error : public ixion::general_error

Public Functions

explicit formula_registration_error(const std::string &msg)
virtual ~formula_registration_error() override

formula_result

class formula_result

Store formula result which may be either numeric, textural, or error. In case the result is textural, it owns the instance of the string.

Public Types

enum class result_type

Values:

enumerator boolean
enumerator value
enumerator string
enumerator error
enumerator matrix

Public Functions

formula_result()
formula_result(const formula_result &r)
formula_result(formula_result &&r)
formula_result(bool b)
formula_result(double v)
formula_result(std::string str)
formula_result(formula_error_t e)
formula_result(matrix mtx)
~formula_result()
void reset()
void set_boolean(bool b)
void set_value(double v)
void set_string_value(std::string str)
void set_error(formula_error_t e)
void set_matrix(matrix mtx)
bool get_boolean() const

Get a boolean result value. The caller must make sure the result is of boolean type, else the behavior is undefined.

Returns:

boolean result value.

double get_value() const

Get a numeric result value. The caller must make sure the result is of numeric type, else the behavior is undefined.

Returns:

numeric result value.

const std::string &get_string() const

Get a string value for textural result. The caller must make sure the result is of textural type, else the behavior is undefined.

Returns:

string value.

formula_error_t get_error() const

Get an error value of the result. The caller must make sure that the result is of error type, else the behavior is undefined.

See also

ixion::get_formula_error_name

Returns:

enum value representing the error.

const matrix &get_matrix() const

Get a matrix value of the result. The caller must make sure that the result is of matrix type, else the behavior is undefined.

Returns:

matrix result value.

matrix &get_matrix()

Get a matrix value of the result. The caller must make sure that the result is of matrix type, else the behavior is undefined.

Returns:

matrix result value.

result_type get_type() const

Get the type of result.

Returns:

enum value representing the result type.

std::string str(const model_context &cxt) const

Get a string representation of the result value no matter what the result type is.

Parameters:

cxt – model context object.

Returns:

string representation of the result value.

void parse(std::string_view s)

Parse a textural representation of a formula result, and set result value of appropriate type.

Parameters:

s – formula result as a string.

formula_result &operator=(formula_result r)
bool operator==(const formula_result &r) const
bool operator!=(const formula_result &r) const

formula_tokens_store

class formula_tokens_store

Storage for a series of formula tokens.

Public Functions

~formula_tokens_store()
formula_tokens_store(const formula_tokens_store&) = delete
formula_tokens_store &operator=(const formula_tokens_store&) = delete
size_t get_reference_count() const
formula_tokens_t &get()
const formula_tokens_t &get() const

Public Static Functions

static formula_tokens_store_ptr_t create()

general_error

class general_error : public std::exception

Subclassed by ixion::file_not_found, ixion::formula_registration_error, ixion::model_context_error, ixion::not_implemented_error

Public Functions

general_error()
explicit general_error(const std::string &msg)
virtual ~general_error()
virtual const char *what() const noexcept override

matrix

class matrix

2-dimensional matrix consisting of elements of variable types. Each element can be numeric, string, or empty. This class is used to represent range values or in-line matrices.

Public Types

enum class element_type

Values:

enumerator numeric
enumerator string
enumerator boolean
enumerator error
enumerator empty

Public Functions

matrix()
matrix(size_t rows, size_t cols)
matrix(size_t rows, size_t cols, double numeric)
matrix(size_t rows, size_t cols, bool boolean)
matrix(size_t rows, size_t cols, const std::string &str)
matrix(size_t rows, size_t cols, formula_error_t error)
matrix(const matrix &other)
matrix(matrix &&other)
matrix(const numeric_matrix &other)
~matrix()
matrix &operator=(matrix other)
bool is_numeric() const

Determine if the entire matrix consists only of numeric value elements.

Returns:

true if the entire matrix consits only of numeric value elements, false otherwise.

bool get_boolean(size_t row, size_t col) const
bool is_numeric(size_t row, size_t col) const
double get_numeric(size_t row, size_t col) const
void set(size_t row, size_t col, double val)
void set(size_t row, size_t col, bool val)
void set(size_t row, size_t col, const std::string &str)
void set(size_t row, size_t col, formula_error_t val)
element get(size_t row, size_t col) const
size_t row_size() const
size_t col_size() const
void swap(matrix &r)
numeric_matrix as_numeric() const
bool operator==(const matrix &r) const
bool operator!=(const matrix &r) const
struct element

Public Types

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

Public Members

element_type type
value_type value

model_context

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()

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 add_string(std::string_view s)

Try to add a new string to the string pool. If the same string already exists in the pool, the new string won’t be added to the pool.

Parameters:

s – string to try to add to the pool.

Returns:

string_id_t integer value 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.

string_id_t append_string(std::string_view s)
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.

Parameters:

s – string value.

Returns:

string_id_t integer string ID associated with the string value given.

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.

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

Public Functions

virtual std::unique_ptr<iface::session_handler> create()
virtual ~session_handler_factory()

model_context_error

class model_context_error : public ixion::general_error

This exception is thrown typically from the ixion::model_context class.

Public Types

enum error_type

Values:

enumerator circular_dependency
enumerator invalid_named_expression
enumerator sheet_name_conflict
enumerator sheet_size_locked
enumerator not_implemented

Public Functions

explicit model_context_error(const std::string &msg, error_type type)
virtual ~model_context_error() override
error_type get_error_type() const

model_iterator

class 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()
const cell &get() const

Friends

friend class detail::model_context_impl
struct cell

Public Types

using value_type = std::variant<bool, double, string_id_t, const formula_cell*>

Public Functions

cell()
cell(row_t _row, col_t _col)
cell(row_t _row, col_t _col, bool _b)
cell(row_t _row, col_t _col, string_id_t _s)
cell(row_t _row, col_t _col, double _v)
cell(row_t _row, col_t _col, const formula_cell *_f)
bool operator==(const cell &other) const
bool operator!=(const cell &other) const

Public Members

row_t row
col_t col
cell_t type
value_type value

named_expressions_iterator

class named_expressions_iterator

Public Functions

named_expressions_iterator()
named_expressions_iterator(const named_expressions_iterator &other)
named_expressions_iterator(named_expressions_iterator &&other)
~named_expressions_iterator()
size_t size() const
bool has() const
void next()
named_expression get() const
named_expressions_iterator &operator=(const named_expressions_iterator &other)
struct named_expression

Public Members

const std::string *name
const named_expression_t *expression

not_implemented_error

class not_implemented_error : public ixion::general_error

Public Functions

explicit not_implemented_error(const std::string &msg)
virtual ~not_implemented_error() override

numeric_matrix

class numeric_matrix

Public Functions

numeric_matrix()
numeric_matrix(size_t rows, size_t cols)
numeric_matrix(std::vector<double> array, size_t rows, size_t cols)

Constructor with initial values.

Parameters:
  • array – Array of initial values stored in column-major order.

  • rows – Number of rows.

  • cols – Number of columns.

numeric_matrix(numeric_matrix &&r)
~numeric_matrix()
numeric_matrix &operator=(numeric_matrix other)
double &operator()(size_t row, size_t col)
const double &operator()(size_t row, size_t col) const
void swap(numeric_matrix &r)
size_t row_size() const
size_t col_size() const

values_t

class values_t

type that stores a mixture of value_t values.

Public Functions

inline values_t(int val)
inline bool is_numeric() const
inline bool is_boolean() const
inline bool is_string() const
inline bool is_empty() const

Child namespaces