XLUtilities.hpp

Go to the documentation of this file.

#ifndef OPENXLSX_XLUTILITIES_HPP
#define OPENXLSX_XLUTILITIES_HPP
 
#include <fstream>
#include <pugixml.hpp>
#include <string>         // 2024-04-25 needed for xml_node_type_string
#include <string_view>    // std::string_view
#include <vector>         // std::vector< std::string_view >
 
#include "XLCellReference.hpp"
#include "XLCellValue.hpp"        // OpenXLSX::XLValueType
#include "XLConstants.hpp"        // 2024-05-28 OpenXLSX::MAX_ROWS
#include "XLContentTypes.hpp"     // OpenXLSX::XLContentType
#include "XLRelationships.hpp"    // OpenXLSX::XLRelationshipType
#include "XLStyles.hpp"           // OpenXLSX::XLStyleIndex
#include "XLXmlParser.hpp"
 
namespace OpenXLSX
{
    constexpr const bool XLRemoveAttributes = true;     // helper variables for appendAndSetNodeAttribute, parameter removeAttributes
    constexpr const bool XLKeepAttributes   = false;    //
 
    inline bool isCleanXmlString(std::string_view sv) noexcept
    {
        for (char c : sv) {
            unsigned char uc = static_cast<unsigned char>(c);
            if (uc < 0x20 && uc != 0x09 && uc != 0x0A && uc != 0x0D) {
                return false;
            }
        }
        return true;
    }
 
    inline std::string sanitizeXmlString(std::string_view sv)
    {
        std::string result;
        result.reserve(sv.size());
        for (char c : sv) {
            unsigned char uc = static_cast<unsigned char>(c);
            if (uc >= 0x20 || uc == 0x09 || uc == 0x0A || uc == 0x0D) {
                result.push_back(c);
            }
        }
        return result;
    }
 
    inline uint16_t extractColumnFromCellRef(const char* cellRef) noexcept
    {
        if (cellRef == nullptr or *cellRef == '\0') return 0;
 
        uint32_t    colNo = 0;
        const char* p     = cellRef;
 
        // Parse uppercase letters only (A-Z)
        while (*p >= 'A' and *p <= 'Z') {
            colNo = colNo * 26 + static_cast<uint32_t>(*p - 'A' + 1);
            ++p;
        }
 
        // Return 0 if no letters were found, or if column exceeds MAX_COLS
        return (colNo > 0 and colNo <= MAX_COLS) ? static_cast<uint16_t>(colNo) : 0;
    }
 
    inline char* columnToLetters(uint16_t colNo, char* buffer) noexcept
    {
        char temp[4];
        int  idx = 0;
 
        while (colNo > 0) {
            --colNo;    // Convert to 0-indexed for modulo
            temp[idx++] = static_cast<char>('A' + (colNo % 26));
            colNo /= 26;
        }
 
        // Reverse the result into buffer
        int j = 0;
        while (idx > 0) { buffer[j++] = temp[--idx]; }
        buffer[j] = '\0';
 
        return buffer;
    }
 
    #if defined(__GNUC__) || defined(__clang__)
__attribute__((always_inline)) inline char* makeCellAddress(uint32_t row, uint16_t col, char* buffer) noexcept
#elif defined(_MSC_VER)
__forceinline char* makeCellAddress(uint32_t row, uint16_t col, char* buffer) noexcept
#else
inline char* makeCellAddress(uint32_t row, uint16_t col, char* buffer) noexcept
#endif
    {
        // Generate column letters
        char* p = buffer;
        char  colLetters[4];
        columnToLetters(col, colLetters);
 
        // Copy column letters
        for (const char* c = colLetters; *c; ++c) { *p++ = *c; }
 
        // Convert row number to string
        char     rowStr[12];
        int      idx = 0;
        uint32_t r   = row;
        do {
            rowStr[idx++] = static_cast<char>('0' + (r % 10));
            r /= 10;
        }
        while (r > 0);
 
        // Append row digits in reverse order
        while (idx > 0) { *p++ = rowStr[--idx]; }
        *p = '\0';
 
        return buffer;
    }
 
    template<class T>
    void ignore(const T&)
    {}
 
    inline std::string XLValueTypeString(XLValueType t)
    {
        using namespace std::literals::string_literals;
        switch (t) {
            case XLValueType::Empty:
                return "Empty"s;
            case XLValueType::Boolean:
                return "Boolean"s;
            case XLValueType::Integer:
                return "Integer"s;
            case XLValueType::Float:
                return "Float"s;
            case XLValueType::Error:
                return "Error"s;
            case XLValueType::String:
                return "String"s;
            case XLValueType::RichText:
                return "RichText"s;
        }
        throw XLInternalError(__func__ + "Invalid XLValueType."s);
    }
 
    inline std::string xml_node_type_string(pugi::xml_node_type t)
    {
        using namespace std::literals::string_literals;
        switch (t) {
            case pugi::node_null:
                return "node_null"s;
            case pugi::node_document:
                return "node_document"s;
            case pugi::node_element:
                return "node_element"s;
            case pugi::node_pcdata:
                return "node_pcdata"s;
            case pugi::node_cdata:
                return "node_cdata"s;
            case pugi::node_comment:
                return "node_comment"s;
            case pugi::node_pi:
                return "node_pi"s;
            case pugi::node_declaration:
                return "node_declaration"s;
            case pugi::node_doctype:
                return "node_doctype"s;
        }
        throw XLInternalError("Invalid XML node type.");
    }
 
    inline std::string XLContentTypeString(OpenXLSX::XLContentType const& t)
    {
        using namespace OpenXLSX;
        switch (t) {
            case XLContentType::Workbook:
                return "Workbook";
            case XLContentType::Relationships:
                return "Relationships";
            case XLContentType::WorkbookMacroEnabled:
                return "WorkbookMacroEnabled";
            case XLContentType::Worksheet:
                return "Worksheet";
            case XLContentType::Chartsheet:
                return "Chartsheet";
            case XLContentType::ExternalLink:
                return "ExternalLink";
            case XLContentType::Theme:
                return "Theme";
            case XLContentType::Styles:
                return "Styles";
            case XLContentType::SharedStrings:
                return "SharedStrings";
            case XLContentType::Drawing:
                return "Drawing";
            case XLContentType::Chart:
                return "Chart";
            case XLContentType::ChartStyle:
                return "ChartStyle";
            case XLContentType::ChartColorStyle:
                return "ChartColorStyle";
            case XLContentType::ControlProperties:
                return "ControlProperties";
            case XLContentType::CalculationChain:
                return "CalculationChain";
            case XLContentType::VBAProject:
                return "VBAProject";
            case XLContentType::Slicer:
                return "Slicer";
            case XLContentType::SlicerCache:
                return "SlicerCache";
            case XLContentType::PivotTable:
                return "PivotTable";
            case XLContentType::PivotCacheDefinition:
                return "PivotCacheDefinition";
            case XLContentType::PivotCacheRecords:
                return "PivotCacheRecords";
 
            case XLContentType::CoreProperties:
                return "CoreProperties";
            case XLContentType::ExtendedProperties:
                return "ExtendedProperties";
            case XLContentType::CustomProperties:
                return "CustomProperties";
            case XLContentType::VMLDrawing:
                return "VMLDrawing";
            case XLContentType::Comments:
                return "Comments";
            case XLContentType::Table:
                return "Table";
            case XLContentType::ThreadedComments:
                return "ThreadedComments";
            case XLContentType::Persons:
                return "Persons";
            case XLContentType::Hyperlink:
                return "Hyperlink";
            case XLContentType::Unknown:
                return "Unknown";
        }
        return "invalid";
    }
 
    inline std::string XLRelationshipTypeString(OpenXLSX::XLRelationshipType const& t)
    {
        using namespace OpenXLSX;
        switch (t) {
            case XLRelationshipType::CoreProperties:
                return "CoreProperties";
            case XLRelationshipType::ExtendedProperties:
                return "ExtendedProperties";
            case XLRelationshipType::CustomProperties:
                return "CustomProperties";
            case XLRelationshipType::Workbook:
                return "Workbook";
            case XLRelationshipType::Worksheet:
                return "Worksheet";
            case XLRelationshipType::Chartsheet:
                return "Chartsheet";
            case XLRelationshipType::Dialogsheet:
                return "Dialogsheet";
            case XLRelationshipType::Macrosheet:
                return "Macrosheet";
            case XLRelationshipType::CalculationChain:
                return "CalculationChain";
            case XLRelationshipType::ExternalLink:
                return "ExternalLink";
            case XLRelationshipType::ExternalLinkPath:
                return "ExternalLinkPath";
            case XLRelationshipType::Theme:
                return "Theme";
            case XLRelationshipType::Styles:
                return "Styles";
            case XLRelationshipType::Chart:
                return "Chart";
            case XLRelationshipType::ChartStyle:
                return "ChartStyle";
            case XLRelationshipType::ChartColorStyle:
                return "ChartColorStyle";
            case XLRelationshipType::Image:
                return "Image";
            case XLRelationshipType::Drawing:
                return "Drawing";
            case XLRelationshipType::VMLDrawing:
                return "VMLDrawing";
            case XLRelationshipType::SharedStrings:
                return "SharedStrings";
            case XLRelationshipType::PrinterSettings:
                return "PrinterSettings";
            case XLRelationshipType::VBAProject:
                return "VBAProject";
            case XLRelationshipType::Slicer:
                return "Slicer";
            case XLRelationshipType::SlicerCache:
                return "SlicerCache";
            case XLRelationshipType::PivotTable:
                return "PivotTable";
            case XLRelationshipType::PivotCacheDefinition:
                return "PivotCacheDefinition";
            case XLRelationshipType::PivotCacheRecords:
                return "PivotCacheRecords";
 
            case XLRelationshipType::ControlProperties:
                return "ControlProperties";
            case XLRelationshipType::Comments:
                return "Comments";
            case XLRelationshipType::Table:
                return "Table";
            case XLRelationshipType::ThreadedComments:
                return "ThreadedComments";
            case XLRelationshipType::Person:
                return "Person";
            case XLRelationshipType::Hyperlink:
                return "Hyperlink";
            case XLRelationshipType::Unknown:
                return "Unknown";
        }
        return "invalid";
    }
 
    inline XMLNode getRowNode(XMLNode sheetDataNode, uint32_t rowNumber, uint32_t* hintRowNumber = nullptr, XMLNode* hintRowNode = nullptr)
    {
        if (rowNumber < 1 or rowNumber > OpenXLSX::MAX_ROWS) {    // 2024-05-28: added range check
            using namespace std::literals::string_literals;
            throw XLCellAddressError("rowNumber "s + std::to_string(rowNumber) + " is outside valid range [1;"s +
                                     std::to_string(OpenXLSX::MAX_ROWS) + "]"s);
        }
 
        // ===== O(1) Hint Fast-Path
        if (hintRowNumber && hintRowNode && *hintRowNumber == rowNumber && !hintRowNode->empty()) {
            return *hintRowNode;
        }
 
        XMLNode result;
 
        // ===== Optimized Hint Crawl (if the target row is exactly the next row or very close after the hint)
        if (hintRowNumber && hintRowNode && !hintRowNode->empty() && rowNumber > *hintRowNumber) {
            result = *hintRowNode;
            while (!result.empty() && result.attribute("r").as_ullong() < rowNumber) {
                result = result.next_sibling_of_type(pugi::node_element);
            }
            if (result.empty() || result.attribute("r").as_ullong() > rowNumber) {
                if (result.empty()) result = sheetDataNode.append_child("row");
                else result = sheetDataNode.insert_child_before("row", result);
                result.append_attribute("r") = rowNumber;
            }
        }
        else if (hintRowNumber && hintRowNode && !hintRowNode->empty() && rowNumber < *hintRowNumber) {
            result = *hintRowNode;
            while (!result.empty() && result.attribute("r").as_ullong() > rowNumber) {
                result = result.previous_sibling_of_type(pugi::node_element);
            }
            if (result.empty() || result.attribute("r").as_ullong() < rowNumber) {
                if (result.empty()) result = sheetDataNode.prepend_child("row");
                else result = sheetDataNode.insert_child_after("row", result);
                result.append_attribute("r") = rowNumber;
            }
        }
        else {
            // ===== Original Binary/Edge crawling fallback
            result = sheetDataNode.last_child_of_type(pugi::node_element);
 
            if (result.empty() or (rowNumber > result.attribute("r").as_ullong())) {
                result                       = sheetDataNode.append_child("row");
                result.append_attribute("r") = rowNumber;
            }
            else if (result.attribute("r").as_ullong() - rowNumber < rowNumber) {
                while (not result.empty() and (result.attribute("r").as_ullong() > rowNumber))
                    result = result.previous_sibling_of_type(pugi::node_element);
                if (result.empty() or (result.attribute("r").as_ullong() != rowNumber)) {
                    if (result.empty())
                        result = sheetDataNode.prepend_child("row");
                    else
                        result = sheetDataNode.insert_child_after("row", result);
                    result.append_attribute("r") = rowNumber;
                }
            }
            else {
                result = sheetDataNode.first_child_of_type(pugi::node_element);
                while (result.attribute("r").as_ullong() < rowNumber) result = result.next_sibling_of_type(pugi::node_element);
                if (result.attribute("r").as_ullong() > rowNumber) {
                    result = sheetDataNode.insert_child_before("row", result);
                    result.append_attribute("r") = rowNumber;
                }
            }
        }
 
        // Update the hint for next time
        if (hintRowNumber && hintRowNode) {
            *hintRowNumber = rowNumber;
            *hintRowNode = result;
        }
 
        return result;
    }
 
    inline std::vector<XLStyleIndex> getColumnStyles(XMLNode rowNode, uint16_t count)
    {
        std::vector<XLStyleIndex> styles(count, XLDefaultCellFormat);
        XMLNode cols = rowNode.parent().parent().child("cols");
        if (not cols.empty()) {
            XMLNode col = cols.first_child_of_type(pugi::node_element);
            while (not col.empty()) {
                int minCol = col.attribute("min").as_int(MAX_COLS + 1);
                int maxCol = col.attribute("max").as_int(0);
                uint32_t style = col.attribute("style").as_uint(XLDefaultCellFormat);
                
                for (int i = minCol; i <= maxCol && i <= count; ++i) {
                    if (i > 0) styles[i - 1] = style;
                }
                col = col.next_sibling_of_type(pugi::node_element);
            }
        }
        return styles;
    }
 
    inline XLStyleIndex getColumnStyle(XMLNode rowNode, uint16_t colNo)
    {
        XMLNode cols = rowNode.parent().parent().child("cols");
        if (not cols.empty()) {
            XMLNode col = cols.first_child_of_type(pugi::node_element);
            while (not col.empty()) {
                if (col.attribute("min").as_int(MAX_COLS + 1) <= colNo and col.attribute("max").as_int(0) >= colNo)    // found
                    return col.attribute("style").as_uint(XLDefaultCellFormat);
                col = col.next_sibling_of_type(pugi::node_element);
            }
        }
        return XLDefaultCellFormat;    // if no col style was found
    }
 
    inline void setDefaultCellAttributes(XMLNode                               cellNode,
                                         const std::string&                    cellRef,
                                         XMLNode                               rowNode,
                                         uint16_t                              colNo,
                                          std::vector<XLStyleIndex> const& colStyles = {})
    {
        cellNode.append_attribute("r").set_value(cellRef.c_str());
        XMLAttribute rowStyle = rowNode.attribute("s");
        XLStyleIndex cellStyle;          // scope declaration
        if (rowStyle.empty()) {          // if no explicit row style is set
            if (colStyles.size() > 0)    // if colStyles were provided
                cellStyle =
                    (colNo > colStyles.size() ? XLDefaultCellFormat : colStyles[colNo - 1]);    // determine cellStyle from colStyles
            else                                                                                // else: no colStyles provided
                cellStyle = getColumnStyle(rowNode, colNo);                                     // so perform a lookup
        }
        else                                                      // else: an explicit row style is set
            cellStyle = rowStyle.as_uint(XLDefaultCellFormat);    // use the row style
 
        if (cellStyle != XLDefaultCellFormat)    // if cellStyle was determined as not the default style (no point in setting that)
            cellNode.append_attribute("s").set_value(cellStyle);
    }
 
    inline void setDefaultCellAttributes(XMLNode                               cellNode,
                                         const char*                           cellRef,
                                         XMLNode                               rowNode,
                                         uint16_t                              colNo,
                                          std::vector<XLStyleIndex> const& colStyles = {})
    {
        cellNode.append_attribute("r").set_value(cellRef);
        XMLAttribute rowStyle = rowNode.attribute("s");
        XLStyleIndex cellStyle;
        if (rowStyle.empty()) {
            if (colStyles.size() > 0)
                cellStyle = (colNo > colStyles.size() ? XLDefaultCellFormat : colStyles[colNo - 1]);
            else
                cellStyle = getColumnStyle(rowNode, colNo);
        }
        else
            cellStyle = rowStyle.as_uint(XLDefaultCellFormat);
 
        if (cellStyle != XLDefaultCellFormat) cellNode.append_attribute("s").set_value(cellStyle);
    }
 
    inline XMLNode getCellNode(XMLNode                               rowNode,
                               uint16_t                              columnNumber,
                               uint32_t                              rowNumber = 0,
                                std::vector<XLStyleIndex> const& colStyles = {},
                               uint16_t*                             hintColNumber = nullptr,
                               XMLNode*                              hintCellNode = nullptr)
    {
        if (columnNumber < 1 or columnNumber > OpenXLSX::MAX_COLS) {    // 2024-08-05: added range check
            using namespace std::literals::string_literals;
            throw XLException("XLWorksheet::column: columnNumber "s + std::to_string(columnNumber) + " is outside allowed range [1;"s +
                              std::to_string(MAX_COLS) + "]"s);
        }
        if (rowNode.empty()) return XMLNode{};    // 2024-05-28: return an empty node in case of empty rowNode
 
        if (!rowNumber) rowNumber = rowNode.attribute("r").as_uint();    // if not provided, determine from rowNode
 
        // ===== O(1) Hint Fast-Path
        if (hintColNumber && hintCellNode && *hintColNumber == columnNumber && !hintCellNode->empty() && hintCellNode->parent() == rowNode) {
            return *hintCellNode;
        }
 
        XMLNode cellNode;
 
        // ===== Optimized Hint Crawl
        if (hintColNumber && hintCellNode && !hintCellNode->empty() && hintCellNode->parent() == rowNode) {
            cellNode = *hintCellNode;
            if (columnNumber > *hintColNumber) {
                uint16_t currentCol = *hintColNumber;
                while (!cellNode.empty() && currentCol < columnNumber) {
                    cellNode = cellNode.next_sibling_of_type(pugi::node_element);
                    currentCol = cellNode.empty() ? 0 : extractColumnFromCellRef(cellNode.attribute("r").value());
                }
                if (currentCol > columnNumber || cellNode.empty()) {
                    if (cellNode.empty()) cellNode = rowNode.append_child("c");
                    else cellNode = rowNode.insert_child_before("c", cellNode);
                    char cellAddrBuf[16];
                    makeCellAddress(rowNumber, columnNumber, cellAddrBuf);
                    setDefaultCellAttributes(cellNode, cellAddrBuf, rowNode, columnNumber, colStyles);
                }
                goto update_hint;
            }
            else if (columnNumber < *hintColNumber) {
                uint16_t currentCol = *hintColNumber;
                while (!cellNode.empty() && currentCol > columnNumber) {
                    cellNode = cellNode.previous_sibling_of_type(pugi::node_element);
                    currentCol = cellNode.empty() ? 0 : extractColumnFromCellRef(cellNode.attribute("r").value());
                }
                if (currentCol < columnNumber || cellNode.empty()) {
                    if (cellNode.empty()) cellNode = rowNode.prepend_child("c");
                    else cellNode = rowNode.insert_child_after("c", cellNode);
                    char cellAddrBuf[16];
                    makeCellAddress(rowNumber, columnNumber, cellAddrBuf);
                    setDefaultCellAttributes(cellNode, cellAddrBuf, rowNode, columnNumber, colStyles);
                }
                goto update_hint;
            }
        }
 
        // ===== Original Fallback Crawl
        cellNode = rowNode.last_child_of_type(pugi::node_element);
        {
            uint16_t lastCellCol = cellNode.empty() ? 0 : extractColumnFromCellRef(cellNode.attribute("r").value());
 
            if (cellNode.empty() or (lastCellCol < columnNumber)) {
                cellNode = rowNode.append_child("c");
                char cellAddrBuf[16];
                makeCellAddress(rowNumber, columnNumber, cellAddrBuf);
                setDefaultCellAttributes(cellNode, cellAddrBuf, rowNode, columnNumber, colStyles);
            }
            else if (lastCellCol - columnNumber < columnNumber) {
                uint16_t currentCol = lastCellCol;
                while (not cellNode.empty() and (currentCol > columnNumber)) {
                    cellNode   = cellNode.previous_sibling_of_type(pugi::node_element);
                    currentCol = cellNode.empty() ? 0 : extractColumnFromCellRef(cellNode.attribute("r").value());
                }
                if (cellNode.empty() or (currentCol < columnNumber)) {
                    if (cellNode.empty()) cellNode = rowNode.prepend_child("c");
                    else cellNode = rowNode.insert_child_after("c", cellNode);
                    char cellAddrBuf[16];
                    makeCellAddress(rowNumber, columnNumber, cellAddrBuf);
                    setDefaultCellAttributes(cellNode, cellAddrBuf, rowNode, columnNumber, colStyles);
                }
            }
            else {
                cellNode = rowNode.first_child_of_type(pugi::node_element);
                uint16_t currentCol = extractColumnFromCellRef(cellNode.attribute("r").value());
                while (currentCol < columnNumber) {
                    cellNode   = cellNode.next_sibling_of_type(pugi::node_element);
                    currentCol = extractColumnFromCellRef(cellNode.attribute("r").value());
                }
                if (currentCol > columnNumber) {
                    cellNode = rowNode.insert_child_before("c", cellNode);
                    char cellAddrBuf[16];
                    makeCellAddress(rowNumber, columnNumber, cellAddrBuf);
                    setDefaultCellAttributes(cellNode, cellAddrBuf, rowNode, columnNumber, colStyles);
                }
            }
        }
 
update_hint:
        if (hintColNumber && hintCellNode) {
            *hintColNumber = columnNumber;
            *hintCellNode = cellNode;
        }
        return cellNode;
    }
 
    constexpr const int SORT_INDEX_NOT_FOUND = -1;
    inline int          findStringInVector(std::string const& nodeName, std::vector<std::string_view> const& nodeOrder)
    {
        for (size_t i = 0; i < nodeOrder.size(); ++i)
            if (nodeName == nodeOrder[i]) return static_cast<int>(i);
        return SORT_INDEX_NOT_FOUND;
    }
 
    inline void copyLeadingWhitespaces(XMLNode& parent, XMLNode fromNode, XMLNode toNode)
    {
        fromNode = fromNode.previous_sibling();    // move to preceeding whitespace node, if any
        // loop from back to front, inserting in the same order before toNode
        while (fromNode.type() == pugi::node_pcdata) {                         // loop ends on pugi::node_element or node_null
            toNode = parent.insert_child_before(pugi::node_pcdata, toNode);    // prepend as toNode a new pcdata node
            toNode.set_value(fromNode.value());                                //  with the value of fromNode
            fromNode = fromNode.previous_sibling();
        }
    }
 
    inline XMLNode appendAndGetNode(XMLNode&                             parent,
                                    std::string const&                   nodeName,
                                    std::vector<std::string_view> const& nodeOrder = {},
                                    bool                                 force_ns  = false)
    {
        if (parent.empty()) return XMLNode{};
 
        XMLNode nextNode = parent.first_child_of_type(pugi::node_element);
        if (nextNode.empty())
            return parent.prepend_child(nodeName.c_str(), force_ns);    // nothing to sort, whitespaces "belong" to parent closing tag
 
        XMLNode node{};    // empty until successfully created;
 
        int nodeSortIndex = (nodeOrder.size() > 1 ? findStringInVector(nodeName, nodeOrder) : SORT_INDEX_NOT_FOUND);
        if (nodeSortIndex !=
            SORT_INDEX_NOT_FOUND) {    // can't sort anything if nodeOrder contains less than 2 entries or does not contain nodeName
            // ===== Find first node to follow nodeName per nodeOrder
            while (not nextNode.empty() and findStringInVector(nextNode.name(), nodeOrder) < nodeSortIndex)
                nextNode = nextNode.next_sibling_of_type(pugi::node_element);
            // ===== Evaluate search result
            if (not nextNode.empty()) {             // found nodeName or a node before which nodeName should be inserted
                if (nextNode.name() == nodeName)    // if nodeName was found
                    node = nextNode;                // use existing node
                else {                              // else: a node was found before which nodeName must be inserted
                    node =
                        parent.insert_child_before(nodeName.c_str(), nextNode, force_ns);    // insert before nextNode without whitespaces
                    copyLeadingWhitespaces(parent, node, nextNode);
                }
            }
            // else: no node was found before which nodeName should be inserted: proceed as usual
        }
        else    // no possibility to perform ordered insert - attempt to locate existing node:
            node = parent.child(nodeName.c_str());
 
        if (node.empty()) {    // neither nodeName, nor a node following per nodeOrder was found
            // ===== There is no reference to perform an ordered insert for nodeName
            nextNode =
                parent.last_child_of_type(pugi::node_element);    // at least one element node must exist, tested at begin of function
            node = parent.insert_child_after(nodeName.c_str(),
                                             nextNode,
                                             force_ns);        // append as the last element node, but before final whitespaces
            copyLeadingWhitespaces(parent, nextNode, node);    // duplicate the prefix whitespaces of nextNode to node
        }
 
        return node;
    }
 
    inline XMLAttribute appendAndGetAttribute(XMLNode& node, std::string const& attrName, std::string const& attrDefaultVal)
    {
        if (node.empty()) return XMLAttribute{};
        XMLAttribute attr = node.attribute(attrName.c_str());
        if (attr.empty()) {
            attr = node.append_attribute(attrName.c_str());
            attr.set_value(attrDefaultVal.c_str());
        }
        return attr;
    }
 
    inline XMLAttribute appendAndSetAttribute(XMLNode& node, std::string const& attrName, std::string const& attrVal)
    {
        if (node.empty()) return XMLAttribute{};
        XMLAttribute attr = node.attribute(attrName.c_str());
        if (attr.empty()) attr = node.append_attribute(attrName.c_str());
        attr.set_value(attrVal.c_str());    // silently fails on empty attribute, which is intended here
        return attr;
    }
 
    inline XMLAttribute appendAndGetNodeAttribute(XMLNode&                                  parent,
                                                  std::string const&                        nodeName,
                                                  std::string const&                        attrName,
                                                  std::string const&                        attrDefaultVal,
                                                   std::vector<std::string_view> const& nodeOrder = {})
    {
        if (parent.empty()) return XMLAttribute{};
        XMLNode node = appendAndGetNode(parent, nodeName, nodeOrder);
        return appendAndGetAttribute(node, attrName, attrDefaultVal);
    }
 
    inline XMLAttribute appendAndSetNodeAttribute(XMLNode&                             parent,
                                                  std::string const&                   nodeName,
                                                  std::string const&                   attrName,
                                                  std::string const&                   attrVal,
                                                   bool                            removeAttributes = XLKeepAttributes,
                                                  std::vector<std::string_view> const& nodeOrder        = {})
    {
        if (parent.empty()) return XMLAttribute{};
        XMLNode node = appendAndGetNode(parent, nodeName, nodeOrder);
        if (removeAttributes) node.remove_attributes();
        return appendAndSetAttribute(node, attrName, attrVal);
    }
 
    inline bool getBoolAttributeWhenOmittedMeansTrue(XMLNode& parent, std::string const& tagName, std::string const& attrName = "val")
    {
        if (parent.empty()) return false;    // can't do anything
        XMLNode tagNode = parent.child(tagName.c_str());
        if (tagNode.empty()) return false;    // if tag does not exist: return false
        XMLAttribute valAttr = tagNode.attribute(attrName.c_str());
        if (valAttr.empty()) {                                   // if no attribute with attrName exists: default to true
            appendAndSetAttribute(tagNode, attrName, "true");    // explicitly create & set attribute
            return true;
        }
        // if execution gets here: attribute with attrName exists
        return valAttr.as_bool();    // return attribute value
    }
 
    inline std::pair<uint32_t, uint32_t> getImageDimensions(const std::string& data)
    {
        if (data.size() < 8) return {0, 0};
 
        // Check for PNG
        if (reinterpret_cast<const uint8_t*>(data.data())[0] == 0x89 and data.substr(1, 3) == "PNG") {
            if (data.size() < 24) return {0, 0};
            // IHDR chunk starts at offset 12. Width at 16, height at 20 (4 bytes each, big-endian)
            const uint8_t* p = reinterpret_cast<const uint8_t*>(data.data());
            uint32_t w = (static_cast<uint32_t>(p[16]) << 24) | (static_cast<uint32_t>(p[17]) << 16) | (static_cast<uint32_t>(p[18]) << 8) |
                         static_cast<uint32_t>(p[19]);
            uint32_t h = (static_cast<uint32_t>(p[20]) << 24) | (static_cast<uint32_t>(p[21]) << 16) | (static_cast<uint32_t>(p[22]) << 8) |
                         static_cast<uint32_t>(p[23]);
            return {w, h};
        }
 
        // Check for JPEG
        if (reinterpret_cast<const uint8_t*>(data.data())[0] == 0xFF and reinterpret_cast<const uint8_t*>(data.data())[1] == 0xD8) {
            size_t offset = 2;
            while (offset + 4 < data.size()) {
                const uint8_t* p = reinterpret_cast<const uint8_t*>(data.data()) + offset;
                if (p[0] != 0xFF) break;
                uint8_t  marker = p[1];
                uint32_t length = (static_cast<uint32_t>(p[2]) << 8) | static_cast<uint32_t>(p[3]);
 
                // SOF0 (Start Of Frame 0) marker is 0xFFC0. Others are 0xFFC1-0xFFC3, 0xFFC5-0xFFC7, 0xFFC9-0xFFCB, 0xFFCD-0xFFCF
                if ((marker >= 0xC0 and marker <= 0xC3) or (marker >= 0xC5 and marker <= 0xC7) or (marker >= 0xC9 and marker <= 0xCB) ||
                    (marker >= 0xCD and marker <= 0xCF))
                {
                    if (offset + 9 > data.size()) return {0, 0};
                    // Height is at offset 5, width at 7 (2 bytes each, big-endian)
                    uint32_t h = (static_cast<uint32_t>(p[5]) << 8) | static_cast<uint32_t>(p[6]);
                    uint32_t w = (static_cast<uint32_t>(p[7]) << 8) | static_cast<uint32_t>(p[8]);
                    return {w, h};
                }
                offset += length + 2;
            }
        }
 
        return {0, 0};
    }
 
}    // namespace OpenXLSX
 
#endif    // OPENXLSX_XLUTILITIES_HPP