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
@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
**/

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_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_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__
#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 <typename T>
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<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
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<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__
#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<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);
/** Destructor. Release all involved hdf5 ids. */
~File();
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__
#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<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;
/** 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;
/** 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>
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>
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;
/** 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 <typename... Ts>
Group& addTable(const String& name, const ArrayBase<Tuple<Ts...>>& data,
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>
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>
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>
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>
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>
decltype(auto) iterRecursive(F&& f);
protected:
MArray<ContentPtr> mCont; /**< Group elements. */
template <typename C, class F>
static void recursion(const C& c, F&& f)
{
@ -72,8 +163,6 @@ namespace CNORXZ
}
}
MArray<ContentPtr> mCont;
void mkCont();
AIndex<ContentPtr> getIndexTo(const String& name) const;
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__
#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<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);
/** 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<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);
/** 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<DType> readRecord(SizeT pos) const;
/** Read table.
@return DType array containing the table data.
*/
MArray<DType> read() const;
/** Iterate over table records.
@param F function object to be executed on each table record.
*/
template <class F>
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:

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"
@ -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