more documentation; WIP: mrange doc

src/include/ranges/eindex.h

@@ -5,7 +5,7 @@
    @brief ...
 
 
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -20,7 +20,17 @@
 
 namespace CNORXZ
 {
-    
+    /** *****
+	Extension Index
+
+	Elements accessed through this index in a loop
+	are treated and processed through a single access
+	allowing the usage of vector extensions
+	
+	@tparam MetaT Index meta data type
+	@tparam S Vector size
+	@tparam L Static index label
+     */
     template <typename MetaT, SizeT S, SizeT L>
     class EIndex : public LIndex<SIndex<MetaT,S>,L>
     {
@@ -28,9 +38,15 @@ namespace CNORXZ
 	typedef typename LIndex<SIndex<MetaT,S>,L>::IB IB;
 	typedef typename LIndex<SIndex<MetaT,S>,L>::RangeType RangeType;
 
-	DEFAULT_MEMBERS(EIndex);
+	DEFAULT_MEMBERS(EIndex); /**< default constructors and assignments */
 	EIndex(const Sptr<LIndex<SIndex<MetaT,S>,L>>& i);
 
+	/** @copydoc IndexInterface::ifor()
+
+	    Specialization for EIndex: access all elements
+	    at once, allowing usage of vector extensions
+	    @see EFor
+	 */
 	template <class Xpr, class F>
 	decltype(auto) ifor(const Xpr& xpr, F&& f) const;
 
@@ -38,6 +54,10 @@ namespace CNORXZ
 	Sptr<LIndex<SIndex<MetaT,S>,L>> mLI;
     };
 
+    /** ***
+	EIndex is an index
+	@see is_index
+     */    
     template <typename MetaT, SizeT S, SizeT L>
     struct is_index<EIndex<MetaT,S,L>>
     {
@@ -53,25 +73,52 @@ namespace CNORXZ
     {
 	static constexpr bool value = true;
     };
-    
+
+    /** Make index pack from EIndex and second index of arbitrary type
+     */    
     template <typename MetaT, SizeT S, SizeT L, class I1>
     decltype(auto) operator*(const Sptr<EIndex<MetaT,S,L>>& a, const Sptr<I1>& b);
 
+    /** Create Eindex pointer from LIndex pointer
+     */
     template <typename MetaT, SizeT S, SizeT L>
     decltype(auto) eindexPtr(const Sptr<LIndex<SIndex<MetaT,S>,L>>& i);
 
+    /** Create Eindex pointer from SIndex pointer
+	@tparam L Static index label
+     */
     template <SizeT L, typename MetaT, SizeT S>
     decltype(auto) eindexPtr(const Sptr<SIndex<MetaT,S>>& i);
 
+    /** Create Eindex pointer from LIndex pointer
+	@param l Static index label
+     */
     template <typename MetaT, SizeT S, SizeT L>
     decltype(auto) eindexPtr(const Sptr<SIndex<MetaT,S>>& i, CSizeT<L> l);
 
+    /** Split given index into pack of EIndex and remainder index
+	@param i Index to be split
+	@tparam S Vector size
+	@tparam L1 label of EIndex
+	@tparam L2 label of remainder index
+     */
     template <SizeT S, SizeT L1, SizeT L2, class Index>
     decltype(auto) eplex(const Sptr<Index>& i);
 
+    /** Split given index into pack of EIndex and remainder index
+	@param i Index to be split
+	@param s Vector size
+	@param l label of EIndex
+     */
     template <class Index, SizeT S, SizeT L>
     decltype(auto) eplex(const Sptr<Index>& i, CSizeT<S> s, CSizeT<L> l);
 
+    /** Split given index into pack of EIndex and remainder index
+	@param i Index to be split
+	@param s Vector size
+	@param l1 label of EIndex
+	@param l2 label of remainder index
+     */
     template <class Index, SizeT S, SizeT L1, SizeT L2>
     decltype(auto) eplex(const Sptr<Index>& i, CSizeT<S> s, CSizeT<L1> l1, CSizeT<L2> l2);
 

src/include/ranges/index_format.h

@@ -5,7 +5,7 @@
    @brief ...
 
 
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -18,26 +18,51 @@
 
 namespace CNORXZ
 {
+    /** ****
+	Type trait: Check if format has static size.
+     */
     template <class FormatT> struct is_static_format { CXZ_CVAL_FALSE; };
-    
+
+    /** ****
+	Multi index format of static size.
+	Wrapper of standard array of UPos.
+	@tparam N Format size
+     */
     template <SizeT N>
     class MFormat
     {
     public:
 	typedef Arr<UPos,N> InputType;
 	
-	SP_DEFAULT_MEMBERS(constexpr,MFormat);
+	SP_DEFAULT_MEMBERS(constexpr,MFormat); /**< default constructors and assignments */
+
+	/** Construct MFormat from standard array.
+	    @param b Input array
+	 */
 	explicit constexpr MFormat(const Arr<UPos,N>& b);
 
+	/** Construct MFormat from format of arbitrary type.
+	    The input format size has to match the static size N.
+	    @param f Input format
+	 */
 	template <class FormatT>
 	constexpr MFormat(const FormatT& f);
 
+	/** Get underlying array. */
 	const Arr<UPos,N>& all() const;
+	
+	/** Get format size. */
 	constexpr decltype(auto) size() const;
 	
+	/** Get format element.
+	    @param i CSizeT indicating static element position 
+	 */
 	template <SizeT I>
 	constexpr decltype(auto) get(CSizeT<I> i) const;
 
+	/** Get format element.
+	    @param i CSizeT indicating static element position 
+	 */
 	template <SizeT I>
 	constexpr decltype(auto) operator[](CSizeT<I> i) const;
 
@@ -46,27 +71,58 @@ namespace CNORXZ
 
     };
 
+    /** ****
+	MFormat has static size.
+	@see is_static_format
+     */
     template <SizeT N> struct is_static_format<MFormat<N>> { CXZ_CVAL_TRUE; };
 
+    /** ****
+	Multi index format of static size.
+	Wrapper of standard tuple of position types.
+	@tparam PosT Position types.
+     */
     template <class... PosT>
     class GMFormat
     {
     public:
 	typedef Tuple<PosT...> InputType;
 
-	SP_DEFAULT_MEMBERS(constexpr,GMFormat);
+	SP_DEFAULT_MEMBERS(constexpr,GMFormat); /**< default constructors and assignments */
+
+	/** Construct from tuple.
+	    @param b Input tuple.
+	 */
 	explicit constexpr GMFormat(const Tuple<PosT...>& b);
+
+	/** Construct from tuple (move).
+	    @param b Input tuple.
+	 */
 	explicit constexpr GMFormat(Tuple<PosT...>&& b);
 
+	/** Construct MFormat from format of arbitrary type.
+	    The input format size has to match the number of entries
+	    and the input entries have to be compatible with the position types.
+	    @param f Input format
+	 */
 	template <class FormatT>
 	constexpr GMFormat(const FormatT& f);
 
+	/** Get underlying tuple. */
 	const Tuple<PosT...>& all() const;
+	
+	/** Get format size. */
 	constexpr decltype(auto) size() const;
 
+	/** Get format element.
+	    @param i CSizeT indicating static element position 
+	 */
 	template <SizeT I>
 	constexpr decltype(auto) get(CSizeT<I> i) const;
 
+	/** Get format element.
+	    @param i CSizeT indicating static element position 
+	 */
 	template <SizeT I>
 	constexpr decltype(auto) operator[](CSizeT<I> i) const;
 	
@@ -74,38 +130,76 @@ namespace CNORXZ
 	Tuple<PosT...> mB;
     };
 
+    /** Create GMFormat from position types.
+	@param ps Position types.
+     */
     template <class... PosT>
     constexpr decltype(auto) gmformat(const PosT&... ps);
     
+    /** ****
+	GMFormat has static size.
+	@see is_static_format
+     */
     template <class... PosT> struct is_static_format<GMFormat<PosT...>> { CXZ_CVAL_TRUE; };
 
+    /** ****
+	Multi index format of variable size
+	Wrapper of standard vector of UPos.
+     */
     class YFormat
     {
     public:
 	typedef Vector<UPos> InputType;
 	
-	DEFAULT_MEMBERS(YFormat);
+	DEFAULT_MEMBERS(YFormat); /**< default constructors and assignments */
+
+	/** Construct from vector.
+	    @param b Input vector.
+	 */
 	explicit YFormat(const Vector<UPos>& b);
 
+	/** Construct from format of arbitrary type.
+	    @param f Input format.
+	 */
 	template <class FormatT>
 	YFormat(const FormatT& f);
 
+	/** Get underlying vector. */
 	const Vector<UPos>& all() const;
+
+	/** Get format size. */
 	SizeT size() const;
 
+	/** Get format element.
+	    @param i CSizeT indicating static element position 
+	 */
 	template <SizeT I>
 	const UPos& get(CSizeT<I> i) const;
 	
+	/** Get format element.
+	    @param i CSizeT indicating static element position 
+	 */
 	template <SizeT I>
 	const UPos& operator[](CSizeT<I> i) const;
 
+	/** Get format element.
+	    @param i E element position 
+	 */
 	const UPos& get(SizeT i) const;
+
+	/** Get format element.
+	    @param i E element position 
+	 */
 	const UPos& operator[](SizeT i) const;
 	
     private:
 	Vector<UPos> mB;
     };
 
+    /** Check if format is trivial, i.e. f[i-1] = f[i]*s[i].
+	@param f Vector representing the index format.
+	@param s Vector representing the sub-index maxima.
+     */
     bool formatIsTrivial(const Vector<SizeT>& f, const Vector<SizeT>& s);
 }
 

src/include/ranges/index_mul.h

@@ -2,10 +2,11 @@
 /**
    
    @file include/ranges/index_mul.h
-   @brief ...
+   @brief Index multiplication
 
+   Indices can be multiplied yielding index packs.
 
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -35,30 +36,71 @@ namespace CNORXZ
 				     Isq<Is...> is, Isq<Js...> js);
     };
 
+    /** Combine two indices to a static index 2-pack.
+	@param a First index.
+	@param b Second index.
+	@return Static index 2-pack
+     */
     template <class I1, typename Meta1, class I2, typename Meta2>
     inline decltype(auto) operator*(const IndexInterface<I1,Meta1>& a,
 				    const IndexInterface<I2,Meta2>& b);
 
+    /** Extend static index pack on the l.h.s.
+	@param a Index to be appended.
+	@param b Index pack to be extended.
+	@return Extended pack.
+     */
     template <class I1, typename Meta1, class... Indices>
     inline decltype(auto) operator*(const IndexInterface<I1,Meta1>& a,
 				    const SPack<Indices...>& b);
 
+    /** Extend static index pack on the r.h.s.
+	@param a Index pack to be extended.
+	@param b Index to be appended.
+	@return Extended pack.
+     */
     template <class I2, typename Meta2, class... Indices>
     inline decltype(auto) operator*(const SPack<Indices...>& a,
 				    const IndexInterface<I2,Meta2>& b);
 
+    /** Combine two static index packs
+	@param a First Index pack.
+	@param b Second Index pack.
+	@return New index pack. a is appended on the l.h.s. of b.
+     */
     template <class... Indices1, class... Indices2>
     inline decltype(auto) operator*(const SPack<Indices1...>& a, const SPack<Indices2...>& b);
 
+    /** Extend dynamic index pack on the l.h.s.
+	@param a Index to be appended.
+	@param b Index pack to be extended.
+	@return Extended pack.
+     */
     template <class I1, typename Meta1>
     inline decltype(auto) operator*(const IndexInterface<I1,Meta1>& a, const DPack& b);
 
+    /** Extend dynamic index pack on the r.h.s.
+	@param a Index pack to be extended.
+	@param b Index to be appended.
+	@return Extended pack.
+     */
     template <class I2, typename Meta2>
     inline decltype(auto) operator*(const DPack& a, const IndexInterface<I2,Meta2>& b);
 
+    /** Combine two dynamic index packs
+	@param a First Index pack.
+	@param b Second Index pack.
+	@return New index pack. a is appended on the l.h.s. of b.
+     */
     inline decltype(auto) operator*(const DPack& a, const DPack& b);
 
-    
+    /** Combine two index pointers to an index 2-pack.
+	YIndices and DIndices will be combined into a DPack,
+	otherwise a SPack is returned.
+	@param a First index.
+	@param b Second index.
+	@return Index 2-pack.
+     */
     template <class I1, class I2>
     decltype(auto) iptrMul(const Sptr<I1>& a, const Sptr<I2>& b);
 }

src/include/ranges/index_traits.h

@@ -4,7 +4,7 @@
    @file include/ranges/index_traits.h
    @brief index traits
 
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Copyright (c) 2023 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/

src/include/ranges/index_utils.h

@@ -1,29 +0,0 @@
-// -*- C++ -*-
-/**
-   
-   @file include/ranges/index_utils.h
-   @brief ...
-
-
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
-   Mail: chizeta@f3l.de
-   
-**/
-
-#ifndef __cxz_index_utils_h__
-#define __cxz_index_utils_h__
-
-#include "base/base.h"
-#include "index_base.h"
-
-namespace CNORXZ
-{
-    // automatically set static format if SIndices are used!
-    template <class... Indices>
-    constexpr decltype(auto) autoiPtr(const SPack<Indices...>& pack);
-
-    inline SPtr<YIndex> autoiPtr(const DPack& pack);
-    
-}
-
-#endif

src/include/ranges/lindex.h

@@ -2,10 +2,12 @@
 /**
    
    @file include/ranges/lindex.h
-   @brief ...
+   @brief Statically labeled index.
 
-
+   Static index labels are usefull to resolve extensions and relations to
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   other indices at compile time.
+   
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -20,7 +22,11 @@
 
 namespace CNORXZ
 {
-    // static label to enforce loop unrolling
+    /** ****
+	Statically labeled index.
+	@tparam Index Underlying index.
+	@tparam L Static label.
+     */
     template <class Index, SizeT L>
     class LIndex : public Index
     {
@@ -28,14 +34,25 @@ namespace CNORXZ
 	typedef typename Index::IB IB;
 	typedef typename Index::RangeType RangeType;
 
-	DEFAULT_MEMBERS(LIndex);
+	DEFAULT_MEMBERS(LIndex); /**< Default constructors and assignments. */
+
+	/** Construct from index pointer.
+	    @param i Input index.
+	 */
 	LIndex(const Sptr<Index>& i);
 
+	/** @copydoc IndexInterface::id()
+	    Specialization: Static id equals L.
+	 */
 	IndexId<L> id() const;
 	
+	/** @copydoc IndexInterface::stepSize()
+	    Specialization: stepSize may be static.
+	 */
 	template <SizeT I>
 	decltype(auto) stepSize(const IndexId<I>& id) const;
 
+	/** @copydoc IndexInterface::stepSize() */
 	template <class Xpr, class F>
 	decltype(auto) ifor(const Xpr& xpr, F&& f) const;
 
@@ -43,6 +60,10 @@ namespace CNORXZ
 	Sptr<Index> mI;
     };
 
+    /** ***
+	LIndex is an index
+	@see is_index
+     */    
     template <class Index, SizeT L>
     struct is_index<LIndex<Index,L>>
     {
@@ -59,12 +80,27 @@ namespace CNORXZ
 	static constexpr bool value = index_expression_exists<Index>::value;
     };
 
+    /** Specialize index multiplication for LIndex.
+	@param a Pointer to first index which is a LIndex.
+	@param b Pointer to second index of arbitrary type.
+	@return Resulting index pack.
+     */
     template <class Index, SizeT L, class I1>
     decltype(auto) operator*(const Sptr<LIndex<Index,L>>& a, const Sptr<I1>& b);
 
+    /** Create LIndex from index pointer.
+	@param i Input index.
+	@tparam L Static label.
+	@return Resulting LIndex.
+     */
     template <SizeT L, class Index>
     decltype(auto) lindexPtr(const Sptr<Index>& i);
 
+    /** Create LIndex from index pointer.
+	@param i Input index.
+	@param l CSizeT indicating the static label.
+	@return Resulting LIndex.
+     */
     template <class Index, SizeT L>
     decltype(auto) lindexPtr(const Sptr<Index>& i, CSizeT<L> l);
 }

src/include/ranges/mrange.h

@@ -2,10 +2,15 @@
 /**
    
    @file include/ranges/mrange.h
-   @brief ...
+   @brief MRange, GMIndex and MIndex declaration
 
+   MRange is a multi-range consisting of of a compile-time fixed number of sub-ranges.
 
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   GMIndex and MIndex are multi-index consisting of a compile-time fixed number of sub-indices.
+   The difference between the two index types is that MIndex has a statically trivial format,
+   while GMIndex can have an arbitrary format (MFormat or GMFormat).
+   
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -22,8 +27,13 @@
 
 namespace CNORXZ
 {
-    // template <class FormatT, class... Indices>
+    
-    // -> Format + IndexTuple
+    /** ****
+	Multi-index with fixed number of sub-indices of arbitrary type
+	and arbitrary index format.
+	@tparam FormatT Index format type.
+	@tparam Indices Sub-index types.
+     */
     template <class FormatT, class... Indices>
     class GMIndex : public IndexInterface<GMIndex<FormatT,Indices...>,
 					  Tuple<typename Indices::MetaType...> >
@@ -32,7 +42,6 @@ namespace CNORXZ
 	
 	typedef IndexInterface<GMIndex<FormatT,Indices...>,
 			       Tuple<typename Indices::MetaType...>> IB;
-	//typedef Tuple<Sptr<Indices>...> IndexPack;
 	typedef Tuple<typename Indices::MetaType...> MetaType;
 	typedef MRange<typename Indices::RangeType...> RangeType;
 	static constexpr SizeT NI = sizeof...(Indices);
@@ -52,36 +61,86 @@ namespace CNORXZ
 	constexpr GMIndex(const RangePtr& range, SizeT lexpos = 0);
 	constexpr GMIndex(const RangePtr& range, const FormatT& format, SizeT lexpos = 0);
 
+	/** @copydoc IndexInterface::operator=(SizeT) */
 	GMIndex& operator=(SizeT pos);
+
+	/** @copydoc IndexInterface::operator++() */
 	GMIndex& operator++();
+
+	/** @copydoc IndexInterface::operator--() */
 	GMIndex& operator--();
+
+	/** @copydoc IndexInterface::operator+() */
 	GMIndex operator+(Int n) const;
+
+	/** @copydoc IndexInterface::operator-() */
 	GMIndex operator-(Int n) const;
+
+	/** @copydoc IndexInterface::operator-(CIndex) */
 	SizeT operator-(const GMIndex& i) const;
+
+	/** @copydoc IndexInterface::operator+=() */
 	GMIndex& operator+=(Int n);
+
+	/** @copydoc IndexInterface::operator-=() */
 	GMIndex& operator-=(Int n);
 
+	/** @copydoc IndexInterface::lex() */
 	SizeT lex() const;
+
+	/** @copydoc IndexInterface::pmax() */
 	constexpr decltype(auto) pmax() const;
+
+	/** @copydoc IndexInterface::lmax() */
 	constexpr decltype(auto) lmax() const;
+
+	/** @copydoc IndexInterface::id() */
 	IndexId<0> id() const;
 
+	/** @copydoc IndexInterface::operator*() */
 	MetaType operator*() const;
 	
+	/** @copydoc IndexInterface::dim() */
 	constexpr SizeT dim() const;
+
+	/** @copydoc IndexInterface::range() */
 	Sptr<RangeType> range() const;
 
+	/** @copydoc IndexInterface::stepSize() */
 	template <SizeT I>
 	decltype(auto) stepSize(const IndexId<I>& id) const;
 
+	/** @copydoc IndexInterface::stringMeta() */
 	String stringMeta() const;
+
+	/** @copydoc IndexInterface::meta() */
 	MetaType meta() const;
+
+	/** @copydoc IndexInterface::at() */
 	GMIndex& at(const MetaType& metaPos);
-	decltype(auto) xpr(const Sptr<MIndex<Indices...>>& _this) const;
+
-	
+	/** @copydoc IndexInterface::prange() */
+	RangePtr prange(const GMIndex<FormatT,Indices...>& last) const;
+
+	/** @copydoc IndexInterface::deepFormat() */
+	auto deepFormat() const;
+
+	/** @copydoc IndexInterface::deepMax() */
+	auto deepMax() const;
+
+	/** @copydoc IndexInterface::reformat() */
+	GMIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s);
+
+	/** @copydoc IndexInterface::ifor() */
 	template <class Xpr, class F>
 	constexpr decltype(auto) ifor(const Xpr& xpr, F&& f) const;
 
+	/** @copydoc IndexInterface::formatIsTrivial() */
+	bool formatIsTrivial() const;
+
+	/** @copydoc IndexInterface::xpr() */
+	decltype(auto) xpr(const Sptr<MIndex<Indices...>>& _this) const;
+
 	// replace sub-index instances; only use if you know what you are doing!
 	GMIndex& operator()(const Sptr<MIndex<Indices...>>& mi);
 	GMIndex& operator()();
@@ -89,18 +148,9 @@ namespace CNORXZ
 	const SPack<Indices...>& pack() const;
 	const auto& format() const;
 	const auto& lexFormat() const;
-	RangePtr prange(const GMIndex<FormatT,Indices...>& last) const;
-	auto deepFormat() const;
-	auto deepMax() const;
-
-	/** @copydoc IndexInterface::reformat() */
-	GMIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s);
 
 	GMIndex& setFormat(const FormatT& bs);
 
-	/** @copydoc IndexInterface::formatIsTrivial() */
-	bool formatIsTrivial() const;
-
     private:
 	template <SizeT... Is>
 	static constexpr decltype(auto) mkLexFormat(const SPack<Indices...>& ipack, Isq<Is...> is);