hdf5: virtual function exists() in ContentBase + hdf5 header documentation

src/include/base/types.h

@@ -6,7 +6,7 @@
 
    This file contains the declaration of all library types
 
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -28,9 +28,9 @@
 
 namespace CNORXZ
 {
-    /**********************
-     *   standard types   *
-     **********************/
+    /*====================+
+     |   standard types   |
+     =====================*/
 
     typedef std::intptr_t PtrId;
     typedef int32_t Int;
@@ -80,9 +80,9 @@ namespace CNORXZ
     template <SizeT N>
     using CSizeT = std::integral_constant<SizeT,N>;
     
-    /*********************
-     *   library types   *
-     *********************/
+    /*===================+
+     |   library types   |
+     +===================*/
 
     /***
 	Naming Prefixes:
@@ -302,9 +302,9 @@ namespace CNORXZ
     template <class CXpr>
     class Contraction;
     
-    /*********************
-     *   derived types   *
-     *********************/
+    /*===================+
+     |   derived types   |
+     +===================*/
     
     template <typename T>
     using Vector = std::vector<T,Allocator<T>>;

src/opt/hdf5/include/h5_content_base.cc.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_content_base.cc.h
+   @brief Implementation of template member functions of ContentBase
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_content_base_cc_h__
 #define __cxz_h5_content_base_cc_h__

src/opt/hdf5/include/h5_content_base.h

@@ -81,6 +81,11 @@ namespace CNORXZ
 	     */
 	    virtual String filename() const = 0;
 
+	    /** Check if group exists in the parent object.
+		@return True if object exists, else false.
+	     */
+	    virtual bool exists() const = 0;
+
 	    /** Get object name.
 		@return The name of this object.
 	     */

src/opt/hdf5/include/h5_dataset.cc.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_dataset.cc.h
+   @brief Implementation of template member functions of Dataset and SDataset.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_dataset_cc_h__
 #define __cxz_h5_dataset_cc_h__

src/opt/hdf5/include/h5_dataset.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_dataset.h
+   @brief Dataset declaration.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_dataset_h__
 #define __cxz_h5_dataset_h__
@@ -9,11 +19,21 @@ namespace CNORXZ
 {
     namespace hdf5
     {
+	/** ****
+	    Class to handle hdf5 datasets.
+	 */
 	class Dataset : public ContentBase
 	{
 	public:
-	    DEFAULT_MEMBERS(Dataset);
+	    DEFAULT_MEMBERS(Dataset); /**< Default constructors and assignments. */
+
+	    /** Construct the class.
+		@param _name Dataset name.
+		@param _parent Parent content object.
+	     */
 	    Dataset(const String& name, const ContentBase* _parent);
+
+	    /** Destructor. Release all involved hdf5 ids. */
 	    ~Dataset();
 
 	    virtual ContentType type() const override final;
@@ -22,32 +42,59 @@ namespace CNORXZ
 	    virtual Dataset& close() override final;
 	    virtual String path() const override final;
 	    virtual String filename() const override final;
+	    virtual bool exists() const override final;
 
-	    bool exists() const;
-
+	    /** Initalize the dataset.
+		@param dataRange A potentially multi-dimensional range characterizing the dataset.
+		@param type Data type id.
+	     */
 	    Dataset& init(const RangePtr& dataRange, hid_t type);
 
+	    /** Initalize the dataset.
+		@param data Array containing the dataset.
+	    */
 	    template <typename T>
 	    Dataset& init(const ArrayBase<T>& data);
 
+	    /** Get the data range.
+		@return Pointer to the range.
+	     */
 	    const RangePtr& dataRange() const;
 	    
 	protected:
-	    RangePtr mDataRange;
-	    hid_t mType;
-	    hid_t mFilespace;
+	    RangePtr mDataRange; /**< The data range. */
+	    hid_t mType; /**< The data type identifier. */
+	    hid_t mFilespace; /**< The hdf5 file space identifier. */
 	    
 	};
 
+	/** ****
+	    Class to handle hdf5 datasets, the value type is known at compile time.
+	    @tparam T Dataset value type.
+	 */
 	template <typename T>
 	class SDataset : public Dataset
 	{
 	public:
-	    DEFAULT_MEMBERS(SDataset);
+	    DEFAULT_MEMBERS(SDataset); /**< Default constructors and assignments. */
+
+	    /** Construct the class.
+		@param _name Dataset name.
+		@param _parent Parent content object.
+	     */
 	    SDataset(const String& name, const ContentBase* _parent);
 
+	    /** Read the dataset.
+		@return Array containing the dataset values.
+	     */
 	    MArray<T> read() const;
 
+	    /** Read a given subset of the dataset.
+		The subset needs to be hypercubic.
+		@param beg Index indicating the begin edge of the hypercube.
+		@param end Index indicating the end edge of the hypercube (inclusive).
+		@return Array containing the dataset values.
+	     */
 	    template <class I, typename M>
 	    MArray<T> read(const IndexInterface<I,M>& beg, const IndexInterface<I,M>& end) const;
 

src/opt/hdf5/include/h5_file.h

@@ -47,8 +47,12 @@ namespace CNORXZ
 	    virtual File& close() override final;
 	    virtual String path() const override final;
 	    virtual String filename() const override final;
+	    virtual bool exists() const override final;
 
-	    virtual Int exists() const override final;
+	    /** Check if handled file is in hdf5 format.
+		@return True if file is in hdf5 format, else false.
+	     */
+	    bool ishdf5() const;
 
 	private:
 	    bool mRo = true;

src/opt/hdf5/include/h5_group.cc.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_group.cc.h
+   @brief Implementation of template member functions of Group.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_group_cc_h__
 #define __cxz_h5_group_cc_h__
@@ -9,6 +19,26 @@ namespace CNORXZ
 {
     namespace hdf5
     {
+	template <SizeT I, typename... Ts>
+	constexpr const auto& tget(const Tuple<Ts...>& t)
+	{
+	    return std::get<sizeof...(Ts)-I-1>(t);
+	}
+
+	template <SizeT I, typename... Ts>
+	constexpr auto& tget(Tuple<Ts...>& t)
+	{
+	    return std::get<sizeof...(Ts)-I-1>(t);
+	}
+
+	template <SizeT N, typename... Ts>
+	SizeT getTupleOffset(const Tuple<Ts...>& t, CSizeT<N> i)
+	{
+	    const PtrId beg = reinterpret_cast<PtrId>(&t);
+	    const PtrId pos = reinterpret_cast<PtrId>(&tget<i>(t));
+	    return pos - beg;
+	}
+
 	template <typename... Ts>
 	Sptr<STable<Ts...>> Group::getTable(const String& name, Tuple<Ts...> proto)
 	{

src/opt/hdf5/include/h5_group.h

@@ -42,11 +42,7 @@ namespace CNORXZ
 	    virtual Group& close() override;
 	    virtual String path() const override;
 	    virtual String filename() const override;
-
-	    /** 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
+	    virtual bool exists() const override;
 
 	    /** Get object contained by this group.
 		@param name Object name.

src/opt/hdf5/include/h5_table.cc.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_table.cc.h
+   @brief Implementation of template member functions of Table and STable.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_table_cc_h__
 #define __cxz_h5_table_cc_h__

src/opt/hdf5/include/h5_table.h

@@ -44,6 +44,7 @@ namespace CNORXZ
 	    virtual Table& close() override final;
 	    virtual String path() const override final;
 	    virtual String filename() const override final;
+	    virtual bool exists() const override final;
 
 	    /** Ininitialize table field names.
 		@param fnames Table field names.

src/opt/hdf5/include/h5_type_id.cc.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_type_id.h
+   @brief TypeId template implementation.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_type_id_cc_h__
 #define __cxz_h5_type_id_cc_h__
@@ -8,37 +18,9 @@ namespace CNORXZ
 {
     namespace hdf5
     {
-	template <typename... Ts>
-	decltype(auto) reverseTuple(const Tuple<Ts...>& t)
-	{
-	    return iter<0,sizeof...(Ts)>
-		( [&](auto i) { return tget<i>(t); },
-		  [](const auto&... e) { return std::make_tuple(e...); } );
-	}
-
-	template <SizeT I, typename... Ts>
-	constexpr const auto& tget(const Tuple<Ts...>& t)
-	{
-	    return std::get<sizeof...(Ts)-I-1>(t);
-	}
-
-	template <SizeT I, typename... Ts>
-	constexpr auto& tget(Tuple<Ts...>& t)
-	{
-	    return std::get<sizeof...(Ts)-I-1>(t);
-	}
-
-	template <SizeT N, typename... Ts>
-	SizeT getTupleOffset(const Tuple<Ts...>& t, CSizeT<N> i)
-	{
-	    const PtrId beg = reinterpret_cast<PtrId>(&t);
-	    const PtrId pos = reinterpret_cast<PtrId>(&tget<i>(t));
-	    return pos - beg;
-	}
-
-	/**************
-	 *   TypeId   *
-	 **************/
+	/*============+
+	 |   TypeId   |
+	 +============*/
 
 	template <typename T>
 	inline hid_t TypeId<T>::get()
@@ -68,9 +50,9 @@ namespace CNORXZ
 	    return arrtype;
 	}
 
-	/*****************
-	 *   getTypeId   *
-	 *****************/
+	/*===============+
+	 |   getTypeId   |
+	 +===============*/
 
 	template <typename T>
 	hid_t getTypeId(T x)

src/opt/hdf5/include/h5_type_id.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_type_id.h
+   @brief TypeId template declaration.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_type_id_h__
 #define __cxz_h5_type_id_h__
@@ -8,43 +18,57 @@ namespace CNORXZ
 {
     namespace hdf5
     {
-	template <typename... Ts>
-	decltype(auto) reverseTuple(const Tuple<Ts...>& t);
-
-	template <typename... Ts>
-	using RTuple = typename std::remove_reference<decltype(reverseTuple(Tuple<Ts...>()))>::type;
-	template <SizeT I, typename... Ts>
-	constexpr const auto& tget(const Tuple<Ts...>& t);
-	
-	template <SizeT I, typename... Ts>
-	constexpr auto& tget(Tuple<Ts...>& t);
-	
-	template <SizeT N, typename... Ts>
-	SizeT getTupleOffset(const Tuple<Ts...>& t, CSizeT<N> i);
-
-	/**************
-	 *   TypeId   *
-	 **************/
- 
+	/** ****
+	    Get a valid hdf5 id for a given type.
+	    Return 0 if not implemented.
+	    @tparam T The type.
+	 */
 	template <typename T>
-	struct TypeId { static inline hid_t get(); };
+	struct TypeId
+	{
+	    /** Get the type id. */
+	    static inline hid_t get();
+	};
 
+	/** Specialization of TypeId for SizeT. */
 	template <>
-	struct TypeId<SizeT> { static inline hid_t get(); };
+	struct TypeId<SizeT>
+	{
+	    /** Get the type id for SizeT. */
+	    static inline hid_t get();
+	};
 	
+	/** Specialization of TypeId for Int. */
 	template <>
-	struct TypeId<Int> { static inline hid_t get(); };
+	struct TypeId<Int>
+	{
+	    /** Get the type id for Int. */
+	    static inline hid_t get();
+	};
 
+	/** Specialization of TypeId for Double. */
 	template <>
-	struct TypeId<Double> { static inline hid_t get(); };
+	struct TypeId<Double>
+	{
+	    /** Get the type id for Double. */
+	    static inline hid_t get();
+	};
 
+	/** Specialization of TypeId for an array
+	    @tparam T Element type.
+	    @tparam N Array size.
+	 */
 	template <typename T, SizeT N>
-	struct TypeId<Arr<T,N>> { static inline hid_t get(); };
-
-	/*****************
-	 *   getTypeId   *
-	 *****************/
+	struct TypeId<Arr<T,N>>
+	{
+	    /** Get the type id for the given array. */
+	    static inline hid_t get();
+	};
 
+	/** Wrapper function for TypeId::get()
+	    @param Variable of given type.
+	    @return A type id of the input variable's type.
+	 */
 	template <typename T>
 	hid_t getTypeId(T x);
     }

src/opt/hdf5/include/h5_types.h

@@ -1,3 +1,15 @@
+// -*- C++ -*-
+/**
+   
+   @file opt/hdf5/include/types.h
+   @brief Declaration of hdf5 related library types
+
+   This file contains the declaration of all hdf5 related library types
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+   
+**/
 
 #ifndef __h5_types_h__
 #define __h5_types_h__

src/opt/hdf5/lib/h5_file.cc

@@ -33,7 +33,7 @@ namespace CNORXZ
 	    }
 	    Int ex = this->exists();
 	    const String fn = this->filename();
-	    CXZ_ASSERT( ex != 2, "tried to open non-h5 file '" << fn << "'" );
+	    CXZ_ASSERT( ishdf5(), "tried to open non-h5 file '" << fn << "'" );
 	    if(mRo){
 		CXZ_ASSERT( ex == 1, "could not open file as read-only: '"
 			    << fn << "' does not exist'");
@@ -79,21 +79,25 @@ namespace CNORXZ
 	    return name();
 	}
 
-	Int File::exists() const
+	bool File::exists() const
 	{
-	    Int ex = 0;
+	    bool ex = false;
 	    std::ifstream fs(this->filename().c_str(), std::ios_base::binary);
 	    if(fs.good()){
-		ex = 1; // file exists
+		ex = true; // file exists
 	    }
 	    fs.close();
-	    if(ex != 0){
-		if(H5Fis_hdf5(this->filename().c_str()) <= 0){
-		    ex = 2; // file not in h5 format
-		}
-	    }
 	    return ex;
 	}
 
+	bool File::ishdf5() const
+	{
+	    if(exists()){
+		if(H5Fis_hdf5(this->filename().c_str()) <= 0){
+		    return false;
+		}
+	    }
+	    return true; // a non-existing file can be created in hdf5 format
+	}
     }
 }

src/opt/hdf5/lib/h5_group.cc

@@ -69,9 +69,9 @@ namespace CNORXZ
 	    return String();
 	}
 	
-	Int Group::exists() const
+	bool Group::exists() const
 	{
-	    return H5Lexists(mParent->id(), mName.c_str(), H5P_DEFAULT) != 0 ? 1 : 0;
+	    return H5Lexists(mParent->id(), mName.c_str(), H5P_DEFAULT) != 0;
 	}
 
 	const ContentPtr& Group::get(const String& name) const

src/opt/hdf5/lib/h5_table.cc

@@ -9,7 +9,7 @@ namespace CNORXZ
 	Table::Table(const String& name, const ContentBase* _parent) :
 	    ContentBase(name, _parent)
 	{
-	    if(H5Lexists(mParent->id(), mName.c_str(), H5P_DEFAULT)){
+	    if(exists()){
 		hsize_t nfields = 0;
 		hsize_t nrecords = 0;
 		H5TBget_table_info(mParent->id(), mName.c_str(), &nfields, &nrecords);
@@ -90,6 +90,13 @@ namespace CNORXZ
 	    return mParent->filename();
 	}
 
+	bool Table::exists() const
+	{
+	    htri_t x = H5Lexists(mParent->id(), mName.c_str(), H5P_DEFAULT);
+	    VCHECK(x);
+	    return x;
+	}
+	
 	Table& Table::initFieldNames(const Vector<String>& fnames)
 	{
 	    CXZ_ASSERT(mFields == nullptr, "fields already initialized");

src/opt/hdf5/tests/h5_basic_unit_test.cc

@@ -58,7 +58,7 @@ namespace
 	    CIndex j(fs);
 	    for(i = 0; i.lex() != rs->size(); ++i){
 		iter<0,3>( [&](auto jj)
-		{ j = jj; mTabD[i*j] = DType(tget<jj>(v[i.lex()])); }, NoF{} );
+		{ j = jj; mTabD[i*j] = DType(std::get<3-jj-1>(v[i.lex()])); }, NoF{} );
 	    }
 
 	    const SizeT ddim = 5;