OpenXLSX::XLMergeCells Class Reference

Manages merged cell ranges in a worksheet. More...

#include <XLMergeCells.hpp>

Data Structures
struct	XLMergeEntry
struct	XLRect
	Internal numerical bounds representation for constant-time coordinate tests. More...

Public Member Functions
	XLMergeCells ()
	XLMergeCells (const XMLNode &rootNode, std::vector< std::string_view > const &nodeOrder)
	~XLMergeCells ()=default
	XLMergeCells (const XLMergeCells &other)=default
	XLMergeCells (XLMergeCells &&other) noexcept=default
XLMergeCells &	operator= (const XLMergeCells &other)=default
XLMergeCells &	operator= (XLMergeCells &&other) noexcept=default
bool	valid () const
XLMergeIndex	findMerge (std::string_view reference) const
bool	mergeExists (std::string_view reference) const
XLMergeIndex	findMergeByCell (std::string_view cellRef) const
XLMergeIndex	findMergeByCell (XLCellReference cellRef) const
size_t	count () const
const char *	merge (XLMergeIndex index) const
const char *	operator[] (XLMergeIndex index) const
XLMergeIndex	appendMerge (const std::string &reference)
void	deleteMerge (XLMergeIndex index)
void	deleteAll ()
	Removes all merged ranges and the <mergeCells> XML container.
void	shiftRows (int32_t delta, uint32_t fromRow)
	Shift all merge regions by rowDelta for rows >= fromRow.
void	shiftCols (int32_t delta, uint16_t fromCol)
	Shift all merge regions by colDelta for columns >= fromCol.
void	print (std::basic_ostream< char > &ostr) const

Detailed Description

Manages merged cell ranges in a worksheet.

This class handles the <mergeCells> element. Rationale: Excel's string-based range lookups (e.g., "A1:C3") are O(N) and expensive for frequent checks. This class maintains a numerical coordinate cache to enable O(1) cell-in-merge tests and O(M) overlap detection, significantly improving performance for spreadsheets with many merged areas.

Constructor & Destructor Documentation

XLMergeCells() [1/4]

XLMergeCells::XLMergeCells ( )

default

XLMergeCells() [2/4]

XLMergeCells::XLMergeCells ( const XMLNode &  rootNode, std::vector< std::string_view > const &  nodeOrder  )

explicit

Parameters

rootNode	The worksheet root node.
nodeOrder	Required child sequence for proper OOXML schema compliance.

~XLMergeCells()

OpenXLSX::XLMergeCells::~XLMergeCells ( )

default

XLMergeCells() [3/4]

OpenXLSX::XLMergeCells::XLMergeCells ( const XLMergeCells &  other )

default

XLMergeCells() [4/4]

OpenXLSX::XLMergeCells::XLMergeCells ( XLMergeCells &&  other )

defaultnoexcept

Member Function Documentation

appendMerge()

XLMergeIndex XLMergeCells::appendMerge

(

const std::string &

reference

)

Returns

The index of the newly appended merge.

Exceptions

XLInputError

If the range overlaps with an existing merge.

count()

size_t XLMergeCells::count

(

)

const

deleteAll()

void XLMergeCells::deleteAll

(

)

Removes all merged ranges and the <mergeCells> XML container.

deleteMerge()

void XLMergeCells::deleteMerge

(

XLMergeIndex

index

)

Invalidation: previous indices are invalidated after deletion.

findMerge()

XLMergeIndex XLMergeCells::findMerge

(

std::string_view

reference

)

const

Returns

0-based index or XLMergeNotFound.

findMergeByCell() [1/2]

XLMergeIndex XLMergeCells::findMergeByCell

(

std::string_view

cellRef

)

const

Returns

The index of the merge range containing the given cell.

findMergeByCell() [2/2]

XLMergeIndex XLMergeCells::findMergeByCell

(

XLCellReference

cellRef

)

const

merge()

const char * XLMergeCells::merge

(

XLMergeIndex

index

)

const

Returns

The range reference string (e.g., "A1:C3").

mergeExists()

bool XLMergeCells::mergeExists

(

std::string_view

reference

)

const

operator=() [1/2]

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

default

operator=() [2/2]

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

defaultnoexcept

operator[]()

const char * OpenXLSX::XLMergeCells::operator[] ( XLMergeIndex  index ) const

inline

print()

void XLMergeCells::print

(

std::basic_ostream< char > &

ostr

)

const

shiftCols()

void XLMergeCells::shiftCols	(	int32_t	delta,
		uint16_t	fromCol
	)

Shift all merge regions by colDelta for columns >= fromCol.

Parameters

delta	Positive = insert, negative = delete.
fromCol	1-based first affected column.

Mirror of shiftRows but operating on column (left/right) coordinates.

shiftRows()

void XLMergeCells::shiftRows	(	int32_t	delta,
		uint32_t	fromRow
	)

Shift all merge regions by rowDelta for rows >= fromRow.

Regions that shrink to zero height or are fully inside the deleted band are removed. Regions straddling the boundary are clipped/expanded as appropriate.

Parameters

delta	Positive = insert (push down), negative = delete (pull up).
fromRow	1-based first affected row.

Shift merge regions vertically.

• Regions entirely above fromRow → unchanged.
• Regions entirely at/below fromRow → both top and bottom slide by delta.
• Regions straddling fromRow (delta < 0 / delete): top unchanged, bottom shrinks; if this makes height < 1 → deleteMerge.
• Regions straddling fromRow (delta > 0 / insert): not possible because insert never touches an existing row – we simply push everything down.

valid()

bool XLMergeCells::valid

(

)

const

Returns

true if initialized with a valid worksheet node.

---

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

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