diff --git a/src/include/ranges/ranges.h b/src/include/ranges/ranges.h index 5cff132..ac41e2e 100644 --- a/src/include/ranges/ranges.h +++ b/src/include/ranges/ranges.h @@ -2,10 +2,9 @@ /** @file include/ranges/ranges.h - @brief ... + @brief Ranges main header - - Copyright (c) 2022 Christian Zimmermann. All rights reserved. + Copyright (c) 2024 Christian Zimmermann. All rights reserved. Mail: chizeta@f3l.de **/ diff --git a/src/opt/hdf5/include/cnorxz_hdf5.cc.h b/src/opt/hdf5/include/cnorxz_hdf5.cc.h index 0003c9d..0bfac44 100644 --- a/src/opt/hdf5/include/cnorxz_hdf5.cc.h +++ b/src/opt/hdf5/include/cnorxz_hdf5.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/hdf5/include/cnorxz_hdf5.cc.h + @brief CNORXZ HDF5 template sources header + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #include "h5_content_base.cc.h" #include "h5_type_id.cc.h" diff --git a/src/opt/hdf5/include/cnorxz_hdf5.h b/src/opt/hdf5/include/cnorxz_hdf5.h index b68d3f0..0d93562 100644 --- a/src/opt/hdf5/include/cnorxz_hdf5.h +++ b/src/opt/hdf5/include/cnorxz_hdf5.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/hdf5/include/cnorxz_hdf5.h + @brief CNORXZ HDF5 main header + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #include "h5_content_base.h" #include "h5_file.h" diff --git a/src/opt/hdf5/include/h5_content_base.h b/src/opt/hdf5/include/h5_content_base.h index bdf346a..7a4dc03 100644 --- a/src/opt/hdf5/include/h5_content_base.h +++ b/src/opt/hdf5/include/h5_content_base.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/hdf5/include/h5_content_base.h + @brief Abstract content base class declaration + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_h5_content_base_h__ #define __cxz_h5_content_base_h__ @@ -11,50 +21,123 @@ namespace CNORXZ namespace hdf5 { // TODO: IO save error handling !!! - + + /** ***** + Enum indicating the content type. + Used by ContainerBase derivates to indicate the derived type. + */ enum class ContentType { - ATTR = 1, - FILE = 2, - GROUP = 3, - DSET = 4, - TABLE = 5, - VALUE = 6, + NONE = 0, + FILE = 1, + GROUP = 2, + DSET = 3, + TABLE = 4, }; - + + /** **** + Abstract base class for handling hdf5 objects. + */ class ContentBase { public: - DEFAULT_MEMBERS(ContentBase); + DEFAULT_MEMBERS(ContentBase); /**< Default constructors and assignments. */ + + /** Construct the class. + @param _name Content name. + @param _parent Parent content object. Leave null for the root object. + */ ContentBase(const String& _name, const ContentBase* _parent = nullptr); + + /** Virtual default destructor. */ virtual ~ContentBase() = default; + /** Get the content type. + @return Content type. + */ virtual ContentType type() const = 0; + + /** Check if in read-only mode + @return True if read-only else false. + */ virtual bool ro() const = 0; + + /** Open object. + @return Reference to this object. + */ virtual ContentBase& open() = 0; + + /** Close object. + @return Reference to this object. + */ virtual ContentBase& close() = 0; + + /** Get object path. + @return Absolute hdf5 file internal path of this object. + */ virtual String path() const = 0; + + /** Get the file name. + @return Name of the hdf5 file this object is stored in. + */ virtual String filename() const = 0; + /** Get object name. + @return The name of this object. + */ const String& name() const; - const ContentBase* parent() const; - RangePtr range() const; - hid_t id() const; - inline bool isOpen() const { return mId != 0; } + /** Get parent object. + @return Pointer to the parent of this object. + */ + const ContentBase* parent() const; + + /** Get object id. + @return hdf5 id of the h5 object maintained by this object. + */ + hid_t id() const; + + /** Check if object is open, i.e. if there is a valid hdf5 id. + @return True if object is open else false. + */ + bool isOpen() const; + + /** Add attribute to this object. + @tparam T Attribute value type. + @param name Attribute name. + @param value Attribute value. + */ template ContentBase& addAttribute(const String& name, const T& value); + + /** Get an attribute of this object. + @param name Attribute name. + @return The attribute value as DType. + */ DType getAttribute(const String& name) const; + + /** Check if attribute of given name exists in this object. + @param name Attribute name. + @return True if attribute exists else false. + */ bool attributeExists(const String& name) const; + + /** Get all attributes of this object. + @return Std map of key-value pairs. + */ std::map getAttributes() const; + + /** Get all attributes of this object and all its parent objects, recursively. + @return Std map of key-value pairs. + */ std::map getRecursiveAttributes() const; // + all parent's attributes protected: - String mName; - const ContentBase* mParent = nullptr; - RangePtr mRange; - hid_t mId = 0; + String mName; /**< Name of this object. */ + const ContentBase* mParent = nullptr; /**< Pointer to this object's parent. */ + hid_t mId = 0; /**< hdf5 identifier of the hdf5 object handled by this object. */ }; + /** Shortcut for a shared pointer to an abstract content object. */ typedef Sptr ContentPtr; } diff --git a/src/opt/hdf5/include/h5_file.h b/src/opt/hdf5/include/h5_file.h index 79dfaf5..d6157cc 100644 --- a/src/opt/hdf5/include/h5_file.h +++ b/src/opt/hdf5/include/h5_file.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/hdf5/include/h5_file.h + @brief Group declaration. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_h5_file_h__ #define __cxz_h5_file_h__ @@ -10,14 +20,25 @@ namespace CNORXZ { namespace hdf5 { - // maybe introduce abstraction layer between as base for File and Group + /** **** + Class to handle hdf5 file objects. + Objects of this type usually serve as root object + so they don't have any parent. + */ class File : public Group { public: typedef URange RangeT; - DEFAULT_MEMBERS(File); + DEFAULT_MEMBERS(File); /**< Default constructors and assignments. */ + + /** Construct the class. + @param _name Path to the hdf5 file to be handled. + @param _ro Open in read-only mode if true, otherwise have write access. + */ File(const String& fname, bool _ro = true); + + /** Destructor. Release all involved hdf5 ids. */ ~File(); virtual ContentType type() const override final; diff --git a/src/opt/hdf5/include/h5_group.h b/src/opt/hdf5/include/h5_group.h index 986d04a..6b85f89 100644 --- a/src/opt/hdf5/include/h5_group.h +++ b/src/opt/hdf5/include/h5_group.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/hdf5/include/h5_group.h + @brief Group declaration. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_h5_group_h__ #define __cxz_h5_group_h__ @@ -9,11 +19,21 @@ namespace CNORXZ { namespace hdf5 { + /** **** + Class to handle hdf5 groups. + */ class Group : public ContentBase { public: - DEFAULT_MEMBERS(Group); + DEFAULT_MEMBERS(Group); /**< Default constructors and assignments. */ + + /** Construct the class. + @param _name Group name. + @param _parent Parent content object. + */ Group(const String& gname, const ContentBase* _parent); + + /** Destructor. Release all involved hdf5 ids. */ ~Group(); virtual ContentType type() const override; @@ -23,43 +43,114 @@ namespace CNORXZ virtual String path() const override; virtual String filename() const override; - virtual Int exists() const; + /** Check if group exists in the parent object. + @return 1 if group exists, 0 if not, -1 if an error occured. + */ + virtual Int exists() const; // TODO: virtual function of base class + /** Get object contained by this group. + @param name Object name. + @return Pointer to the object. + */ const ContentPtr& get(const String& name) const; + + /** Get object contained by this group as group. + Checks if the object is a group. + @param name Group name. + @return Pointer to the group. + */ Sptr getGroup(const String& name) const; + + /** Get object contained by this group as table. + Checks if the object is a table. + @param name Table name. + @return Pointer to the table. + */ Sptr getTable(const String& name) const; + + /** Get object contained by this group as dataset. + Checks if the object is a table. + @param name Dataset name. + @return Pointer to the dataset. + */ Sptr getDataset(const String& name) const; + /** Get object contained by this group as table for given value type. + Checks if the object is a table. + @tparam Ts Table entry types. + @param name Table name. + @param proto Empty prototype (template argument resolution). + @return Pointer to the table. + */ template Sptr> getTable(const String& name, Tuple proto); + /** Get object contained by this group as dataset for given value type. + Checks if the object is a dataset. + @tparam T Dataset value type. + @param name Dataset name. + @param proto Empty prototype (template argument resolution). + @return Pointer to the dataset. + */ template Sptr> getDataset(const String& name, T proto); + /** Get objects contained by this group. + @returns MArray of object pointers. + */ const MArray& get() const; + + /** Add a new group to this group. + @param name Name of the created group. + */ Group& addGroup(const String& name); + /** Add a new table to this group. + @tparam Ts Table element types. + @param name Name of the created table. + @param data Table data. + @param fnames Table field names. + */ template Group& addTable(const String& name, const ArrayBase>& data, const Arr& fnames); + /** Add a new dataset to this group. + @tparam T Value type. + @param name Name of the created dataset. + @param data Dataset data. + */ template Group& addDataset(const String& name, const ArrayBase& data); + /** Iterate over all group elements (const). + @param F function object to be executed on each group element. + */ template decltype(auto) iter(F&& f) const; + /** Iterate recursively over all group elements (const). + @param F function object to be executed on each group element. + */ template decltype(auto) iterRecursive(F&& f) const; + /** Iterate over all group elements. + @param F function object to be executed on each group element. + */ template decltype(auto) iter(F&& f); + /** Iterate recursively over all group elements. + @param F function object to be executed on each group element. + */ template decltype(auto) iterRecursive(F&& f); protected: + MArray mCont; /**< Group elements. */ + template static void recursion(const C& c, F&& f) { @@ -72,8 +163,6 @@ namespace CNORXZ } } - MArray mCont; - void mkCont(); AIndex getIndexTo(const String& name) const; BIndex getIndexTo(const String& name); diff --git a/src/opt/hdf5/include/h5_table.h b/src/opt/hdf5/include/h5_table.h index c8fa306..6cf82b1 100644 --- a/src/opt/hdf5/include/h5_table.h +++ b/src/opt/hdf5/include/h5_table.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/hdf5/include/h5_table.h + @brief Table declaration. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_h5_table_h__ #define __cxz_h5_table_h__ @@ -9,13 +19,23 @@ namespace CNORXZ { namespace hdf5 { + /** **** + Class to handle hdf5 tables. + */ class Table : public ContentBase { public: typedef std::pair FieldID; - DEFAULT_MEMBERS(Table); + DEFAULT_MEMBERS(Table); /**< Default constructors and assignments. */ + + /** Construct the class. + @param _name Table name. + @param _parent Parent content object. + */ Table(const String& name, const ContentBase* _parent); + + /** Destructor. Release all involved hdf5 ids. */ ~Table(); virtual ContentType type() const override final; @@ -25,17 +45,57 @@ namespace CNORXZ virtual String path() const override final; virtual String filename() const override final; + /** Ininitialize table field names. + @param fnames Table field names. + */ Table& initFieldNames(const Vector& fnames); + + /** Initialize the table. + @param n Number of records (rows). + @param data Table data. + @param dsize Record type size. + @param chunk_size Chunk size. + */ Table& initTable(SizeT n, const void* data, SizeT dsize, SizeT chunk_size); + + /** Append records to the table. + @param n Number of records to append. + @param data Records data. + */ Table& appendRecords(SizeT n, const void* data); + + /** Read records. + @param pos Number of first record to read. + @param n Number of records to read. + @param data Target pointer. + */ Table& readRecords(SizeT pos, SizeT n, char* data); + + /** Read record. + @param pos Number of the record to be read. + @return DType array with containing the record data. + */ MArray readRecord(SizeT pos) const; + + /** Read table. + @return DType array containing the table data. + */ MArray read() const; + /** Iterate over table records. + @param F function object to be executed on each table record. + */ template decltype(auto) iterRecords(F&& f) const; - + + /** Get fields range. + @return Pointer to the range. + */ const RangePtr& fields() const; + + /** Get records range. + @return Pointer to the range. + */ const RangePtr& records() const; protected: diff --git a/src/opt/hdf5/lib/h5_content_base.cc b/src/opt/hdf5/lib/h5_content_base.cc index ce338a6..8a7a1b3 100644 --- a/src/opt/hdf5/lib/h5_content_base.cc +++ b/src/opt/hdf5/lib/h5_content_base.cc @@ -1,3 +1,15 @@ +// -*- C++ -*- +/** + + @file opt/hdf5/lib/h5_content_base.cc + @brief Content base member function implementation. + + Implementation of all non-virtual member functions of ContentBase. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #include "h5_content_base.h" @@ -19,16 +31,16 @@ namespace CNORXZ return mParent; } - RangePtr ContentBase::range() const - { - return mRange; - } - hid_t ContentBase::id() const { return mId; } + bool isOpen() const + { + return mId != 0; + } + DType ContentBase::getAttribute(const String& name) const { CXZ_ASSERT(attributeExists(name), "no attribute with name '" << name