Loaded workbook structure generation

Structural generations let a reader retain inexpensive snapshots and reject traversal after the workbook topology it depends on has changed

Generation sources

Each property is a read-only UInt64 value and the exact amount by which it changes is not contractual

Invalidating operations

Creating, removing, or clearing stored cells changes the cell-store generation when topology actually changes

Row or column insertion and deletion, coordinate movement, packed append or materialisation, and explicit cell-index rebuilds also invalidate cell-store traversal state

Adding, deleting, moving, or clearing worksheets changes the worksheet-collection generation when the collection actually changes

Non-invalidating operations

Changing the value, formula, cached value, or format of an existing cell does not change its cell-store generation

Renaming or activating a worksheet does not change the worksheet-collection generation, and no-op moves, missing deletions, or clearing an already empty collection keep the current generation

Validation

Call XlsValidateStructureGeneration before advancing or reading traversal state that was created for an earlier generation

A mismatch raises EXLSLoadedCellCursorInvalidated, allowing callers to distinguish structural invalidation from data or format errors

ExpectedGeneration := Worksheet.CellStructureGeneration;

{ Read or retain traversal state }

XlsValidateStructureGeneration(
  ExpectedGeneration,
  Worksheet.CellStructureGeneration);

Classic workbook cursor

IXLSWorkbook.CreateLoadedCellCursor captures the classic workbook aggregate generation and validates it before every MoveNext and Current call

The cursor traverses allocated sparse-storage branches directly with constant cursor state and returns owned TXLSLoadedCellSnapshot values

The Boolean overload freezes whether independently styled stored blanks are included; inherited row, column, and worksheet formats do not create blank cursor entries

XLSX workbook cursor

TXLSXWorkbook.CreateLoadedCellCursor captures a workbook lifetime lease and aggregate topology generation shared by every worksheet cell store and the worksheet collection

The materialised path reads sparse row blocks directly, while the packed path reuses the packed iterator without materialising cells or retaining internal pointers in snapshots

The Boolean overload can include style-only stored blanks in either storage representation, while unstyled Empty and Null placeholders remain excluded

Releasing the workbook invalidates its lease before worksheet storage is freed, so later cursor access raises EXLSLoadedCellCursorInvalidated

Concurrency boundary

Generation checks provide fail-fast detection only and do not make concurrent workbook mutation and traversal thread-safe

See also

• IXLSWorkbook.CreateLoadedCellCursor method
• TXLSXWorkbook.CreateLoadedCellCursor method
• TXLSXCells class
• Advanced workbook workflows