Import and export

The classes in this section can be viewed as the points of entry for initiating import or export processes.

The import_factory class wraps document as its destination storage then gets passed to an import filter class that parses the content of an input file and populates the destination document store.

The import_styles class works similarly to import_factory in that it wraps styles as its destination storage then gets passed to a styles import parser in order to get the destination store populated. Although this class is used by import_factory internally, it can also be instantiated independently to allow loading of just the styles data.

The export_factory also works in a similar fashion, however; the export functionality of the orcus library is currently very limited and should be considered experimental. It is currently only used by orcus_xml to export the content of a document which was originally imported from an XML document.

Warning

The export functionality of the orcus library is highly experimental.

Import factory

class import_factory : public orcus::spreadsheet::iface::import_factory

Wraps document and view stores. This is to be used by the import filter to populate the document and view stores.

Public Functions

import_factory(document &doc)
import_factory(document &doc, view &view_store)
virtual ~import_factory()
virtual iface::import_global_settings *get_global_settings() override

Obtain an optional interface for global settings, which the import filter uses to specify global filter settings that may affect how certain values and properties should be processed. The implementor can use this interface to decide how to process relevant values and properties.

Returns:

pointer to the global settings interface, or a nullptr if the implementor doesn’t support it.

virtual iface::import_shared_strings *get_shared_strings() override

Obtain an optional interface for importing shared strings for string cells. Implementing this interface is required in order to import string cell values.

Returns:

pointer to the shared strings interface, or a nullptr if the implementor doesn’t support it.

virtual iface::import_styles *get_styles() override

Obtain an optional interface for importing styles used to add formatting properties to cell values.

Returns:

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

virtual iface::import_named_expression *get_named_expression() override

Obtain an optional interface for importing global named expressions.

Note that import_sheet also provides the same interface, but its interface is for importing sheet-local named expressions.

Returns:

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

virtual iface::import_reference_resolver *get_reference_resolver(formula_ref_context_t cxt) override

Obtain an optional interface for resolving cell and cell-range references from string values.

Parameters:

cxt – context in which the formula expression containing the references to be resolved occurs.

Returns:

pointer to the reference resolve interfance, or a nullptr if the implementor doesn’t support it.

virtual iface::import_pivot_cache_definition *create_pivot_cache_definition(orcus::spreadsheet::pivot_cache_id_t cache_id) override

Obtain an optional interface for pivot cache definition import for a specified cache ID. In case a pivot cache alrady exists for the passed ID, the implementor should overwrite the existing cache with a brand-new cache instance.

Parameters:

cache_id – numeric ID associated with the pivot cache.

Returns:

pointer to the pivot cache interface, or a nullptr if the implementor doesn’t support pivot cache import.

virtual iface::import_pivot_cache_records *create_pivot_cache_records(orcus::spreadsheet::pivot_cache_id_t cache_id) override

Obtain an optional interface for pivot cache records import for a specified cache ID.

Parameters:

cache_id – numeric ID associated with the pivot cache.

Returns:

pointer to the pivot cache records interface, or a nullptr if the implementor doesn’t support pivot cache import.

virtual iface::import_sheet *append_sheet(sheet_t sheet_index, std::string_view name) override

Append a sheet with a specified sheet position index and name and return an interface for importing its content. The implementor can use a call to this method as a signal to create and append a new sheet instance to the document store.

Parameters:
  • sheet_index – position index of the sheet to be appended. It is 0-based i.e. the first sheet to be appended will have an index value of 0.

  • name – sheet name.

Returns:

pointer to the sheet instance, or a nullptr if the implementor doesn’t support it. Note, however, that if the implementor doesn’t support this interface, no cell values will get imported.

virtual iface::import_sheet *get_sheet(std::string_view name) override

Get a sheet instance by name. The import filter may use this method to get access to an existing sheet after it has been created.

Parameters:

name – sheet name.

Returns:

pointer to the sheet instance whose name matches the name passed to this method. It returns a nullptr if no sheet instance exists by the specified name.

virtual iface::import_sheet *get_sheet(sheet_t sheet_index) override

Retrieve a sheet instance by a specified numerical sheet index.

Parameters:

sheet_index – sheet index.

Returns:

pointer to the sheet instance, or a nullptr if no sheet instance exists at the specified sheet index.

virtual void finalize() override

The import filter calls this method after completing its import, to give the implementor a chance to perform post-processing.

void set_config(const import_factory_config &config)
void set_default_row_size(row_t row_size)
void set_default_column_size(col_t col_size)
void set_character_set(character_set_t charset)
character_set_t get_character_set() const
void set_recalc_formula_cells(bool b)

When setting this flag to true, those formula cells with no cached results will be re-calculated upon loading.

Parameters:

b – value of this flag.

void set_formula_error_policy(formula_error_policy_t policy)

Import styles

class import_styles : public orcus::spreadsheet::iface::import_styles

Wraps styles store. This is to be used by an import styles parser to populate the styles store.

Public Functions

import_styles(styles &styles_store, string_pool &sp)
import_styles(std::shared_ptr<import_factory_config> config, styles &styles_store, string_pool &sp)
virtual ~import_styles() override
virtual iface::import_font_style *start_font_style() override

Signal the start of the import of font style attributes, and return a pointer to the interface instance for importing the attributes.

Note

Note that the import_styles implementer must return a non-null pointer.

Returns:

pointer to the interface instance for importing font style attributes.

virtual iface::import_fill_style *start_fill_style() override

Signal the start of the import of fill style attributes, and return a pointer to the interface instance for importing the attributes.

Note

Note that the import_styles implementer must return a non-null pointer.

Returns:

pointer to the interface instance for importing fill style attributes.

virtual iface::import_border_style *start_border_style() override

Signal the start of the import of border style attributes, and return a pointer to the interface instance for importing the attributes.

Note

Note that the import_styles implementer must return a non-null pointer.

Returns:

pointer to the interface instance for importing border style attributes.

virtual iface::import_cell_protection *start_cell_protection() override

Signal the start of the import of cell protection attributes, and return a pointer to the interface instance for importing the attributes.

Note

Note that the import_styles implementer must return a non-null pointer.

Returns:

pointer to the interface instance for importing cell protection attributes.

virtual iface::import_number_format *start_number_format() override

Signal the start of the import of number format attributes and return a pointer to the interface instance for importing the attributes.

Note

Note that the import_styles implementer must return a non-null pointer.

Returns:

pointer to the interface instance for importing number format attributes.

virtual iface::import_xf *start_xf(xf_category_t cat) override

Signal the start of the import of cell format (xf) indices that each reference different format attributes in their respective pools, and return a pointer to the interface instance for importing the indices.

Note

Note that the import_styles implementer must return a non-null pointer.

Returns:

pointer to the interface instance for importing cell format (xf) indices.

virtual iface::import_cell_style *start_cell_style() override

Signal the start of the import of named cell style information, and return a pointer to the interface instance for importing the information.

Note

Note that the import_styles implementer must return a non-null pointer.

Returns:

pointer to the interface instance for importing named cell style information.

virtual void set_font_count(size_t n) override

Set the total number of font styles. This may be called before importing any of the font styles. This will give the implementer a chance to allocate storage. Note that it may not always be called.

Parameters:

n – number of font styles.

virtual void set_fill_count(size_t n) override

Set the total number of fill styles. This may be called before importing any of the fill styles. This will give the implementer a chance to allocate storage. Note that it may not always be called.

Parameters:

n – number of fill styles.

virtual void set_border_count(size_t n) override

Set the total number of border styles. This may be called before importing any of the border styles. This will give the implementer a chance to allocate storage. Note that it may not always be called.

Parameters:

n – number of border styles.

virtual void set_number_format_count(size_t n) override

Set the total number of number format styles. This may be called before importing any of the number format styles. This will give the implementer a chance to allocate storage. Note that it may not always be called.

Parameters:

n – number of number format styles.

virtual void set_xf_count(xf_category_t cat, size_t n) override

Set the total number of cell format styles for a specified cell format category. This may be called before importing any of the cell format styles for the specified category. This will give the implementer a chance to allocate storage. Note that it may not always be called.

Parameters:
  • cat – cell format category.

  • n – number of cell formats styles for the specified cell format category.

virtual void set_cell_style_count(size_t n) override

Set the total number of named cell styles. This may be called before importing any cell styles to give the implementer a chance to allocate storage. Note that it may not always be called.

Parameters:

n – number of named cell styles.

Export factory

class export_factory : public orcus::spreadsheet::iface::export_factory

Wraps document store and faciliates export of its content.

Warning

It currently provides very limited functionality especially when compared to that of the import_factory.

Public Functions

export_factory(const document &doc)
virtual ~export_factory()
virtual const iface::export_sheet *get_sheet(std::string_view sheet_name) const override

Obtain an interface for exporting sheet content.

Parameters:

sheet_name – name of the sheet to export.

Returns:

pointer to an interface for exporting sheet content.