repository·master·Indexed 23 days ago
https://github.com/troldal/openxlsxA high-performance C++ library for reading, writing, creating, and modifying Microsoft Excel (.xlsx) files. It provides capabilities for manipulating data and formatting, including cell ranges, worksheets, styles, conditional formatting, and merged cells. The library depends on PugiXML and Zippy (or libzip) and requires UTF-8 encoding for all text input and output.
.xlsx format. The library focuses on speed and aims to provide a mature feature set for C++ developers, similar to what is available in Python, Java, or C#.OpenXLSX is a work in progress. The following features are currently implemented and functional:
Known Limitations:
const XLDocument objects is currently not working.OpenXLSX uses the miniz library for zip compression/decompression. There is a maximum allowable size for any single entry (e.g., an individual .xml worksheet file) within the .xlsx archive, which is 4 GB (uncompressed).
Key details:
XLComments implementation. You can iterate over only the existing comments in a worksheet as they appear in the underlying XML, which is useful when processing files created by other applications.OpenXLSX requires all text input and output to be in UTF-8 encoding. Failure to use UTF-8 may result in unexpected behavior or crashes.
std::wstring on Windows), you must manually convert them to/from UTF-8. OpenXLSX internally uses Boost.Nowide for these conversions.Unicode support on Windows terminals can be challenging; non-ASCII characters (e.g., Chinese or Japanese) may appear as gibberish in the terminal. Always ensure your IDE is configured to save files in UTF-8 to avoid crashes when opening files with non-ASCII filenames.
OpenXLSX uses the PugiXML DOM parser, which loads the entire XML document into memory for high-speed manipulation. This can lead to high memory consumption for large spreadsheets.
Assuming a worksheet with 1,048,576 rows, the following table provides an estimate of column capacity based on available RAM:
| RAM | Columns |
|---|---|
| 8 GB | 8-16 |
| 16 GB | 32-64 |
| 32 GB | 128-256 |
Note: Performance depends on data type and your specific environment.
If memory is a constraint, you can build OpenXLSX in compact mode by enabling the ENABLE_COMPACT_MODE flag in the CMakeLists.txt file. This enables PugiXML's compact mode, reducing memory usage at the cost of execution speed.
It is strongly recommended to use OpenXLSX in 64-bit mode. While 32-bit mode is supported, it is limited to 4 GB of RAM, which significantly restricts the ability to handle large spreadsheets.
Conditional formatting is currently implemented in an experimental stage.
Usage Notes & Limitations:
<formula> entry per <cfRule>. It does not support cases where <cfRule><formula> appears multiple times."true" and "false". (Note: LibreOffice may use 1 and 0).XLStyles. Accessing a format property may automatically create that node if it does not exist.OpenXLSX depends on the following 3rd party libraries:
miniz). Alternatively, libzip can be used via the -DOPENXLSX_ENABLE_LIBZIP=ON CMake flag.| Platform | GCC | Clang | MSVC |
|---|---|---|---|
| Windows | MinGW | MinGW | + |
| MacOS | + | + | N/A |
| Linux | + | + | N/A |
Minimum Compiler Versions:
The easiest way to use OpenXLSX is to add its root folder as a subdirectory in your own project's CMakeLists.txt. This ensures the library is built with the same configuration (Debug/Release) as your application, which is critical on Windows when passing STL objects.
Use add_subdirectory( OpenXLSX ) to make the OpenXLSX::OpenXLSX target available. You can control whether to build a shared library by setting BUILD_SHARED_LIBS to ON.
# ============================================================================
# Configure OpenXLSX
# ============================================================================
set(OPENXLSX_CREATE_DOCS OFF)
set(OPENXLSX_BUILD_SAMPLES OFF)
set( BUILD_SHARED_LIBS OFF)
add_subdirectory( OpenXLSX )
# Configure linkage for myapp
target_link_libraries(myapp PRIVATE OpenXLSX::OpenXLSX)
target_include_directories(myapp PRIVATE ${OpenXLSX_INCLUDES})To build OpenXLSX, you must have cmake and git installed. On Debian-based Linux distributions, you can install the necessary build tools using apt.
sudo apt update
sudo apt install build-essential cmake gitBy default, OpenXLSX uses Zippy (a wrapper around miniz). If you encounter stability issues with miniz or wish to use a different library (like libzip), you can provide a custom implementation.
IZipArchive class.IZipArchive is required; the class just needs to provide the expected methods).OpenXLSX constructor.Refer to Examples/Demo1A for a complete implementation using libzip via a class named CustomZip. To build this specific example, enable the OPENXLSX_ENABLE_LIBZIP_EXAMPLE option in the root CMakeLists.txt and ensure libzip is installed on your system.
For Windows 10/11, it is recommended to use the MSYS2 environment with MSYS Makefiles.
winget install --id MSYS2.MSYS2 -e in an Administrator PowerShell.pacman -Syu then pacman -Su.pacman -S --needed base-devel mingw-w64-x86_64-toolchain.pacman -S --needed mingw-w64-x86_64-cmake mingw-w64-x86_64-git.git --version; cmake --version; gcc --version; g++ --version in the MinGW 64-bit shell.git --version; cmake --version; gcc --version; g++ --version