Container.hpp

/* Copyright 2017-2025 Fabian Koller and Franz Poeschel, Axel Huebl
 *
 * This file is part of openPMD-api.
 *
 * openPMD-api is free software: you can redistribute it and/or modify
 * it under the terms of of either the GNU General Public License or
 * the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * openPMD-api is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License and the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * and the GNU Lesser General Public License along with openPMD-api.
 * If not, see <http://www.gnu.org/licenses/>.
 */
#pragma once
 
#include "openPMD/Error.hpp"
#include "openPMD/IO/Access.hpp"
#include "openPMD/auxiliary/TypeTraits.hpp"
#include "openPMD/backend/Attributable.hpp"
#include "openPMD/backend/HierarchyVisitor.hpp"
 
#include <initializer_list>
#include <map>
#include <set>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <utility>
 
// expose private and protected members for invasive testing
#ifndef OPENPMD_protected
#define OPENPMD_protected protected:
#endif
 
namespace openPMD
{
namespace traits
{
    template <typename U>
    struct GenerationPolicy
    {
        constexpr static bool is_noop = true;
        template <typename T>
        void operator()(T &)
        {}
    };
} // namespace traits
 
namespace internal
{
    class SeriesData;
    template <typename>
    class EraseStaleEntries;
 
    template <
        typename T,
        typename T_key = std::string,
        typename T_container = std::map<T_key, T>>
    class ContainerData : virtual public AttributableData
    {
    public:
        using InternalContainer = T_container;
 
        InternalContainer m_container;
 
        ContainerData() = default;
 
        ContainerData(ContainerData const &) = delete;
        ContainerData(ContainerData &&) = delete;
 
        ContainerData &operator=(ContainerData const &) = delete;
        ContainerData &operator=(ContainerData &&) = delete;
    };
} // namespace internal
 
template <
    typename T,
    typename T_key = std::string,
    typename T_container = std::map<T_key, T>>
class Container : virtual public Attributable
{
    static_assert(
        std::is_base_of<Attributable, T>::value,
        "Type of container element must be derived from Writable");
 
    friend class Iteration;
    friend class ParticleSpecies;
    friend class ParticlePatches;
    friend class internal::SeriesData;
    friend class Series;
    template <typename>
    friend class internal::EraseStaleEntries;
    friend class StatefulIterator;
 
protected:
    using ContainerData = internal::ContainerData<T, T_key, T_container>;
    using InternalContainer = T_container;
 
    std::shared_ptr<ContainerData> m_containerData;
 
    inline void setData(std::shared_ptr<ContainerData> containerData)
    {
        m_containerData = std::move(containerData);
        Attributable::setData(m_containerData);
    }
 
    inline InternalContainer const &container() const
    {
        return m_containerData->m_container;
    }
 
    inline InternalContainer &container()
    {
        return m_containerData->m_container;
    }
 
public:
    using key_type = typename InternalContainer::key_type;
    using mapped_type = typename InternalContainer::mapped_type;
    using value_type = typename InternalContainer::value_type;
    using size_type = typename InternalContainer::size_type;
    using difference_type = typename InternalContainer::difference_type;
    using allocator_type = typename InternalContainer::allocator_type;
    using reference = typename InternalContainer::reference;
    using const_reference = typename InternalContainer::const_reference;
    using pointer = typename InternalContainer::pointer;
    using const_pointer = typename InternalContainer::const_pointer;
    using iterator = typename InternalContainer::iterator;
    using const_iterator = typename InternalContainer::const_iterator;
    using reverse_iterator = typename InternalContainer::reverse_iterator;
    using const_reverse_iterator =
        typename InternalContainer::const_reverse_iterator;
 
    iterator begin() noexcept;
    const_iterator begin() const noexcept;
    const_iterator cbegin() const noexcept;
 
    iterator end() noexcept;
    const_iterator end() const noexcept;
    const_iterator cend() const noexcept;
 
    reverse_iterator rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
 
    reverse_iterator rend() noexcept;
    const_reverse_iterator rend() const noexcept;
    const_reverse_iterator crend() const noexcept;
 
    bool empty() const noexcept;
 
    size_type size() const noexcept;
 
    void clear();
 
    std::pair<iterator, bool> insert(value_type const &value);
    std::pair<iterator, bool> insert(value_type &&value);
    iterator insert(const_iterator hint, value_type const &value);
    iterator insert(const_iterator hint, value_type &&value);
    template <class InputIt>
    void insert(InputIt first, InputIt last)
    {
        container().insert(first, last);
    }
    void insert(std::initializer_list<value_type> ilist);
 
    void swap(Container &other);
 
    mapped_type &at(key_type const &key);
    mapped_type const &at(key_type const &key) const;
 
    mapped_type &operator[](key_type const &key);
    mapped_type &operator[](key_type &&key);
 
    iterator find(key_type const &key);
    const_iterator find(key_type const &key) const;
 
    size_type count(key_type const &key) const;
 
    bool contains(key_type const &key) const;
 
    size_type erase(key_type const &key);
 
    iterator erase(iterator res);
    // virtual iterator erase(const_iterator first, const_iterator last)
 
    template <class... Args>
    auto emplace(Args &&...args)
        -> decltype(InternalContainer().emplace(std::forward<Args>(args)...))
    {
        return container().emplace(std::forward<Args>(args)...);
    }
 
    template <typename ChildClass>
    void visitHierarchyImpl(HierarchyVisitor &v, bool recursive)
    {
        if (recursive)
        {
            for (auto &p : *this)
            {
                p.second.visitHierarchy(v, recursive);
            }
        }
        v(*static_cast<ChildClass *>(this));
    }
 
    // clang-format off
OPENPMD_protected
    // clang-format on
 
    void clear_unchecked();
 
    virtual void
    flush(std::string const &path, internal::FlushParams const &flushParams);
 
    Container();
 
    Container(NoInit);
 
public:
    /*
     * Need to define these manually due to the virtual inheritance from
     * Attributable.
     * Otherwise, they would only run from the most derived class
     * if explicitly called.
     * If not defining these, a user could destroy copy/move constructors/
     * assignment operators by deriving from any class that has a virtual
     * Attributable somewhere.
     * Care must be taken in move constructors/assignment operators to not move
     * multiple times (which could happen in diamond inheritance situations).
     */
 
    Container(Container const &other);
 
    Container(Container &&other) noexcept;
 
    Container &operator=(Container const &other);
 
    Container &operator=(Container &&other) noexcept;
};
 
namespace internal
{
    template <typename Container_t>
    class EraseStaleEntries
    {
        static_assert(
            std::is_same_v<Container_t, std::remove_reference_t<Container_t>>);
        using key_type = typename Container_t::key_type;
        using mapped_type = typename Container_t::mapped_type;
        std::set<key_type> m_accessedKeys;
        /*
         * Note: Putting a copy here leads to weird bugs due to destructors
         * being called too eagerly upon destruction.
         * Should be avoidable by extending the frontend redesign to the
         * Container class template
         * (https://github.com/openPMD/openPMD-api/pull/886)
         */
        Container_t &m_originalContainer;
 
    public:
        explicit EraseStaleEntries(Container_t &container_in);
 
        EraseStaleEntries(EraseStaleEntries &&) = delete;
        EraseStaleEntries &operator=(EraseStaleEntries &&) = delete;
 
        mapped_type &operator[](typename Container_t::key_type const &k);
 
        mapped_type &at(typename Container_t::key_type const &k);
 
        void forget(typename Container_t::key_type const &k);
 
        ~EraseStaleEntries();
    };
} // namespace internal
} // namespace openPMD