WIP: hdf5 documentation
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful

This commit is contained in:
Christian Zimmermann 2024-02-02 00:36:14 +01:00
parent eb3055ddca
commit be3f5521e8
8 changed files with 317 additions and 33 deletions

View file

@ -2,10 +2,9 @@
/** /**
@file include/ranges/ranges.h @file include/ranges/ranges.h
@brief ... @brief Ranges main header
Copyright (c) 2024 Christian Zimmermann. All rights reserved.
Copyright (c) 2022 Christian Zimmermann. All rights reserved.
Mail: chizeta@f3l.de Mail: chizeta@f3l.de
**/ **/

View file

@ -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_content_base.cc.h"
#include "h5_type_id.cc.h" #include "h5_type_id.cc.h"

View file

@ -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_content_base.h"
#include "h5_file.h" #include "h5_file.h"

View file

@ -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__ #ifndef __cxz_h5_content_base_h__
#define __cxz_h5_content_base_h__ #define __cxz_h5_content_base_h__
@ -12,49 +22,122 @@ namespace CNORXZ
{ {
// TODO: IO save error handling !!! // TODO: IO save error handling !!!
/** *****
Enum indicating the content type.
Used by ContainerBase derivates to indicate the derived type.
*/
enum class ContentType { enum class ContentType {
ATTR = 1, NONE = 0,
FILE = 2, FILE = 1,
GROUP = 3, GROUP = 2,
DSET = 4, DSET = 3,
TABLE = 5, TABLE = 4,
VALUE = 6,
}; };
/** ****
Abstract base class for handling hdf5 objects.
*/
class ContentBase class ContentBase
{ {
public: 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); ContentBase(const String& _name, const ContentBase* _parent = nullptr);
/** Virtual default destructor. */
virtual ~ContentBase() = default; virtual ~ContentBase() = default;
/** Get the content type.
@return Content type.
*/
virtual ContentType type() const = 0; virtual ContentType type() const = 0;
/** Check if in read-only mode
@return True if read-only else false.
*/
virtual bool ro() const = 0; virtual bool ro() const = 0;
/** Open object.
@return Reference to this object.
*/
virtual ContentBase& open() = 0; virtual ContentBase& open() = 0;
/** Close object.
@return Reference to this object.
*/
virtual ContentBase& close() = 0; virtual ContentBase& close() = 0;
/** Get object path.
@return Absolute hdf5 file internal path of this object.
*/
virtual String path() const = 0; 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; virtual String filename() const = 0;
/** Get object name.
@return The name of this object.
*/
const String& name() const; 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 <typename T> template <typename T>
ContentBase& addAttribute(const String& name, const T& value); 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; 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; bool attributeExists(const String& name) const;
/** Get all attributes of this object.
@return Std map of key-value pairs.
*/
std::map<String,DType> getAttributes() const; std::map<String,DType> getAttributes() const;
/** Get all attributes of this object and all its parent objects, recursively.
@return Std map of key-value pairs.
*/
std::map<String,DType> getRecursiveAttributes() const; // + all parent's attributes std::map<String,DType> getRecursiveAttributes() const; // + all parent's attributes
protected: protected:
String mName; String mName; /**< Name of this object. */
const ContentBase* mParent = nullptr; const ContentBase* mParent = nullptr; /**< Pointer to this object's parent. */
RangePtr mRange; hid_t mId = 0; /**< hdf5 identifier of the hdf5 object handled by this object. */
hid_t mId = 0;
}; };
/** Shortcut for a shared pointer to an abstract content object. */
typedef Sptr<ContentBase> ContentPtr; typedef Sptr<ContentBase> ContentPtr;
} }

View file

@ -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__ #ifndef __cxz_h5_file_h__
#define __cxz_h5_file_h__ #define __cxz_h5_file_h__
@ -10,14 +20,25 @@ namespace CNORXZ
{ {
namespace hdf5 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 class File : public Group
{ {
public: public:
typedef URange<String> RangeT; typedef URange<String> 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); File(const String& fname, bool _ro = true);
/** Destructor. Release all involved hdf5 ids. */
~File(); ~File();
virtual ContentType type() const override final; virtual ContentType type() const override final;

View file

@ -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__ #ifndef __cxz_h5_group_h__
#define __cxz_h5_group_h__ #define __cxz_h5_group_h__
@ -9,11 +19,21 @@ namespace CNORXZ
{ {
namespace hdf5 namespace hdf5
{ {
/** ****
Class to handle hdf5 groups.
*/
class Group : public ContentBase class Group : public ContentBase
{ {
public: 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); Group(const String& gname, const ContentBase* _parent);
/** Destructor. Release all involved hdf5 ids. */
~Group(); ~Group();
virtual ContentType type() const override; virtual ContentType type() const override;
@ -23,43 +43,114 @@ namespace CNORXZ
virtual String path() const override; virtual String path() const override;
virtual String filename() 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; 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<Group> getGroup(const String& name) const; Sptr<Group> 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<Table> getTable(const String& name) const; Sptr<Table> 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<Dataset> getDataset(const String& name) const; Sptr<Dataset> 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 <typename... Ts> template <typename... Ts>
Sptr<STable<Ts...>> getTable(const String& name, Tuple<Ts...> proto); Sptr<STable<Ts...>> getTable(const String& name, Tuple<Ts...> 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 <typename T> template <typename T>
Sptr<SDataset<T>> getDataset(const String& name, T proto); Sptr<SDataset<T>> getDataset(const String& name, T proto);
/** Get objects contained by this group.
@returns MArray of object pointers.
*/
const MArray<ContentPtr>& get() const; const MArray<ContentPtr>& get() const;
/** Add a new group to this group.
@param name Name of the created group.
*/
Group& addGroup(const String& name); 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 <typename... Ts> template <typename... Ts>
Group& addTable(const String& name, const ArrayBase<Tuple<Ts...>>& data, Group& addTable(const String& name, const ArrayBase<Tuple<Ts...>>& data,
const Arr<String,sizeof...(Ts)>& fnames); const Arr<String,sizeof...(Ts)>& fnames);
/** Add a new dataset to this group.
@tparam T Value type.
@param name Name of the created dataset.
@param data Dataset data.
*/
template <typename T> template <typename T>
Group& addDataset(const String& name, const ArrayBase<T>& data); Group& addDataset(const String& name, const ArrayBase<T>& data);
/** Iterate over all group elements (const).
@param F function object to be executed on each group element.
*/
template <class F> template <class F>
decltype(auto) iter(F&& f) const; 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 <class F> template <class F>
decltype(auto) iterRecursive(F&& f) const; decltype(auto) iterRecursive(F&& f) const;
/** Iterate over all group elements.
@param F function object to be executed on each group element.
*/
template <class F> template <class F>
decltype(auto) iter(F&& f); decltype(auto) iter(F&& f);
/** Iterate recursively over all group elements.
@param F function object to be executed on each group element.
*/
template <class F> template <class F>
decltype(auto) iterRecursive(F&& f); decltype(auto) iterRecursive(F&& f);
protected: protected:
MArray<ContentPtr> mCont; /**< Group elements. */
template <typename C, class F> template <typename C, class F>
static void recursion(const C& c, F&& f) static void recursion(const C& c, F&& f)
{ {
@ -72,8 +163,6 @@ namespace CNORXZ
} }
} }
MArray<ContentPtr> mCont;
void mkCont(); void mkCont();
AIndex<ContentPtr> getIndexTo(const String& name) const; AIndex<ContentPtr> getIndexTo(const String& name) const;
BIndex<ContentPtr> getIndexTo(const String& name); BIndex<ContentPtr> getIndexTo(const String& name);

View file

@ -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__ #ifndef __cxz_h5_table_h__
#define __cxz_h5_table_h__ #define __cxz_h5_table_h__
@ -9,13 +19,23 @@ namespace CNORXZ
{ {
namespace hdf5 namespace hdf5
{ {
/** ****
Class to handle hdf5 tables.
*/
class Table : public ContentBase class Table : public ContentBase
{ {
public: public:
typedef std::pair<SizeT,String> FieldID; typedef std::pair<SizeT,String> 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); Table(const String& name, const ContentBase* _parent);
/** Destructor. Release all involved hdf5 ids. */
~Table(); ~Table();
virtual ContentType type() const override final; virtual ContentType type() const override final;
@ -25,17 +45,57 @@ namespace CNORXZ
virtual String path() const override final; virtual String path() const override final;
virtual String filename() const override final; virtual String filename() const override final;
/** Ininitialize table field names.
@param fnames Table field names.
*/
Table& initFieldNames(const Vector<String>& fnames); Table& initFieldNames(const Vector<String>& 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); 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); 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); 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<DType> readRecord(SizeT pos) const; MArray<DType> readRecord(SizeT pos) const;
/** Read table.
@return DType array containing the table data.
*/
MArray<DType> read() const; MArray<DType> read() const;
/** Iterate over table records.
@param F function object to be executed on each table record.
*/
template <class F> template <class F>
decltype(auto) iterRecords(F&& f) const; decltype(auto) iterRecords(F&& f) const;
/** Get fields range.
@return Pointer to the range.
*/
const RangePtr& fields() const; const RangePtr& fields() const;
/** Get records range.
@return Pointer to the range.
*/
const RangePtr& records() const; const RangePtr& records() const;
protected: protected:

View file

@ -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" #include "h5_content_base.h"
@ -19,16 +31,16 @@ namespace CNORXZ
return mParent; return mParent;
} }
RangePtr ContentBase::range() const
{
return mRange;
}
hid_t ContentBase::id() const hid_t ContentBase::id() const
{ {
return mId; return mId;
} }
bool isOpen() const
{
return mId != 0;
}
DType ContentBase::getAttribute(const String& name) const DType ContentBase::getAttribute(const String& name) const
{ {
CXZ_ASSERT(attributeExists(name), "no attribute with name '" << name CXZ_ASSERT(attributeExists(name), "no attribute with name '" << name