react-native-nitro-xlsx 0.2.5 → 0.2.6

package/thirdparty/OpenXLSX/OpenXLSX/headers/XLXmlParser.hpp

@@ -0,0 +1,282 @@
+/*
+
+   ____                               ____      ___ ____       ____  ____      ___
+  6MMMMb                              `MM(      )M' `MM'      6MMMMb\`MM(      )M'
+ 8P    Y8                              `MM.     d'   MM      6M'    ` `MM.     d'
+6M      Mb __ ____     ____  ___  __    `MM.   d'    MM      MM        `MM.   d'
+MM      MM `M6MMMMb   6MMMMb `MM 6MMb    `MM. d'     MM      YM.        `MM. d'
+MM      MM  MM'  `Mb 6M'  `Mb MMM9 `Mb    `MMd       MM       YMMMMb     `MMd
+MM      MM  MM    MM MM    MM MM'   MM     dMM.      MM           `Mb     dMM.
+MM      MM  MM    MM MMMMMMMM MM    MM    d'`MM.     MM            MM    d'`MM.
+YM      M9  MM    MM MM       MM    MM   d'  `MM.    MM            MM   d'  `MM.
+ 8b    d8   MM.  ,M9 YM    d9 MM    MM  d'    `MM.   MM    / L    ,M9  d'    `MM.
+  YMMMM9    MMYMMM9   YMMMM9 _MM_  _MM_M(_    _)MM_ _MMMMMMM MYMMMM9 _M(_    _)MM_
+            MM
+            MM
+           _MM_
+
+  Copyright (c) 2018, Kenneth Troldal Balslev
+
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+  - Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+  - Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  - Neither the name of the author nor the
+    names of any contributors may be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+ */
+
+#ifndef OPENXLSX_XLXMLPARSER_HPP
+#define OPENXLSX_XLXMLPARSER_HPP
+
+#include <memory> // shared_ptr
+
+// ===== pugixml header needed for pugi::impl::xml_memory_page_type_mask, pugi::xml_node_type, pugi::char_t, pugi::node_element, pugi::xml_node, pugi::xml_attribute, pugi::xml_document
+#include <pugixml.hpp>                   // include public pugixml header, wherever it may be in the include paths
+#include "XLException.hpp"
+#include "XLXmlParserForwardDeclarations.hpp"
+
+namespace { // anonymous namespace to define constants / functions that shall not be exported from this module
+    constexpr const int XLMaxNamespacedNameLen = 100;
+} // anonymous namespace
+
+namespace OpenXLSX
+{
+#   define ENABLE_XML_NAMESPACES 1    // disable this line to control behavior via compiler flag
+#   define NO_MULTITHREADING_SAFETY 1 // if this is defined, the function namespaced_name_char will be used for XML namespace support,
+//                                    //  using a static character array for improved performance when multithreading conflicts are not a risk
+
+#   ifdef ENABLE_XML_NAMESPACES
+        // ===== Macro for NAMESPACED_NAME when node names might need to be prefixed with the current node's namespace
+#       ifdef NO_MULTITHREADING_SAFETY
+#           define NAMESPACED_NAME(name_, force_ns_) namespaced_name_char(name_, force_ns_)
+#       else
+#           define NAMESPACED_NAME(name_, force_ns_) namespaced_name_shared_ptr(name_, force_ns_).get()
+#       endif
+#   else
+        // ===== Optimized version when no namespace support is desired - ignores force_ns_ setting
+#       define NAMESPACED_NAME(name_, force_ns_) name_
+#   endif
+
+    constexpr const bool XLForceNamespace = true;
+    /**
+     * With namespace support: where OpenXLSX already addresses nodes by their namespace, doubling the namespace in a node name
+     *   upon node create can be avoided by passing the optional parameter XLForceNamespace - this will use the node name passed to the
+     *   insertion function "as-is".
+     * Affected XMLNode methods: ::set_name, ::append_child, ::prepend_child, ::insert_child_after, ::insert_child_before
+     */
+
+    extern bool NO_XML_NS; // defined in XLXmlParser.cpp - default: no XML namespaces
+    /**
+     * @brief Set NO_XML_NS to false
+     * @return true if PUGI_AUGMENTED is defined (success), false if PUGI_AUGMENTED is not in use (function would be pointless)
+     * @note CAUTION: this setting should be established before any other OpenXLSX function is used
+     */
+    bool enable_xml_namespaces();
+    /**
+     * @brief Set NO_XML_NS to true
+     * @return true if PUGI_AUGMENTED is defined (success), false if PUGI_AUGMENTED is not in use (function would be pointless)
+     * @note CAUTION: this setting should be established before any other OpenXLSX function is used
+     */
+    bool disable_xml_namespaces();
+
+
+    // ===== 2025-07-14: moved forward declarations to XLXmlParserForwardDeclarations.hpp =====
+
+
+    // ===== Custom OpenXLSX_xml_node to add functionality to pugi::xml_node
+    class OpenXLSX_xml_node : public pugi::xml_node {
+    public:
+        /**
+         * @brief Default constructor. Constructs a null object.
+         */
+        OpenXLSX_xml_node() : pugi::xml_node(), name_begin(0) {}
+
+        /**
+         * @brief Inherit all constructors with parameters from pugi::xml_node
+         */
+        template<class base>
+        // explicit OpenXLSX_xml_node(base b) : pugi::xml_node(b), name_begin(0) // TBD on explicit keyword
+        OpenXLSX_xml_node(base b) : pugi::xml_node(b), name_begin(0)
+        {
+            if (NO_XML_NS) return;
+                const char *name = xml_node::name();
+            int pos = 0;
+            while (name[pos] && name[pos] != ':') ++pos; // find name delimiter
+            if (name[pos] == ':') name_begin = pos + 1;  // if delimiter was found: update name_begin to point behind that position
+        }
+
+        /**
+         * @brief Strip any namespace from name_
+         * @param name_ A node name which may be prefixed with any namespace like so "namespace:nodename"
+         * @return The name_ stripped of a namespace prefix
+         */
+        const pugi::char_t* name_without_namespace(const pugi::char_t* name_) const;
+
+        /**
+         * @brief add this node's namespace to name_
+         * @param name_ a node name which shall be prefixed with this node's current namespace
+         * @param force_ns if true, will return name_ unmodified
+         * @return this node's current namespace + ":" + name_ as a const pugi::char_t *
+         */
+        const pugi::char_t* namespaced_name_char(const pugi::char_t* name_, bool force_ns) const;
+
+        /**
+         * @brief add this node's namespace to name_
+         * @param name_ a node name which shall be prefixed with this node's current namespace
+         * @param force_ns if true, will return name_ unmodified
+         * @return this node's current namespace + ":" + name_ as a shared_ptr to pugi::char_t
+         */
+        std::shared_ptr<pugi::char_t> namespaced_name_shared_ptr(const pugi::char_t* name_, bool force_ns) const;
+
+
+        // ===== BEGIN: Wrappers for xml_node member functions to ensure OpenXLSX_xml_node return values
+        //                and overrides for xml_node member functions to support ignoring the node namespace
+        // ===== CAUTION: this section might be incomplete, only functions actually used by OpenXLSX to date have been checked
+
+        /**
+         * @brief get node name while stripping namespace, if so configured (name_begin > 0)
+         * @return the node name without a namespace
+         */
+        const pugi::char_t* name() const { return &xml_node::name()[name_begin]; }
+
+        /**
+         * @brief get actual node name from pugi::xml_node::name, including namespace, if any
+         * @return the raw node name
+         */
+        const pugi::char_t* raw_name() const { return xml_node::name(); }
+
+        /**
+         * @brief for all functions returning xml_node: invoke base class function, but with a return type of XMLNode (OpenXLSX_xml_node)
+         */
+        XMLNode parent() { return pugi::xml_node::parent(); }
+        template <typename Predicate> XMLNode find_child(Predicate pred) const { return pugi::xml_node::find_child(pred); }
+        XMLNode child(const pugi::char_t* name_) const { return xml_node::child(NAMESPACED_NAME(name_, false)); }
+        XMLNode next_sibling(const pugi::char_t* name_) const { return xml_node::next_sibling(NAMESPACED_NAME(name_, false)); }
+        XMLNode next_sibling() const { return xml_node::next_sibling(); }
+        XMLNode previous_sibling(const pugi::char_t* name_) const { return xml_node::previous_sibling(NAMESPACED_NAME(name_, false)); }
+        XMLNode previous_sibling() const { return xml_node::previous_sibling(); }
+        const pugi::char_t* child_value() const { return xml_node::child_value(); }
+        const pugi::char_t* child_value(const pugi::char_t* name_) const { return xml_node::child_value(NAMESPACED_NAME(name_, false)); }
+        bool set_name(const pugi::char_t* rhs, bool force_ns = false) { return xml_node::set_name(NAMESPACED_NAME(rhs, force_ns)); }
+        bool set_name(const pugi::char_t* rhs, size_t size, bool force_ns = false) { return xml_node::set_name(NAMESPACED_NAME(rhs, force_ns), size + name_begin); }
+        XMLNode append_child(pugi::xml_node_type type_) { return xml_node::append_child(type_); }
+        XMLNode prepend_child(pugi::xml_node_type type_) { return xml_node::prepend_child(type_); }
+        XMLNode append_child(const pugi::char_t* name_, bool force_ns = false) { return xml_node::append_child(NAMESPACED_NAME(name_, force_ns)); }
+        XMLNode prepend_child(const pugi::char_t* name_, bool force_ns = false) { return xml_node::prepend_child(NAMESPACED_NAME(name_, force_ns)); }
+        XMLNode insert_child_after(pugi::xml_node_type type_, const xml_node& node) { return xml_node::insert_child_after(type_, node); }
+        XMLNode insert_child_before(pugi::xml_node_type type_, const xml_node& node) { return xml_node::insert_child_before(type_, node); }
+        XMLNode insert_child_after(const pugi::char_t* name_, const xml_node& node, bool force_ns = false)
+            { return xml_node::insert_child_after(NAMESPACED_NAME(name_, force_ns), node); }
+        XMLNode insert_child_before(const pugi::char_t* name_, const xml_node& node, bool force_ns = false)
+            { return xml_node::insert_child_before(NAMESPACED_NAME(name_, force_ns), node); }
+        bool remove_child(const pugi::char_t* name_) { return xml_node::remove_child(NAMESPACED_NAME(name_, false)); }
+        bool remove_child(const xml_node& n) { return xml_node::remove_child(n); }
+        XMLNode find_child_by_attribute(const pugi::char_t* name_, const pugi::char_t* attr_name, const pugi::char_t* attr_value) const
+            { return xml_node::find_child_by_attribute(NAMESPACED_NAME(name_, false), attr_name, attr_value); }
+        XMLNode find_child_by_attribute(const pugi::char_t* attr_name, const pugi::char_t* attr_value) const
+            { return xml_node::find_child_by_attribute(attr_name, attr_value); }
+        // DISCLAIMER: unused by OpenXLSX, but theoretically impacted by xml namespaces:
+        // PUGI_IMPL_FN xml_node xml_node::first_element_by_path(const pugi::char_t* path_, pugi::char_t delimiter) const
+        // ===== END: Wrappers for xml_node member functions
+
+        /**
+         * @brief get first node child that matches type
+         * @param type_ the pugi::xml_node_type to match
+         * @return a valid child matching the node type or an empty XMLNode
+         */
+        XMLNode first_child_of_type(pugi::xml_node_type type_ = pugi::node_element) const;
+
+        /**
+         * @brief get last node child that matches type
+         * @param type_ the pugi::xml_node_type to match
+         * @return a valid child matching the node type or an empty XMLNode
+         */
+        XMLNode last_child_of_type(pugi::xml_node_type type_ = pugi::node_element) const;
+
+        /**
+         * @brief count node children that match type
+         * @param type_ the pugi::xml_node_type to match
+         * @return the amount of node children matching type
+         */
+        size_t child_count_of_type(pugi::xml_node_type type_ = pugi::node_element) const;
+
+        /**
+         * @brief get next node sibling that matches type
+         * @param type_ the pugi::xml_node_type to match
+         * @return a valid sibling matching the node type or an empty XMLNode
+         */
+        XMLNode next_sibling_of_type(pugi::xml_node_type type_ = pugi::node_element) const;
+
+        /**
+         * @brief get previous node sibling that matches type
+         * @param type_ the pugi::xml_node_type to match
+         * @return a valid sibling matching the node type or an empty XMLNode
+         */
+        XMLNode previous_sibling_of_type(pugi::xml_node_type type_ = pugi::node_element) const;
+
+        /**
+         * @brief get next node sibling that matches name_ and type
+         * @param name_ the xml_node::name() to match
+         * @param type_ the pugi::xml_node_type to match
+         * @return a valid sibling matching the node type or an empty XMLNode
+         */
+        XMLNode next_sibling_of_type(const pugi::char_t* name_, pugi::xml_node_type type_ = pugi::node_element) const;
+
+        /**
+         * @brief get previous node sibling that matches name_ and type
+         * @param name_ the xml_node::name() to match
+         * @param type_ the pugi::xml_node_type to match
+         * @return a valid sibling matching the node type or an empty XMLNode
+         */
+        XMLNode previous_sibling_of_type(const pugi::char_t* name_, pugi::xml_node_type type_ = pugi::node_element) const;
+
+    private:
+        int  name_begin; // nameBegin holds the position in xml_node::name() where the actual node name begins - 0 for non-namespaced nodes
+                         // for nodes with a namespace: the position following namespace + delimiter colon, e.g. "x:c" -> nameBegin = 2
+    };
+
+    // ===== Custom OpenXLSX_xml_document to override relevant pugi::xml_document member functions with OpenXLSX_xml_node return value
+    class OpenXLSX_xml_document : public pugi::xml_document {
+    public:
+        /**
+         * @brief Default constructor. Constructs a null object.
+         */
+        OpenXLSX_xml_document() : pugi::xml_document() {}
+
+        /**
+         * @brief Inherit all constructors with parameters from pugi::xml_document
+         */
+        template<class base>
+        // explicit OpenXLSX_xml_document(base b) : xml_document(b) // TBD
+        OpenXLSX_xml_document(base b) : pugi::xml_document(b)
+        {}
+
+        // ===== BEGIN: Wrappers for xml_document member functions to ensure OpenXLSX_xml_node return values
+        // ===== CAUTION: this section is incomplete, only implementing those functions actually used by OpenXLSX to date
+        /**
+         * @brief for all functions: invoke the base class function, but with a return type of OpenXLSX_xml_node
+         */
+        XMLNode document_element() const { return pugi::xml_document::document_element(); }
+        // ===== END: Wrappers for xml_document member functions
+    };
+
+}    // namespace OpenXLSX
+#endif    // OPENXLSX_XLXMLPARSER_HPP

package/thirdparty/OpenXLSX/OpenXLSX/headers/XLXmlParserForwardDeclarations.hpp

@@ -0,0 +1,85 @@
+/*
+
+   ____                               ____      ___ ____       ____  ____      ___
+  6MMMMb                              `MM(      )M' `MM'      6MMMMb\`MM(      )M'
+ 8P    Y8                              `MM.     d'   MM      6M'    ` `MM.     d'
+6M      Mb __ ____     ____  ___  __    `MM.   d'    MM      MM        `MM.   d'
+MM      MM `M6MMMMb   6MMMMb `MM 6MMb    `MM. d'     MM      YM.        `MM. d'
+MM      MM  MM'  `Mb 6M'  `Mb MMM9 `Mb    `MMd       MM       YMMMMb     `MMd
+MM      MM  MM    MM MM    MM MM'   MM     dMM.      MM           `Mb     dMM.
+MM      MM  MM    MM MMMMMMMM MM    MM    d'`MM.     MM            MM    d'`MM.
+YM      M9  MM    MM MM       MM    MM   d'  `MM.    MM            MM   d'  `MM.
+ 8b    d8   MM.  ,M9 YM    d9 MM    MM  d'    `MM.   MM    / L    ,M9  d'    `MM.
+  YMMMM9    MMYMMM9   YMMMM9 _MM_  _MM_M(_    _)MM_ _MMMMMMM MYMMMM9 _M(_    _)MM_
+            MM
+            MM
+           _MM_
+
+  Copyright (c) 2018, Kenneth Troldal Balslev
+
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+  - Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+  - Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  - Neither the name of the author nor the
+    names of any contributors may be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+ */
+
+#ifndef OPENXLSX_XLXMLPARSER_FORWARD_DECLARATIONS_HPP
+#define OPENXLSX_XLXMLPARSER_FORWARD_DECLARATIONS_HPP
+
+// disable this line to use original (non-augmented) pugixml - as of 2024-07-29 this is no longer a realistic option
+#define PUGI_AUGMENTED
+
+namespace pugi {
+#   ifdef PUGI_AUGMENTED
+        class xml_attribute;
+#   else
+        class xml_node;
+        class xml_attribute;
+        class xml_document;
+#   endif
+}
+
+namespace OpenXLSX {
+    // ===== Functions to enable/disable support for documents that use XML namespaces for OOXML tags
+    //       Both functions return true on success, false if functionality is not supported (it is supported, so this should not happen)
+    bool enable_xml_namespaces();       // enable support for namespaces (costs performance on documents without such namespaces)
+    bool disable_xml_namespaces();      // disable support for namespaces
+
+    // ===== Using statements to switch between pugixml and augmented pugixml implementation
+#   ifdef PUGI_AUGMENTED
+        // ===== Forward declarations for using statements below
+        class OpenXLSX_xml_node;
+        class OpenXLSX_xml_document;
+
+        using XMLNode      = OpenXLSX_xml_node;
+        using XMLAttribute = pugi::xml_attribute;
+        using XMLDocument  = OpenXLSX_xml_document;
+#   else
+        using XMLNode      = pugi::xml_node;
+        using XMLAttribute = pugi::xml_attribute;
+        using XMLDocument  = pugi::xml_document;
+#   endif
+}    // namespace OpenXLSX
+
+#endif // OPENXLSX_XLXMLPARSER_FORWARD_DECLARATIONS_HPP
+

package/thirdparty/OpenXLSX/OpenXLSX/headers/XLZipArchive.hpp

@@ -0,0 +1,232 @@
+/*
+
+   ____                               ____      ___ ____       ____  ____      ___
+  6MMMMb                              `MM(      )M' `MM'      6MMMMb\`MM(      )M'
+ 8P    Y8                              `MM.     d'   MM      6M'    ` `MM.     d'
+6M      Mb __ ____     ____  ___  __    `MM.   d'    MM      MM        `MM.   d'
+MM      MM `M6MMMMb   6MMMMb `MM 6MMb    `MM. d'     MM      YM.        `MM. d'
+MM      MM  MM'  `Mb 6M'  `Mb MMM9 `Mb    `MMd       MM       YMMMMb     `MMd
+MM      MM  MM    MM MM    MM MM'   MM     dMM.      MM           `Mb     dMM.
+MM      MM  MM    MM MMMMMMMM MM    MM    d'`MM.     MM            MM    d'`MM.
+YM      M9  MM    MM MM       MM    MM   d'  `MM.    MM            MM   d'  `MM.
+ 8b    d8   MM.  ,M9 YM    d9 MM    MM  d'    `MM.   MM    / L    ,M9  d'    `MM.
+  YMMMM9    MMYMMM9   YMMMM9 _MM_  _MM_M(_    _)MM_ _MMMMMMM MYMMMM9 _M(_    _)MM_
+            MM
+            MM
+           _MM_
+
+  Copyright (c) 2018, Kenneth Troldal Balslev
+
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+  - Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+  - Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  - Neither the name of the author nor the
+    names of any contributors may be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+ */
+
+#ifndef OPENXLSX_XLZIPARCHIVE_HPP
+#define OPENXLSX_XLZIPARCHIVE_HPP
+
+#ifdef _MSC_VER    // conditionally enable MSVC specific pragmas to avoid other compilers warning about unknown pragmas
+#   pragma warning(push)
+#   pragma warning(disable : 4251)
+#   pragma warning(disable : 4275)
+#endif // _MSC_VER
+
+// ===== External Includes ===== //
+#include <memory>    // std::shared_ptr
+#include <cstddef>      // size_t
+#include <type_traits>  // std::make_signed_t
+
+// ===== OpenXLSX Includes ===== //
+#include "OpenXLSX-Exports.hpp"
+
+#ifdef USE_LIBZIP
+    namespace LibZip {
+        class ZipArchive;
+    } // namespace LibZip
+    #define XLZipImplementation LibZip::ZipArchive
+#else
+    namespace Zippy
+    {
+        class ZipArchive;
+    }   // namespace Zippy
+    #define XLZipImplementation Zippy::ZipArchive
+#endif
+
+// ===== portable ssize_t definition ===== //
+using ssize_t = std::make_signed_t< std::size_t >;
+
+namespace OpenXLSX
+{
+    /**
+     * @brief provide the user with the name of the zip library in use
+     */
+    OPENXLSX_EXPORT const char *ZipLibraryName();
+
+    /**
+     * @brief provide the user with the version string of the zip library in use
+     */
+    OPENXLSX_EXPORT const char *ZipLibraryVersion();
+
+    /**
+     * @brief
+     */
+    class OPENXLSX_EXPORT XLZipArchive
+    {
+    public:
+        /**
+         * @brief
+         */
+        XLZipArchive();
+
+        /**
+         * @brief
+         * @param other
+         */
+        XLZipArchive(const XLZipArchive& other);
+
+        /**
+         * @brief
+         * @param other
+         */
+        XLZipArchive(XLZipArchive&& other) noexcept;
+
+        /**
+         * @brief
+         */
+        ~XLZipArchive();
+
+        /**
+         * @brief copy assignment shall be disabled until a use case is found
+         * @param other
+         * @return
+         */
+        XLZipArchive& operator=(const XLZipArchive& other) = delete;
+
+        /**
+         * @brief
+         * @param other
+         * @return
+         */
+        XLZipArchive& operator=(XLZipArchive&& other) noexcept;
+
+        /**
+         * @brief check if zippy is in use (or ziplib)
+         * @param
+         * @return true if zippy is used for the zip implementation, otherwise false
+         */
+        bool usesZippy();
+
+        /**
+         * @brief
+         * @return
+         */
+        explicit operator bool() const;
+
+        bool isValid() const;
+
+        /**
+         * @brief
+         * @return
+         */
+        bool isOpen() const;
+
+        /**
+         * @brief
+         * @param fileName
+         */
+        void open(const std::string& fileName);
+
+        /**
+         * @brief
+         */
+        void close();
+
+        /**
+         * @brief make archive updates (from addEntry) available to calls via getEntry
+         */
+        void commitChanges();
+
+        /**
+         * @brief
+         * @param path
+         */
+        void save(const std::string& path = "");
+
+        /**
+         * @brief
+         * @param name
+         * @param data
+         */
+        void addEntry(const std::string& name, const std::string& data);
+
+        /**
+         * @brief like addEntry, but call commitChanges() afterwards
+         * @param name
+         * @param data
+         */
+        void addEntryAndCommit(const std::string& name, const std::string& data);
+
+        /**
+         * @brief
+         * @param entryName
+         */
+        void deleteEntry(const std::string& entryName);
+
+        /**
+         * @brief
+         * @param name
+         * @return
+         */
+        std::string getEntry(const std::string& name) const;
+
+        /**
+         * @brief
+         * @param entryName
+         * @return
+         */
+        bool hasEntry(const std::string& entryName) const;
+
+        /**
+         * @brief get the amount of entries in the archive
+         * @return for libzip: amount of entries in archive, 0 for zippy
+         */
+        ssize_t entryCount() const;
+
+        /**
+         * @brief get the name of an archive entry by its index
+         * @param index the archive entry whose name to fetch
+         * @return for libzip: name of the archive entry (full path), "" for zippy
+         */
+        std::string entryName( int index ) const;
+
+    private:
+        std::shared_ptr<XLZipImplementation> m_archive; /**< */
+    };
+}    // namespace OpenXLSX
+
+#ifdef _MSC_VER    // conditionally enable MSVC specific pragmas to avoid other compilers warning about unknown pragmas
+#   pragma warning(pop)
+#endif // _MSC_VER
+
+#endif    // OPENXLSX_XLZIPARCHIVE_HPP