This class encapsulates the concept of an excel file. It is different from the XLWorkbook, in that an XLDocument holds an XLWorkbook together with its metadata, as well as methods for opening, closing and saving the document.
The XLDocument is the entrypoint for clients using the RapidXLSX library. More...

#include <XLDocument.hpp>

Data Structures
struct	SharedFormula

Public Member Functions
XLXmlData *	getXmlData (XLInternalAccess, std::string_view path, bool doNotThrow=false)

const XLXmlData *	getXmlData (XLInternalAccess, std::string_view path, bool doNotThrow=false) const

XLXmlData *	addXmlData (XLInternalAccess, const std::string &path, const std::string &id, XLContentType type)

std::map< void *, std::unordered_map< uint32_t, SharedFormula > > &	sharedFormulas (XLInternalAccess) const

	XLDocument (const IZipArchive &zipArchive=XLZipArchive())
	Default constructor. Initializes an empty document package with a default ZIP archive.

	XLDocument (std::string_view docPath, const IZipArchive &zipArchive=XLZipArchive())
	Path-based constructor. Loads an existing document or sets the target path for a new one.

	XLDocument (const std::string &docPath, const IZipArchive &zipArchive=XLZipArchive())
	Legacy string constructor. Maintained to resolve ambiguity with IZipArchive's template constructor when passing string literals or std::string.

	XLDocument (const XLDocument &other)=delete

	XLDocument (XLDocument &&other) noexcept=default

	~XLDocument ()

XLDocument &	operator= (const XLDocument &other)=delete

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

void	showWarnings ()

void	suppressWarnings ()

void	open (std::string_view fileName)
	Open an existing .xlsx package. Uses std::string_view for zero-copy path processing.

void	open (std::string_view fileName, const std::string &password)
	Open an existing encrypted .xlsx package.

void	create (std::string_view fileName, bool forceOverwrite=XLForceOverwrite)
	Initialize a new .xlsx package from a built-in template.

void	create (const std::string &fileName)
	Create a new .xlsx file with the given name. Legacy interface.

void	close ()
	Close the document and release underlying ZIP resources, ensuring file handles are closed properly.

void	save ()
	Save changes to the original file path.

void	addStreamedFile (std::string_view pathInZip, std::string_view tempFilePath)

void	saveAs (std::string_view fileName, bool forceOverwrite=XLForceOverwrite)
	Persistence to a new location.

void	saveAs (std::string_view fileName, const std::string &password, bool forceOverwrite=XLForceOverwrite)
	Persistence to a new location with encryption.

void	saveAs (const std::string &fileName)
	Save the document with a new name. Legacy interface.

std::string	name () const
	Access filename to uniquely identify the document in the package.

const std::string &	path () const
	Access the full filesystem path of the current document. [[nodiscard]] prevents ignoring the current path reference.

XLContentTypes &	contentTypes ()
	Provides access to the [Content_Types].xml file, which defines the package structure and internal part mapping.

bool	hasMacro () const
	Provides access to custom properties (metadata) that can be set for the document.

void	deleteMacro ()
	Deletes the VBA macro project and all macro-related signatures/relationships from the document. This is typically used to sanitize a file before saving it as a standard .xlsx.

XLCustomProperties &	customProperties ()

uint32_t	nextTableId () const
	Atomic table ID generator to ensure workbook-wide uniqueness for Excel table structures. [[nodiscard]] is used to enforce correct result consumption.

XLWorkbook	workbook () const
	Get the underlying workbook object, containing worksheets and global data state. [[nodiscard]] prevents side-effect-free querying errors.

std::string	property (XLProperty prop) const
	Fetch metadata property by type (e.g., Title, Creator).

void	setProperty (XLProperty prop, std::string_view value)
	Update metadata property. Uses string_view to allow updating from literals without temporary allocations.

void	deleteProperty (XLProperty theProperty)
	Remove specific metadata property.

	operator bool () const

bool	isOpen () const

void	setCompressionLevel (int level)
	Set the compression level for packing the document.

int	compressionLevel () const
	Get the current compression level.

void	setDefaultAuthor (const std::string &author)
	Set the default author for comments and notes.

std::string	defaultAuthor () const
	Get the default author for comments and notes.

XLStyles &	styles ()
	Provides access to shared document styles (fonts, fills, borders, cell formats).

bool	hasSheetRelationships (uint16_t sheetXmlNo, bool isChartsheet=false) const
	Component presence checks, used to avoid unnecessary parsing of absent components in the package.

bool	hasSheetVmlDrawing (uint16_t sheetXmlNo) const

bool	hasSheetComments (uint16_t sheetXmlNo) const

bool	hasSheetThreadedComments (uint16_t sheetXmlNo) const

bool	hasSheetDrawing (uint16_t sheetXmlNo) const

bool	hasSheetTables (uint16_t sheetXmlNo) const

XLRelationships	sheetRelationships (uint16_t sheetXmlNo, bool isChartsheet=false)

XLDrawing	sheetDrawing (uint16_t sheetXmlNo)

XLDrawing	createDrawing ()

XLDrawing	drawing (std::string_view path)

XLVmlDrawing	sheetVmlDrawing (uint16_t sheetXmlNo)

XLComments	sheetComments (uint16_t sheetXmlNo)

XLThreadedComments	sheetThreadedComments (uint16_t sheetXmlNo)

XLTables	sheetTables (uint16_t sheetXmlNo)

class XLChart	createChart (XLChartType type=XLChartType::Bar)

class XLPivotTable	createPivotTable ()

class XLPivotCacheDefinition	createPivotCacheDefinition ()

class XLPivotCacheRecords	createPivotCacheRecords (std::string_view cacheDefPath)

std::string	createTableSlicerCache (uint32_t tableId, uint32_t tableColumnId, std::string_view name, std::string_view sourceName)

std::string	createPivotSlicerCache (uint32_t pivotCacheId, uint32_t sheetId, std::string_view pivotTableName, std::string_view name, std::string_view sourceName)

std::string	createSlicer (std::string_view name, std::string_view cacheName, std::string_view caption)

std::string	addImage (std::string_view name, std::string_view data)
	Insert image into the archive's media folder. Uses string_view for zero-copy data transfer.

std::string	getImage (std::string_view path) const
	Fetch raw image data from the document archive (xl/media/).

XLRelationships	drawingRelationships (std::string_view drawingPath)

XLRelationships	xmlRelationships (std::string_view xmlPath)
	Get relationships for an arbitrary XML file (e.g. pivot tables)

XLRelationships &	workbookRelationships ()
	Get workbook relationships.

IZipArchive &	archive ()
	Access the low-level ZIP archive for advanced package manipulation. [[nodiscard]] is used to prevent state-querying errors.

const IZipArchive &	archive () const

XLAppProperties &	appProperties ()
	Access application-specific properties (metadata). [[nodiscard]] is used to prevent state-querying errors.

const XLAppProperties &	appProperties () const

XLProperties &	coreProperties ()
	Access core document metadata properties. [[nodiscard]] is used to prevent state-querying errors.

const XLProperties &	coreProperties () const

bool	validateSheetName (std::string_view sheetName, bool throwOnInvalid=false)
	Ensure worksheet names adhere to Excel's naming rules.

bool	execCommand (const XLCommand &command)

XLQuery	execQuery (const XLQuery &query) const
	Execute a state-querying operation without modifying the document. [[nodiscard]] is used to prevent state-querying errors.

XLQuery	execQuery (const XLQuery &query)

void	setSavingDeclaration (XLXmlSavingDeclaration const &savingDeclaration)

const XLSharedStrings &	sharedStrings () const
	Access the workbook's central Shared String Table (SST). The SST reduces file size by deduplicating text across the entire package.

bool	hasPersons () const
	Check if the document has a persons metadata file.

XLPersons &	persons ()
	Access the persons metadata for threaded comments.

void	cleanupSharedStrings ()
	Prune unused strings from the SST and reindex referencing cells. Essential for minimizing file size and memory footprint in long-lived or large documents.

void	setFormulaNeedsRecalculation (bool status=true)
	Marks the document to require formula recalculation on load.

std::string	extractXmlFromArchive (std::string_view path)
	Fetch raw XML content for a specific package path. Used internally for lazily loading components on demand, or for advanced testing/inspection.

std::shared_mutex &	mutex () const
	Get the document-level mutex for thread-safe operations.

Protected Member Functions
XLXmlData *	getXmlData (std::string_view path, bool doNotThrow=false)
	Provide access to managed XML data nodes, enabling centralized XML state management. doNotThrow allows safe querying when a component's presence is uncertain.

const XLXmlData *	getXmlData (std::string_view path, bool doNotThrow=false) const

bool	hasXmlData (std::string_view path) const

Detailed Description

This class encapsulates the concept of an excel file. It is different from the XLWorkbook, in that an XLDocument holds an XLWorkbook together with its metadata, as well as methods for opening, closing and saving the document.
The XLDocument is the entrypoint for clients using the RapidXLSX library.

Constructor & Destructor Documentation

◆ XLDocument() [1/5]

XLDocument::XLDocument ( const IZipArchive & zipArchive = XLZipArchive() )

explicit

Default constructor. Initializes an empty document package with a default ZIP archive.

Allows creating or manipulating an in-memory or custom-provided ZIP archive, decoupling the document from direct disk I/O.

◆ XLDocument() [2/5]

XLDocument::XLDocument	(	std::string_view	docPath,
		const IZipArchive &	zipArchive = `XLZipArchive()`
	)

explicit

Path-based constructor. Loads an existing document or sets the target path for a new one.

Parameters

docPath Non-owning view to the file path to minimize memory overhead during initialization.

Provides an optimized initialization path that avoids string copies when reading an existing workbook from disk.

◆ XLDocument() [3/5]

XLDocument::XLDocument	(	const std::string &	docPath,
		const IZipArchive &	zipArchive = `XLZipArchive()`
	)

explicit

Legacy string constructor. Maintained to resolve ambiguity with IZipArchive's template constructor when passing string literals or std::string.

Maintains backward compatibility for existing codebases relying on std::string, ensuring smooth upgrades.

◆ XLDocument() [4/5]

OpenXLSX::XLDocument::XLDocument ( const XLDocument & other )

delete

◆ XLDocument() [5/5]

OpenXLSX::XLDocument::XLDocument ( XLDocument && other )

defaultnoexcept

◆ ~XLDocument()

XLDocument::~XLDocument ( )

Prevents resource leaks and ensures any pending archive handles or DOM structures are properly disposed of when the object goes out of scope.

Member Function Documentation

◆ addImage()

std::string XLDocument::addImage	(	std::string_view	name,
		std::string_view	data
	)

Insert image into the archive's media folder. Uses string_view for zero-copy data transfer.

Parameters

name	Filename in the archive.
data	Raw image data as a non-owning view.

Returns: The internal package path to the image.

Injects binary image payloads into the internal media folder and registers their MIME type, laying the groundwork for visual sheet annotations.

◆ addStreamedFile()

void XLDocument::addStreamedFile	(	std::string_view	pathInZip,
		std::string_view	tempFilePath
	)

◆ addXmlData()

XLXmlData * OpenXLSX::XLDocument::addXmlData	(	XLInternalAccess	,
		const std::string &	path,
		const std::string &	id,
		XLContentType	type
	)

inline

◆ appProperties() [1/2]

XLAppProperties & OpenXLSX::XLDocument::appProperties ( )

inline

Access application-specific properties (metadata). [[nodiscard]] is used to prevent state-querying errors.

◆ appProperties() [2/2]

const XLAppProperties & OpenXLSX::XLDocument::appProperties ( ) const

inline

◆ archive() [1/2]

IZipArchive & OpenXLSX::XLDocument::archive ( )

inline

Access the low-level ZIP archive for advanced package manipulation. [[nodiscard]] is used to prevent state-querying errors.

◆ archive() [2/2]

const IZipArchive & OpenXLSX::XLDocument::archive ( ) const

inline

◆ cleanupSharedStrings()

void XLDocument::cleanupSharedStrings ( )

Prune unused strings from the SST and reindex referencing cells. Essential for minimizing file size and memory footprint in long-lived or large documents.

Shared String Table (SST) cleanup. Rationale: Over time, the SST can accumulate unused strings as cells are modified or deleted. This method performs a full workbook traversal to identify strings currently in use, remaps their indices to a new, compact table, and moves the string data to avoid copies. Index 0 is reserved for empty strings by convention.

◆ close()

void XLDocument::close ( )

Close the document and release underlying ZIP resources, ensuring file handles are closed properly.

Safely drops the internal DOM representations and archive handles, returning the XLDocument to a pristine, uninitialized state to prevent cross-contamination between files.

◆ compressionLevel()

int XLDocument::compressionLevel ( ) const

Get the current compression level.

◆ contentTypes()

XLContentTypes & XLDocument::contentTypes ( )

Provides access to the [Content_Types].xml file, which defines the package structure and internal part mapping.

Exposes the content types manager, which is required to register new XML parts (like sheets or drawings) so Excel recognizes their purpose.

◆ coreProperties() [1/2]

XLProperties & OpenXLSX::XLDocument::coreProperties ( )

inline

Access core document metadata properties. [[nodiscard]] is used to prevent state-querying errors.

◆ coreProperties() [2/2]

const XLProperties & OpenXLSX::XLDocument::coreProperties ( ) const

inline

◆ create() [1/2]

void XLDocument::create ( const std::string & fileName )

Create a new .xlsx file with the given name. Legacy interface.

Deprecated:: Use void create(std::string_view, bool) for explicit overwrite control.

Maintains backward compatibility for creating new documents using std::string, ensuring smooth upgrades.

◆ create() [2/2]

void XLDocument::create	(	std::string_view	fileName,
		bool	forceOverwrite = `XLForceOverwrite`
	)

Initialize a new .xlsx package from a built-in template.

Parameters

fileName	Target path for the new package.
forceOverwrite	Prevents accidental data loss unless explicitly requested via XLForceOverwrite.

Bootstraps a minimal, valid OOXML document structure from scratch. Uses hardcoded string templates instead of a binary payload to prevent carrying opaque blobs in the executable.

◆ createChart()

XLChart XLDocument::createChart ( XLChartType type = XLChartType::Bar )

◆ createDrawing()

XLDrawing XLDocument::createDrawing ( )

◆ createPivotCacheDefinition()

XLPivotCacheDefinition XLDocument::createPivotCacheDefinition ( )

◆ createPivotCacheRecords()

class XLPivotCacheRecords OpenXLSX::XLDocument::createPivotCacheRecords ( std::string_view cacheDefPath )

◆ createPivotSlicerCache()

std::string XLDocument::createPivotSlicerCache	(	uint32_t	pivotCacheId,
		uint32_t	sheetId,
		std::string_view	pivotTableName,
		std::string_view	name,
		std::string_view	sourceName
	)

◆ createPivotTable()

XLPivotTable XLDocument::createPivotTable ( )

◆ createSlicer()

std::string XLDocument::createSlicer	(	std::string_view	name,
		std::string_view	cacheName,
		std::string_view	caption
	)

◆ createTableSlicerCache()

std::string XLDocument::createTableSlicerCache	(	uint32_t	tableId,
		uint32_t	tableColumnId,
		std::string_view	name,
		std::string_view	sourceName
	)

◆ customProperties()

XLCustomProperties & XLDocument::customProperties ( )

◆ defaultAuthor()

std::string XLDocument::defaultAuthor ( ) const

Get the default author for comments and notes.

◆ deleteMacro()

void XLDocument::deleteMacro ( )

Deletes the VBA macro project and all macro-related signatures/relationships from the document. This is typically used to sanitize a file before saving it as a standard .xlsx.

◆ deleteProperty()

void XLDocument::deleteProperty ( XLProperty theProperty )

Remove specific metadata property.

Clears a specific metadata property to clean up unneeded, obsolete, or sensitive document traces.

◆ drawing()

XLDrawing XLDocument::drawing ( std::string_view path )

◆ drawingRelationships()

XLRelationships XLDocument::drawingRelationships ( std::string_view drawingPath )

Lazily resolves or bootstraps drawing-level relationships, which are required when linking images or charts within a drawing surface.

◆ execCommand()

bool XLDocument::execCommand ( const XLCommand & command )

Provides a centralized mutation interface for document-level changes. Abstracted as commands to decouple the UI/API layers from the internal DOM routing and dependency management logic.

◆ execQuery() [1/2]

XLQuery XLDocument::execQuery ( const XLQuery & query )

Non-const overload for querying document state.

◆ execQuery() [2/2]

XLQuery XLDocument::execQuery ( const XLQuery & query ) const

Execute a state-querying operation without modifying the document. [[nodiscard]] is used to prevent state-querying errors.

Provides a centralized read interface for querying document state. Decouples consumers from traversing the relationship graphs directly.

◆ extractXmlFromArchive()

std::string XLDocument::extractXmlFromArchive ( std::string_view path )

Fetch raw XML content for a specific package path. Used internally for lazily loading components on demand, or for advanced testing/inspection.

Serves as the foundational bridge between the raw ZIP layer and the parsed DOM layer, safely extracting content only when explicitly requested.

◆ getImage()

std::string XLDocument::getImage ( std::string_view path ) const

Fetch raw image data from the document archive (xl/media/).

Retrieves the raw binary payload of an embedded image, enabling external rendering or extraction of worksheet media.

◆ getXmlData() [1/4]

XLXmlData * XLDocument::getXmlData	(	std::string_view	path,
		bool	doNotThrow = `false`
	)

protected

Provide access to managed XML data nodes, enabling centralized XML state management. doNotThrow allows safe querying when a component's presence is uncertain.

Returns a mutable pointer to the requested XML part, acting as the document's central DOM registry cache.

◆ getXmlData() [2/4]

const XLXmlData * XLDocument::getXmlData	(	std::string_view	path,
		bool	doNotThrow = `false`
	)		const

protected

Returns a read-only pointer to the requested XML part from the DOM cache.

◆ getXmlData() [3/4]

XLXmlData * OpenXLSX::XLDocument::getXmlData	(	XLInternalAccess	,
		std::string_view	path,
		bool	doNotThrow = `false`
	)

inline

◆ getXmlData() [4/4]

const XLXmlData * OpenXLSX::XLDocument::getXmlData	(	XLInternalAccess	,
		std::string_view	path,
		bool	doNotThrow = `false`
	)		const

inline

◆ hasMacro()

bool XLDocument::hasMacro ( ) const

Provides access to custom properties (metadata) that can be set for the document.

Check if the loaded document contains a VBA macro project (e.g. xl/vbaProject.bin)

Returns: true if macro project exists

Provides access to custom properties, enabling the storage of application-specific metadata within the OOXML container.

◆ hasPersons()

bool XLDocument::hasPersons ( ) const

Check if the document has a persons metadata file.

Overrides the default XML header attributes, allowing consumers to dictate XML standalone status or encoding during serialization.

◆ hasSheetComments()

bool XLDocument::hasSheetComments ( uint16_t sheetXmlNo ) const

Probes the archive index for comments to conditionally parse them, optimizing load times for sheets without annotations.

◆ hasSheetDrawing()

bool XLDocument::hasSheetDrawing ( uint16_t sheetXmlNo ) const

Probes the archive index for drawings to verify the presence of visual elements before attempting to parse them.

◆ hasSheetRelationships()

bool XLDocument::hasSheetRelationships	(	uint16_t	sheetXmlNo,
		bool	isChartsheet = `false`
	)		const

Component presence checks, used to avoid unnecessary parsing of absent components in the package.

Probes the archive index for sheet relationships to conditionally access dependencies, avoiding eager and expensive XML allocations for untouched components.

◆ hasSheetTables()

bool XLDocument::hasSheetTables ( uint16_t sheetXmlNo ) const

Probes the archive index for table definitions, delaying XML parsing until table data is explicitly requested.

◆ hasSheetThreadedComments()

bool XLDocument::hasSheetThreadedComments ( uint16_t sheetXmlNo ) const

◆ hasSheetVmlDrawing()

bool XLDocument::hasSheetVmlDrawing ( uint16_t sheetXmlNo ) const

Probes the archive index for legacy VML drawings (often used for comments or form controls) to avoid redundant DOM creation.

◆ hasXmlData()

bool XLDocument::hasXmlData ( std::string_view path ) const

protected

Provides a safe lookup into the DOM cache to verify the existence of optional parts without triggering exceptions.

◆ isOpen()

bool XLDocument::isOpen ( ) const

Returns: True if the document is active and editable.

Provides an explicit boolean check for the document's readiness state, preventing operations on uninitialized archives.

◆ mutex()

std::shared_mutex & OpenXLSX::XLDocument::mutex ( ) const

inline

Get the document-level mutex for thread-safe operations.

◆ name()

std::string XLDocument::name ( ) const

Access filename to uniquely identify the document in the package.

Returns: The current document's filename. [[nodiscard]] is used to prevent state-querying errors.

Provides the base filename to facilitate identification in UI, logging, or reporting contexts.

◆ nextTableId()

uint32_t XLDocument::nextTableId ( ) const

Atomic table ID generator to ensure workbook-wide uniqueness for Excel table structures. [[nodiscard]] is used to enforce correct result consumption.

Calculates the next available auto-incrementing ID across all tables to ensure unique table references within the document, a strict OOXML requirement.

◆ open() [1/2]

void XLDocument::open ( std::string_view fileName )

Open an existing .xlsx package. Uses std::string_view for zero-copy path processing.

Parameters

fileName Path to the file to open.

◆ open() [2/2]

void XLDocument::open	(	std::string_view	fileName,
		const std::string &	password
	)

Open an existing encrypted .xlsx package.

Parameters

fileName	Path to the file to open.
password	The user password for decryption.

Establishes the document's internal structure by parsing its root relationships and mandatory XML parts. This serves as the primary entry point for accessing and mutating any existing workbook.

◆ operator bool()

XLDocument::operator bool ( ) const

explicit

Returns: True if the document archive is valid and properly loaded.

Allows fast truthy checks to verify if the underlying zip archive is successfully bound and accessible.

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

defaultnoexcept

◆ path()

const std::string & XLDocument::path ( ) const

Access the full filesystem path of the current document. [[nodiscard]] prevents ignoring the current path reference.

Returns the active file path to allow consumers to verify or display the target destination.

◆ persons()

XLPersons & XLDocument::persons ( )

Access the persons metadata for threaded comments.

◆ property()

std::string XLDocument::property ( XLProperty prop ) const

Fetch metadata property by type (e.g., Title, Creator).

Provides read access to standard OOXML document metadata (core and extended properties) such as creator, application version, or creation date.

◆ save()

void XLDocument::save ( )

Save changes to the original file path.

Commits the current DOM state to the archive, updating dimensions and calculation chains before disk flush to ensure Excel interprets the modified file as valid.

◆ saveAs() [1/3]

void XLDocument::saveAs ( const std::string & fileName )

Save the document with a new name. Legacy interface.

Deprecated:: Use void saveAs(std::string_view, bool) for explicit overwrite control.

Maintains backward compatibility for saving documents using std::string, ensuring smooth upgrades.

◆ saveAs() [2/3]

void XLDocument::saveAs	(	std::string_view	fileName,
		bool	forceOverwrite = `XLForceOverwrite`
	)

Persistence to a new location.

Parameters

fileName	Target path.
forceOverwrite	Protects existing files from being overwritten without explicit intent.

◆ saveAs() [3/3]

void XLDocument::saveAs	(	std::string_view	fileName,
		const std::string &	password,
		bool	forceOverwrite = `XLForceOverwrite`
	)

Persistence to a new location with encryption.

Parameters

fileName	Target path.
password	Password for encryption.
forceOverwrite	Protects existing files from being overwritten.

Serializes the modified DOM objects into their respective XML strings and constructs a new ZIP archive. Caches and restores unhandled media/VBA entries to prevent data loss in macro-enabled files.

◆ setCompressionLevel()

void XLDocument::setCompressionLevel ( int level )

Set the compression level for packing the document.

Parameters

level Compression level (1-9). Default is 1.

◆ setDefaultAuthor()

void XLDocument::setDefaultAuthor ( const std::string & author )

Set the default author for comments and notes.

◆ setFormulaNeedsRecalculation()

void OpenXLSX::XLDocument::setFormulaNeedsRecalculation ( bool status = true )

inline

Marks the document to require formula recalculation on load.

◆ setProperty()

void XLDocument::setProperty	(	XLProperty	prop,
		std::string_view	value
	)

Update metadata property. Uses string_view to allow updating from literals without temporary allocations.

Parameters

prop	The property to set.
value	A non-owning view to the value string.

Mutates document metadata, explicitly validating format-specific constraints (e.g., boolean strings or version formatting 'XX.XXXX') to prevent schema validation failures in Excel.

◆ setSavingDeclaration()

void XLDocument::setSavingDeclaration ( XLXmlSavingDeclaration const & savingDeclaration )

◆ sharedFormulas()

std::map< void *, std::unordered_map< uint32_t, SharedFormula > > & OpenXLSX::XLDocument::sharedFormulas ( XLInternalAccess ) const

inline

◆ sharedStrings()

const XLSharedStrings & OpenXLSX::XLDocument::sharedStrings ( ) const

inline

Access the workbook's central Shared String Table (SST). The SST reduces file size by deduplicating text across the entire package.

◆ sheetComments()

XLComments XLDocument::sheetComments ( uint16_t sheetXmlNo )

Bootstraps or retrieves the comment thread storage for a sheet, required to read or write cell-anchored notes.

◆ sheetDrawing()

XLDrawing XLDocument::sheetDrawing ( uint16_t sheetXmlNo )

Initializes or retrieves the drawing canvas for a sheet, serving as the root container for images, charts, and shapes.

◆ sheetRelationships()

XLRelationships XLDocument::sheetRelationships	(	uint16_t	sheetXmlNo,
		bool	isChartsheet = `false`
	)

Lazily resolves or bootstraps sheet-level relationships. This is necessary to construct valid linkages before adding interactive or visual elements to a sheet.

◆ sheetTables()

XLTableCollection XLDocument::sheetTables ( uint16_t sheetXmlNo )

◆ sheetThreadedComments()

XLThreadedComments XLDocument::sheetThreadedComments ( uint16_t sheetXmlNo )

Bootstraps or retrieves the table registry for a sheet, facilitating structured data manipulation and formatting.

◆ sheetVmlDrawing()

XLVmlDrawing XLDocument::sheetVmlDrawing ( uint16_t sheetXmlNo )

Initializes or retrieves the legacy VML drawing canvas, primarily required for anchoring cell comments to the UI.

◆ showWarnings()

void XLDocument::showWarnings ( )

Enables stdout logging for non-critical schema deviations (e.g., unknown xml relationships), which is vital for debugging compatibility issues.

◆ styles()

XLStyles & XLDocument::styles ( )

Provides access to shared document styles (fonts, fills, borders, cell formats).

Provides access to the global stylesheet manager to retrieve or define fonts, fills, borders, and number formats used across the workbook.

◆ suppressWarnings()

void XLDocument::suppressWarnings ( )

Silences non-critical schema deviation warnings to keep the console output clean during production use.

◆ validateSheetName()

bool XLDocument::validateSheetName	(	std::string_view	sheetName,
		bool	throwOnInvalid = `false`
	)

Ensure worksheet names adhere to Excel's naming rules.

Worksheet names cannot: Be blank. Contain more than 31 characters. Contain any of the following characters: / \ ? * : [ ] For example, 02/17/2016 would not be a valid worksheet name, but 02-17-2016 would work fine. Begin or end with an apostrophe ('), but they can be used in between text or numbers in a name. Be named "History". This is a reserved word Excel uses internally.

Worksheet names must adhere to strict Excel naming rules to ensure compatibility across different spreadsheet applications and prevent OOXML schema violations. Key restrictions include length (31 chars), forbidden characters (/ \ ? * : [ ]), and the reserved name "History".

◆ workbook()

XLWorkbook XLDocument::workbook ( ) const

Get the underlying workbook object, containing worksheets and global data state. [[nodiscard]] prevents side-effect-free querying errors.

Provides access to the core workbook component, serving as the gateway to manage worksheets, chartsheets, and global definitions.

◆ workbookRelationships()

XLRelationships & OpenXLSX::XLDocument::workbookRelationships ( )

inline

Get workbook relationships.

◆ xmlRelationships()

XLRelationships OpenXLSX::XLDocument::xmlRelationships ( std::string_view xmlPath )

Get relationships for an arbitrary XML file (e.g. pivot tables)

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

/home/runner/work/OpenXLSX-NX/OpenXLSX-NX/OpenXLSX/headers/XLDocument.hpp
/home/runner/work/OpenXLSX-NX/OpenXLSX-NX/OpenXLSX/sources/XLDocument.cpp
/home/runner/work/OpenXLSX-NX/OpenXLSX-NX/OpenXLSX/sources/XLDocument_Commands.cpp
/home/runner/work/OpenXLSX-NX/OpenXLSX-NX/OpenXLSX/sources/XLDocument_Properties.cpp

Data Structures

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ XLDocument() [1/5]

◆ XLDocument() [2/5]

◆ XLDocument() [3/5]

◆ XLDocument() [4/5]

◆ XLDocument() [5/5]

◆ ~XLDocument()

Member Function Documentation

◆ addImage()

◆ addStreamedFile()

◆ addXmlData()

◆ appProperties() [1/2]

◆ appProperties() [2/2]

◆ archive() [1/2]

◆ archive() [2/2]

◆ cleanupSharedStrings()

◆ close()

◆ compressionLevel()

◆ contentTypes()

◆ coreProperties() [1/2]

◆ coreProperties() [2/2]

◆ create() [1/2]

◆ create() [2/2]

◆ createChart()

◆ createDrawing()

◆ createPivotCacheDefinition()

◆ createPivotCacheRecords()

◆ createPivotSlicerCache()

◆ createPivotTable()

◆ createSlicer()

◆ createTableSlicerCache()

◆ customProperties()

◆ defaultAuthor()

◆ deleteMacro()

◆ deleteProperty()

◆ drawing()

◆ drawingRelationships()

◆ execCommand()

◆ execQuery() [1/2]

◆ execQuery() [2/2]

◆ extractXmlFromArchive()

◆ getImage()

◆ getXmlData() [1/4]

◆ getXmlData() [2/4]

◆ getXmlData() [3/4]

◆ getXmlData() [4/4]

◆ hasMacro()

◆ hasPersons()

◆ hasSheetComments()

◆ hasSheetDrawing()

◆ hasSheetRelationships()

◆ hasSheetTables()

◆ hasSheetThreadedComments()

◆ hasSheetVmlDrawing()

◆ hasXmlData()

◆ isOpen()

◆ mutex()

◆ name()

◆ nextTableId()

◆ open() [1/2]

◆ open() [2/2]

◆ operator bool()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ path()

◆ persons()

◆ property()

◆ save()

◆ saveAs() [1/3]

◆ saveAs() [2/3]

◆ saveAs() [3/3]

◆ setCompressionLevel()

◆ setDefaultAuthor()

◆ setFormulaNeedsRecalculation()

◆ setProperty()

◆ setSavingDeclaration()