Attributable.hpp

/* Copyright 2017-2021 Fabian Koller
 *
 * 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/IO/AbstractIOHandler.hpp"
#include "openPMD/ThrowError.hpp"
#include "openPMD/auxiliary/OutOfRangeMsg.hpp"
#include "openPMD/backend/Attribute.hpp"
#include "openPMD/backend/Writable.hpp"
 
#include <cstddef>
#include <exception>
#include <map>
#include <memory>
#include <string>
#include <type_traits>
#include <vector>
 
// expose private and protected members for invasive testing
#ifndef OPENPMD_protected
#define OPENPMD_protected protected:
#endif
 
namespace openPMD
{
namespace traits
{
    template <typename T>
    struct GenerationPolicy;
} // namespace traits
class AbstractFilePosition;
class Attributable;
class Iteration;
class Series;
 
namespace internal
{
    class AttributableData
    {
        friend class openPMD::Attributable;
 
    public:
        AttributableData();
        AttributableData(AttributableData const &) = delete;
        AttributableData(AttributableData &&) = delete;
        virtual ~AttributableData() = default;
 
        AttributableData &operator=(AttributableData const &) = delete;
        AttributableData &operator=(AttributableData &&) = delete;
 
        using A_MAP = std::map<std::string, Attribute>;
        Writable m_writable;
 
    private:
        A_MAP m_attributes;
    };
 
    template <typename>
    class BaseRecordData;
} // namespace internal
 
class Attributable
{
    // @todo remove unnecessary friend (wew that sounds bitter)
    using A_MAP = std::map<std::string, Attribute>;
    friend Writable *getWritable(Attributable *);
    template <typename T_elem>
    friend class BaseRecord;
    template <typename T_elem>
    friend class BaseRecordInterface;
    template <typename>
    friend class internal::BaseRecordData;
    template <typename T, typename T_key, typename T_container>
    friend class Container;
    template <typename T>
    friend struct traits::GenerationPolicy;
    friend class Iteration;
    friend class Series;
    friend class Writable;
    friend class WriteIterations;
 
protected:
    std::shared_ptr<internal::AttributableData> m_attri{
        new internal::AttributableData()};
 
    // Should not be called publicly, only by implementing classes
    Attributable(std::shared_ptr<internal::AttributableData>);
 
public:
    Attributable();
 
    virtual ~Attributable() = default;
 
    template <typename T>
    bool setAttribute(std::string const &key, T value);
    bool setAttribute(std::string const &key, char const value[]);
    Attribute getAttribute(std::string const &key) const;
 
    bool deleteAttribute(std::string const &key);
 
    std::vector<std::string> attributes() const;
    size_t numAttributes() const;
    bool containsAttribute(std::string const &key) const;
 
    std::string comment() const;
    Attributable &setComment(std::string const &comment);
 
    void seriesFlush(std::string backendConfig = "{}");
 
    struct MyPath
    {
        std::string directory; 
        std::string seriesName; 
        std::string seriesExtension; 
        std::vector<std::string> group;
        Access access;
 
        std::string filePath() const;
    };
 
    MyPath myPath() const;
 
    // clang-format off
OPENPMD_protected
    // clang-format on
 
    Series retrieveSeries() const;
 
    Iteration const &containingIteration() const;
    Iteration &containingIteration();
    void seriesFlush(internal::FlushParams);
 
    void flushAttributes(internal::FlushParams const &);
 
    enum ReadMode
    {
        IgnoreExisting,
        OverrideExisting,
        FullyReread
    };
    void readAttributes(ReadMode);
 
    template <typename T>
    T readFloatingpoint(std::string const &key) const;
    template <typename T>
    std::vector<T> readVectorFloatingpoint(std::string const &key) const;
 
    /* views into the resources held by m_writable
     * purely for convenience so code that uses these does not have to go
     * through m_writable-> */
    AbstractIOHandler *IOHandler()
    {
        return const_cast<AbstractIOHandler *>(
            static_cast<Attributable const *>(this)->IOHandler());
    }
    AbstractIOHandler const *IOHandler() const
    {
        auto &opt = m_attri->m_writable.IOHandler;
        if (!opt || !opt->has_value())
        {
            return nullptr;
        }
        return &*opt->value();
    }
    Writable *&parent()
    {
        return m_attri->m_writable.parent;
    }
    Writable const *parent() const
    {
        return m_attri->m_writable.parent;
    }
    Writable &writable()
    {
        return m_attri->m_writable;
    }
    Writable const &writable() const
    {
        return m_attri->m_writable;
    }
 
    inline void setData(std::shared_ptr<internal::AttributableData> attri)
    {
        m_attri = std::move(attri);
    }
 
    inline internal::AttributableData &get()
    {
        return *m_attri;
    }
    inline internal::AttributableData const &get() const
    {
        return *m_attri;
    }
 
    bool dirty() const
    {
        return writable().dirty;
    }
    bool &dirty()
    {
        return writable().dirty;
    }
    bool written() const
    {
        return writable().written;
    }
    bool &written()
    {
        return writable().written;
    }
 
private:
    virtual void linkHierarchy(Writable &w);
}; // Attributable
 
// note: we explicitly instantiate Attributable::setAttributeImpl for all T in
// Datatype in Attributable.cpp
template <typename T>
inline bool Attributable::setAttribute(std::string const &key, T value)
{
    auto &attri = get();
    if (IOHandler() &&
        IOHandler()->m_seriesStatus == internal::SeriesStatus::Default &&
        Access::READ_ONLY == IOHandler()->m_frontendAccess)
    {
        auxiliary::OutOfRangeMsg const out_of_range_msg(
            "Attribute", "can not be set (read-only).");
        error::throwNoSuchAttribute(out_of_range_msg(key));
    }
 
    dirty() = true;
    auto it = attri.m_attributes.lower_bound(key);
    if (it != attri.m_attributes.end() &&
        !attri.m_attributes.key_comp()(key, it->first))
    {
        // key already exists in map, just replace the value
        it->second = Attribute(std::move(value));
        return true;
    }
    else
    {
        // emplace a new map element for an unknown key
        attri.m_attributes.emplace_hint(
            it, std::make_pair(key, Attribute(std::move(value))));
        return false;
    }
}
 
inline bool
Attributable::setAttribute(std::string const &key, char const value[])
{
    return this->setAttribute(key, std::string(value));
}
 
template <typename T>
inline T Attributable::readFloatingpoint(std::string const &key) const
{
    static_assert(
        std::is_floating_point<T>::value,
        "Type of attribute must be floating point");
 
    return getAttribute(key).get<T>();
}
 
template <typename T>
inline std::vector<T>
Attributable::readVectorFloatingpoint(std::string const &key) const
{
    static_assert(
        std::is_floating_point<T>::value,
        "Type of attribute must be floating point");
 
    return getAttribute(key).get<std::vector<T> >();
}
} // namespace openPMD