This class encapsulate the Excel concept of Shared Strings. In Excel, instead of havig individual strings in each cell, cells have a reference to an entry in the SharedStrings register. This results in smalle file sizes, as repeated strings are referenced easily. More...

#include <XLSharedStrings.hpp>

Inheritance diagram for OpenXLSX::XLSharedStrings:

Public Member Functions
	XLSharedStrings ()=default

	XLSharedStrings (XLXmlData xmlData, XLSharedStringsState state)

	~XLSharedStrings ()
	Destructor.

	XLSharedStrings (const XLSharedStrings &other)=default

	XLSharedStrings (XLSharedStrings &&other) noexcept=default

XLSharedStrings &	operator= (const XLSharedStrings &other)=default

XLSharedStrings &	operator= (XLSharedStrings &&other) noexcept=default

int32_t	stringCount () const
	return the amount of shared string entries currently in the cache

int32_t	getStringIndex (std::string_view str) const

bool	stringExists (std::string_view str) const

const char *	getString (int32_t index) const

std::string_view	getStringView (int32_t index) const
	Get a string view from the list of shared strings.

int32_t	appendString (std::string_view str) const
	Append a new string to the list of shared strings.

void	reserveStrings (size_t n) const
	Pre-reserve capacity in the string cache and index for n strings.

size_t	memoryUsageBytes () const noexcept
	Approximate memory used by the cache and hash index structures.

int32_t	getOrCreateStringIndex (std::string_view str) const
	Get or create a string index in O(1) time.

void	clearString (int32_t index) const
	Clear the string at the given index.

void	print (std::basic_ostream< char > &ostr) const
	print the XML contents of the shared strings document using the underlying XMLNode print function

Public Member Functions inherited from OpenXLSX::XLXmlFile
	XLXmlFile ()=default
	Default constructor.

std::string	xmlData (XLXmlSavingDeclaration savingDeclaration=XLXmlSavingDeclaration{}) const
	Method for getting the XML data represented by the object.

	XLXmlFile (XLXmlData *xmlData)
	Constructor. Creates an object based on the xmlData input.

	XLXmlFile (const XLXmlFile &other)=default
	Copy constructor. Default implementation used.

	XLXmlFile (XLXmlFile &&other) noexcept=default
	Move constructor. Default implementation used.

	~XLXmlFile ()=default
	Destructor. Default implementation used.

bool	valid () const
	check whether class is linked to a valid XML file

XLXmlFile &	operator= (const XLXmlFile &other)=default
	The copy assignment operator. The default implementation has been used.

XLXmlFile &	operator= (XLXmlFile &&other) noexcept=default
	The move assignment operator. The default implementation has been used.

XLDocument &	parentDoc ()
	This function provides access to the parent XLDocument object.

const XLDocument &	parentDoc () const
	This function provides access to the parent XLDocument object.

XMLDocument &	xmlDocument ()
	This function provides access to the underlying XMLDocument object.

const XMLDocument &	xmlDocument () const
	This function provides access to the underlying XMLDocument object.

std::string	getXmlPath () const
	Retrieve the path of the XML data in the .xlsx zip archive via m_xmlData->getXmlPath.

Protected Member Functions
int32_t	rewriteXmlFromCache ()
	clear & rewrite the full shared strings XML from the shared strings cache

void	rebuild (const std::vector< int32_t > &indexMap, int32_t newStringCount)
	Rebuilds the shared string arena and cache using the provided index mapping, keeping only the used strings, and rewrites the XML.

Protected Member Functions inherited from OpenXLSX::XLXmlFile
void	setXmlData (std::string_view xmlData)
	Provide the XML data represented by the object.

std::string	relationshipID () const
	This function returns the relationship ID (the ID used in the XLRelationships objects) for the object.

Friends
class	XLDocument

Additional Inherited Members
Protected Attributes inherited from OpenXLSX::XLXmlFile
XLXmlData *	m_xmlData {nullptr}

Detailed Description

This class encapsulate the Excel concept of Shared Strings. In Excel, instead of havig individual strings in each cell, cells have a reference to an entry in the SharedStrings register. This results in smalle file sizes, as repeated strings are referenced easily.

Constructor & Destructor Documentation

◆ XLSharedStrings() [1/4]

OpenXLSX::XLSharedStrings::XLSharedStrings ( )

default

◆ XLSharedStrings() [2/4]

XLSharedStrings::XLSharedStrings	(	XLXmlData *	xmlData,
		XLSharedStringsState *	state
	)

explicit

Parameters

xmlData
state	Pointer to the shared strings state

Constructs a new XLSharedStrings object. Only one (common) object is allowed per XLDocument instance. A filepath to the underlying XML file must be provided.

◆ ~XLSharedStrings()

XLSharedStrings::~XLSharedStrings ( )

default

Destructor.

◆ XLSharedStrings() [3/4]

OpenXLSX::XLSharedStrings::XLSharedStrings ( const XLSharedStrings & other )

default

Parameters

other

◆ XLSharedStrings() [4/4]

OpenXLSX::XLSharedStrings::XLSharedStrings ( XLSharedStrings && other )

defaultnoexcept

Parameters

other

Member Function Documentation

◆ appendString()

int32_t XLSharedStrings::appendString ( std::string_view str ) const

Append a new string to the list of shared strings.

Parameters

str	The string to append.

Returns: An int32_t with the index of the appended string

Append a string by creating a new node in the XML file and adding the string to it. The index to the shared string is returned

◆ clearString()

void XLSharedStrings::clearString ( int32_t index ) const

Clear the string at the given index.

Parameters

index The index to clear.

Note: There is no 'deleteString' member function, as deleting a shared string node will invalidate the shared string indices for the cells in the spreadsheet. Instead use this member functions, which clears the contents of the string, but keeps the XMLNode holding the string.

Clear the string at the given index. This will affect the entire spreadsheet; everywhere the shared string is used, it will be erased.

Note: : 2024-05-31 DONE: index now int32_t everywhere, 2 billion shared strings should be plenty

◆ getOrCreateStringIndex()

int32_t XLSharedStrings::getOrCreateStringIndex ( std::string_view str ) const

Get or create a string index in O(1) time.

Parameters

str	The string to look up or add.

Returns: The index of the string (existing or newly added).

Note: This is the optimized method for setting cell string values.

Get or create a string index in O(1) time. This is the optimized path for setting cell values. It avoids the separate stringExists() + getStringIndex()/appendString() pattern.

◆ getString()

const char * XLSharedStrings::getString ( int32_t index ) const

Parameters

index

Returns

◆ getStringIndex()

int32_t XLSharedStrings::getStringIndex ( std::string_view str ) const

Parameters

str

Returns

Look up a string index by the string content. If the string does not exist, the returned index is -1. Optimized to use O(1) hash lookup when available.

◆ getStringView()

std::string_view XLSharedStrings::getStringView ( int32_t index ) const

Get a string view from the list of shared strings.

Parameters

index The index of the string to get.

Returns: A std::string_view object with the string.

◆ memoryUsageBytes()

size_t XLSharedStrings::memoryUsageBytes ( ) const

noexcept

Approximate memory used by the cache and hash index structures.

Returns: Bytes consumed by m_stringCache and m_stringIndex (not the arena).

Returns the approximate heap memory used by the string cache vector and the hash index buckets. Does not include the arena itself.

◆ operator=() [1/2]

XLSharedStrings & OpenXLSX::XLSharedStrings::operator= ( const XLSharedStrings & other )

default

Parameters

other

Returns

◆ operator=() [2/2]

XLSharedStrings & OpenXLSX::XLSharedStrings::operator= ( XLSharedStrings && other )

defaultnoexcept

Parameters

other

Returns

◆ print()

void XLSharedStrings::print ( std::basic_ostream< char > & ostr ) const

print the XML contents of the shared strings document using the underlying XMLNode print function

Print the underlying XML using pugixml::xml_node::print

◆ rebuild()

void XLSharedStrings::rebuild	(	const std::vector< int32_t > &	indexMap,
		int32_t	newStringCount
	)

protected

Rebuilds the shared string arena and cache using the provided index mapping, keeping only the used strings, and rewrites the XML.

Parameters

indexMap	Mapping from old string indices to new string indices.
newStringCount	The number of used strings (including empty string at index 0).

◆ reserveStrings()

void XLSharedStrings::reserveStrings ( size_t n ) const

Pre-reserve capacity in the string cache and index for n strings.

Call before bulk-inserting many strings to avoid incremental reallocation. Does not affect the pugi XML DOM.

Parameters

n	Number of strings to reserve capacity for.

Pre-reserve capacity in the string cache vector and hash index for n strings. Avoids repeated incremental reallocations when bulk-inserting many strings.

◆ rewriteXmlFromCache()

int32_t XLSharedStrings::rewriteXmlFromCache ( )

protected

clear & rewrite the full shared strings XML from the shared strings cache

Returns: the amount of strings written to XML (should be equal to m_stringCache->size())

◆ stringCount()

int32_t OpenXLSX::XLSharedStrings::stringCount ( ) const

inline

return the amount of shared string entries currently in the cache

Returns

◆ stringExists()

bool XLSharedStrings::stringExists ( std::string_view str ) const

Parameters

str

Returns

Check if a string exists in the shared strings table. O(1) with hash index.

Friends And Related Symbol Documentation

◆ XLDocument

friend class XLDocument

friend

The documentation for this class was generated from the following files:

/home/runner/work/OpenXLSX-NX/OpenXLSX-NX/OpenXLSX/headers/XLSharedStrings.hpp
/home/runner/work/OpenXLSX-NX/OpenXLSX-NX/OpenXLSX/sources/XLSharedStrings.cpp

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ XLSharedStrings() [1/4]

◆ XLSharedStrings() [2/4]

◆ ~XLSharedStrings()

◆ XLSharedStrings() [3/4]

◆ XLSharedStrings() [4/4]

Member Function Documentation

◆ appendString()

◆ clearString()

◆ getOrCreateStringIndex()

◆ getString()

◆ getStringIndex()

◆ getStringView()

◆ memoryUsageBytes()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ print()

◆ rebuild()

◆ reserveStrings()

◆ rewriteXmlFromCache()

◆ stringCount()

◆ stringExists()

Friends And Related Symbol Documentation

◆ XLDocument