OpenXLSX

OpenXLSX is a C++ library for reading, writing, creating and modifying Microsoft Excel® files, with the .xlsx format.

NOTE: "Releases" are severely outdated - do not use them

As the heading says - the latest "Release" that is shown on https://github.com/troldal/OpenXLSX/releases is from 2021-11-06, and severely outdated - please pull / download the latest SW version directly from the repository in its current state. Link for those that do not want to use git: https://github.com/troldal/OpenXLSX/archive/refs/heads/master.zip

(aral-matrix) 14 July 2025 - minor bugfixes & a test of signed commits

• addressed issue https://github.com/troldal/OpenXLSX/issues/368
• configured commit signature for a development machine

(aral-matrix) 20 April 2025 - added validation of worksheet names when creating, renaming or cloning worksheets to address #358

• added bool XLDocument::validateSheetName(std::string sheetName, bool throwOnInvalid = false) - can be called by the user to test whether a name would throw
• if XLSheet::setName, XLWorkbook.addWorksheet or XLWorkbook.cloneSheet are invoked with a name for which validateSheetName would return false, an XLInputError is thrown with the validation rule that was violated.
• this change addresses https://github.com/troldal/OpenXLSX/issues/358

CAUTION: this change is potentially code-breaking as it can throw an exception on code that previously executed without errors - However, when it throws, previous versions would have produced a workbook that Excel refuses to read.

(aral-matrix) 12 April 2025 - added cmake option(OPENXLSX_ENABLE_LTO "Enables Link-Time Optimization (LTO)" ON)

• merged pull request https://github.com/troldal/OpenXLSX/pull/355 adding the cmake option OPENXLSX_ENABLE_LTO that permits disabling link-time optimization altogether. It remains ON by default.

(aral-matrix) 08 April 2025 - XLMergeCells: remove <mergeCells> element from worksheet XML when merge count is 0 - addresses #351

• XLMergeCells is now constructed with the worksheet root XML node (unfortunately necessary) and will use this access to create/delete the <mergeCells> node as necessary, this addresses https://github.com/troldal/OpenXLSX/issues/351
• added a function XLMergeCells::deleteAll to clear all merges in the worksheet
• added a typedef XLMergeIndex as the parameter / return type for all functions using a merge index - the underlying int32_t remains unchanged
• added a constexpr const XLMergeIndex XLMergeNotFound = -1 for code readability

(aral-matrix) 07 April 2025 - Demo10: added a disabled use of borders with merged cells

• enable Demo10 line 450 to experiment - but LibreOffice behaves weird (at least) with (diagonal) borders, so I have disabled this Demo functionality by default

(aral-matrix) 24 March 2025 - XLStyles: XLFont fix attribute values underline, scheme, vertAlign

• getters XLFont::underline, ::scheme, ::vertAlign: fix default value to set for attribute val when tag doesn't exist
• setter XLFont::setUnderline: return correct "none" value for XLUnderlineNone from XLUnderlineStyleToString (was returning empty string)

(aral-matrix) 23 March 2025 - XLStyles: get bool settings when omitted attribute shall default to true - addresses #347

• added function getBoolAttributeWhenOmittedMeansTrue to XLUtilities
• XLStyles XLFont: changed bool getter functions to return true when tag exists, but attribute val is omitted, to be in line with OOXML spec. This addresses https://github.com/troldal/OpenXLSX/issues/347. Affected getters: bold(), italic(), strikethrough(), outline(), shadow(), condense(), extend()

(aral-matrix) 16 March 2025 - XLSheet::findCell added to address #333, setting an XLFormula to an empty string now deletes the formula

• added function(s) XLSheet::findCell that allow to try and fetch a cell without creating the row/cell XML (like the non-creating XLCellIterator). This function complements XLSheet::cell (which always creates the XML cell node and returns a valid object)
• after using findCell, the returned XLCellAssignable::empty() method must be checked to ensure success before accessing any cell properties
• XLSheet::findCell provides a solution to https://github.com/troldal/OpenXLSX/issues/333, a demonstration of this solution has been added to Demo1.cpp
• setting XLFormula to an empty (zero-length) string will now delete the formula XML node from the cell without further actions

(aral-matrix) 03 February 2025 - XLComments and shared strings cleanup

Before I start working on the next items on my to-do list (tables/filters, hyperlink support), I am merging all recent patches into master. I have not yet had much feedback on whether the changes work with MS Office, but I am confident that if you discover any issues, I can fix them quickly.

Should you experience stability issues, please revert to commit https://github.com/troldal/OpenXLSX/commit/4ed9c97ad613526bf1544296acd24639dcbe2846 and submit a bug report.

New features

• support for creating / reading / modifying / deleting comments is now implemented in XLComments -> see Demo1.cpp
• using an XLRowIterator no longer creates the XML for rows that do not exist until the iterator is dereferenced
• XLDocument::cleanupSharedStrings() can now be called manually to rewrite the shared strings cache (and remove all strings that are no longer referenced from any cell)

Recent changes

2025-03-16: XLSheet: fixed issue #338 - align cmake_minimum_required to be VERSION 3.15 everywhere

• in response to https://github.com/troldal/OpenXLSX/issues/338, updated all occurrences of CMakeLists.txt in Examples/external/nowide/* to have cmake_minimum_required VERSION 3.15

2025-03-15: XLSheet: fixed issue #337 - assign tabSelected value with newly created attribute if it didn't exist

• in response to https://github.com/troldal/OpenXLSX/issues/337, added a forgotten assignment to XLSheet.cpp

2025-02-17: added some comments to XLSheet class definition to clarify that the sheet index is 1-based (issue #332)

• in response to https://github.com/troldal/OpenXLSX/issues/332, added (doxygen) documentation to XLSheet.hpp clarifying that sheet index is 1-based

2025-02-14 Added cctype includes to XLSheet and XLDrawing, resolving issue #330

• in response to https://github.com/troldal/OpenXLSX/issues/330, added #include <cctype> to XLSheet.cpp and XLDrawing.cpp

2025-02-02 Cleaning up shared strings, non-creating XLRowIterator

2025-01-31 Support for XLWorksheet comments

2025-01-09 Support for XLWorksheet protection

2025-01-08 Support for XLWorksheet conditional formatting (experimental)

Experimental in this case means:

• users are kindly requested to verify that the generated OOXML behaves well with MS Office (I can't promise yet I got the node order right for all scenarios)
• it appears that the <cfRule><formula> may appear up to 3 times per cfRule - the current implementation only supports a single entry for <formula>
• as the conditional formatting uses differential formats, and I am re-using XLStyles classes, there is currently an automatism that by accessing a format property, that property node gets created if it does not yet exist. For differential formats, this is undesired when testing whether a given setting exists. I have yet to implement something along the lines of bool settingExists(std::string settingName)
• I have implemented boolean values to be stored in XML as "true" and "false" - whereas LibreOffice appears to store them (for cfRules) as 1 and 0). The reason is: I want to know if this works, and if it does, stay consistent in how OpenXLSX stores boolean values. I may have to modify this as I learn more
• Another boolean "gotcha": I do not yet know how MS Office evalutes attribute names that exist with an empty value, e.g. aboveAverage="" when for aboveAverage, the documentation defines true as the default - does that mean an empty string gets evaluted as true?

Change history

Change history is found in the detailed change log.

(aral-matrix) 29 September 2024 - Support for styles, merging cells (and more)

Today the features from the development branch finally made it into the main branch :) For details, please refer to the detailed change log below.

In summary:

• OpenXLSX/headers/XLStyles.hpp: XLStyles class (and lots of subclasses) has been added, providing nearly complete access to all Excel formatting capabilities.
• OpenXLSX/headers/XLMergeCells.hpp and XLSheet.hpp: XLMergeCells class is made accessible through XLWorksheet in order to create / delete cell merges
• Examples/Demo10.cpp demonstrates how styles and merges are used Note: The section that is disabled with testBasics = false will break the resulting Excel Spreadsheet if enabled, the only purpose is to demonstrate access to all new classes and methods. If you want to use them, make sure to use them correctly

Note on XLNumberFormat(s): Contrary to all other XLStyles elements, these do not use an index within the XML as the referrable ID (XLCellFormat::setNumberFormatId), but instead a user-defined ID that can be set via XLNumberFormat::setNumberFormatId - and for an XLCellFormat, can be set to either a self-defined number format ID, or to a format predefined by MS. Generally, for custom formats, it is recommended to use IDs > 100.

On the to-do list:

• support predefined number formats with constants that have meaningful