Merge pull request 'dev' (#1) from dev into main

Reviewed-on: chizeta/CNORXZ#1

.gitlab-ci.yml

@@ -1,21 +0,0 @@
-
-image: docker.io/chizeta/centos:8
-
-stages:
-    - build
-
-build-centos:
-    stage: build
-    script:
-      - source /opt/rh/gcc-toolset-9/enable
-      - mkdir build-gcc
-      - cd build-gcc
-      - cmake3 ..
-      - make -j2
-      - make test
-      - cd ..
-      - mkdir build-clang
-      - cd build-clang
-      - CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake3 ..
-      - make -j2
-      - make test

README.md

@@ -1,5 +1,7 @@
 # Container with Native Operation Routines by XZ (CNORXZ)
 
+![Image](./cnorxz_logo.png)
+
 ## Description
 
 This library provides a framework for handling multi dimensional containers, their meta data, and several kinds of operations on one or more of them.
@@ -9,9 +11,10 @@ This library provides a framework for handling multi dimensional containers, the
 The library can be installed by the following procedure (`gtest` required):
 
 ```bash
-git clone git@git.f3l.de:chizeta/cnorxz.git <SOURCE_DIR>
+git clone git@git.f3l.de:chizeta/cnorxz.git <LIBRARY_ROOT_DIR>
+mkdir <BUILD_DIR>
 cd <BUILD_DIR>
-cmake -DCMAKE_INSTALL_PREFIX:PATH=<INSTALL_DIR> <SOURCE_DIR>
+cmake -DCMAKE_INSTALL_PREFIX:PATH=<INSTALL_DIR> <LIBRARY_ROOT_DIR>
 make install
 ```
 
@@ -31,7 +34,7 @@ The tools of the library are accessible within the namespace `CNORXZ`.
 
 (Also consider doxygen)
 
-### Basics
+### Basics and Library organization
 
 This library consists of several building blocks. For simple usage, the most important building blocks are [ranges](#ranges), [indices](#indices) and [array types](#arrays).
 
@@ -63,8 +66,11 @@ Apart from range specific indices, there exist also special indices:
 
 * `BIndex<T>` : The same as `AIndex`, but not const.
 
-#### Arrays
+#### Array types
 
 Finally, there are the container classes (arrays), which are derived from `CArrayBase<T>` (const) or `ArrayBase<T>` for a given data type `T`. All arrays are defined on a range, their data can be accessed or iterated over using suitable indices. The array-type actually containing data is called `MArray<T>`. Moreover, there exist array-types that do not contain data, but view the data of other arrays or at least parts of the data. These are called `CSlice<T>` (const view) or `Slice`.
 
+#### Expressions and Operations
+
+...
 

doc/doxy/Doxyfile

@@ -943,7 +943,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../../src
+INPUT                  = ../../README.md ../../src
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1110,7 +1110,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = README.md
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common

doc/doxy/html/cnorxz_logo.png

@@ -0,0 +1 @@
+../../../cnorxz_logo.png

src/include/cnorxz.h

@@ -9,19 +9,6 @@
    
 **/
 
-/**
-    @mainpage CNORXZ Documentation
-
-    ## Library organization
-    
-    ## Ranges and Indices
-
-    ## Array types
-
-    ## Expressions and Operations
-    
- **/
-
 #ifndef __cxz_cnorxz_h__
 #define __cxz_cnorxz_h__
 

src/include/ranges/crange.h

@@ -21,7 +21,7 @@
 namespace CNORXZ
 {
     /** ****
-	specific index for CRange
+	Specific index for CRange.
      */
     class CIndex : public IndexInterface<CIndex,SizeT>
     {
@@ -34,7 +34,7 @@ namespace CNORXZ
 	INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType);
 	DEFAULT_MEMBERS(CIndex); /**< default constructors and assignments */
 
-	/** constrcut index from range and position
+	/** Construct index from range and position.
 	    @param range Range to iterate over
 	    @param pos lexicographic position
 	 */
@@ -98,9 +98,6 @@ namespace CNORXZ
 	/** @copydoc IndexInterface::at() */
 	CIndex& at(const SizeT& metaPos);
 
-	/** @copydoc IndexInterface::xpr() */
-	COpRoot<SizeT,CIndex> xpr(const Sptr<CIndex>& _this) const;
-
 	/** @copydoc IndexInterface::prange() */
 	RangePtr prange(const CIndex& last) const;
 
@@ -120,6 +117,9 @@ namespace CNORXZ
 	/** @copydoc IndexInterface::formatIsTrivial() */
 	bool formatIsTrivial() const;
 	
+	/** @copydoc IndexInterface::xpr() */
+	COpRoot<SizeT,CIndex> xpr(const Sptr<CIndex>& _this) const;
+
     private:
 	Sptr<RangeType> mRangePtr;
     };

src/include/ranges/dindex.cc.h

@@ -44,7 +44,9 @@ namespace CNORXZ
     I indexAs(const DIndex& i)
     {
 	static_assert(is_index<I>::value, "expected index type");
-	return std::dynamic_pointer_cast<XIndex<I,typename I::MetaType>>( i.xptr() )->get();
+	auto ptr = std::dynamic_pointer_cast<XIndex<I,typename I::MetaType>>( i.xptr() );
+	CXZ_ASSERT(ptr, "invalid cast");
+	return ptr->get();
     }
 }
 

src/include/ranges/dindex.h

@@ -20,6 +20,9 @@
 
 namespace CNORXZ
 {
+    /** ****
+	index of compile-time-unspecified type
+     */
     class DIndex : public IndexInterface<DIndex,DType>
     {
     public:
@@ -27,64 +30,145 @@ namespace CNORXZ
 	typedef DType MetaType;
 	typedef RangeBase RangeType;
 
-	DEFAULT_C(DIndex);
+	DEFAULT_C(DIndex); /**< default constructor */
+
+	/** copy constructor
+	    @param i index to copy
+	 */
 	DIndex(const DIndex& i);
+
+	/** move constructor
+	    @param i index to move
+	 */
 	DIndex(DIndex&& i);
+
+	/** copy assignment
+	    @param i index to copy 
+	 */
 	DIndex& operator=(const DIndex& i);
+
+	/** move assignment
+	    @param i index to move
+	 */
 	DIndex& operator=(DIndex&& i);
+
+	/** construct from XIndex instance
+	    @param i XIndex to use for construction
+	 */
 	DIndex(const XIndexPtr& i);
+
+	/** construct from range pointer
+	    @param r Range to iterate over
+	    @param lexpos initial lexicographic position
+	 */
 	DIndex(const RangePtr& r, SizeT lexpos = 0);
 
+	/** construct from index of arbitrary type
+	    @param i Index to use for construction 
+	 */
 	template <class Index, typename Meta>
 	DIndex(const IndexInterface<Index,Meta>& i);
 
+	/** @copydoc IndexInterface::operator=(SizeT) */
 	DIndex& operator=(SizeT lexpos);
+
+	/** @copydoc IndexInterface::operator++() */
 	DIndex& operator++();
+
+	/** @copydoc IndexInterface::operator--() */
 	DIndex& operator--();
+
+	/** @copydoc IndexInterface::operator+() */
 	DIndex operator+(Int n) const;
+
+	/** @copydoc IndexInterface::operator-() */
 	DIndex operator-(Int n) const;
+
+	/** @copydoc IndexInterface::operator-(CIndex) */
 	SizeT operator-(const DIndex& i) const;
+
+	/** @copydoc IndexInterface::operator+=() */
 	DIndex& operator+=(Int n);
+
+	/** @copydoc IndexInterface::operator-=() */
 	DIndex& operator-=(Int n);
 
+	/** @copydoc IndexInterface::lex() */
 	SizeT lex() const;
+
+	/** @copydoc IndexInterface::pmax() */
 	UPos pmax() const;
+
+	/** @copydoc IndexInterface::lmax() */
 	UPos lmax() const;
+
+	/** @copydoc IndexInterface::id() */
 	IndexId<0> id() const;
 	
+	/** @copydoc IndexInterface::operator*() */
 	DType operator*() const;
 
+	/** @copydoc IndexInterface::dim() */
 	SizeT dim() const;
+
+	/** @copydoc IndexInterface::range() */
 	RangePtr range() const;
 
+	/** @copydoc IndexInterface::stepSize() */
 	UPos stepSize(const IndexId<0>& id) const;
 
+	/** @copydoc IndexInterface::stringMeta() */
 	String stringMeta() const;
+
+	/** @copydoc IndexInterface::meta() */
 	DType meta() const;
+
+	/** @copydoc IndexInterface::at() */
 	DIndex& at(const DType& meta);
+
+	/** @copydoc IndexInterface::prange() */
 	RangePtr prange(const DIndex& end) const;
+
+	/** @copydoc IndexInterface::deepFormat() */
 	Vector<SizeT> deepFormat() const;
+
+	/** @copydoc IndexInterface::deepMax() */
 	Vector<SizeT> deepMax() const;
 
 	/** @copydoc IndexInterface::reformat() */
 	DIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s);
 	
+	/** @copydoc IndexInterface::ifor() */
 	template <class Xpr, class F>
 	decltype(auto) ifor(const Xpr& xpr, F&& f) const;
 	
-	const XIndexPtr& xptr() const;
-
 	/** @copydoc IndexInterface::formatIsTrivial() */
 	bool formatIsTrivial() const;
 
+	/** get internal XIndex instance
+	    @return shared pointer to XIndex instance
+	 */
+	const XIndexPtr& xptr() const;
+
     private:
 	XIndexPtr mI;
     };
 
+    /** Trait-specialization:
+	DIndex can have sub-indices
+     */
     template <>
     struct has_sub<DIndex>
     { static constexpr bool value = true; };
 
+    /** dynamically cast DIndex to given type.
+	If type does not match the index type of the underlying index
+	and exception is thrown
+
+	@tparam I index type to be returned
+	@param i DIndex to by casted
+	@return copy of underlying index instance
+     */
     template <class I>
     I indexAs(const DIndex& i);
 }

src/include/ranges/index_pack.h

@@ -2,8 +2,13 @@
 /**
    
    @file include/ranges/index_pack.h
-   @brief ...
+   @brief Index pack declaration
 
+   Index packs are sets of indices. In contrast to multi-indices like
+   (G)MIndex or YIndex, there is no format that can be used to determine
+   a linearized memory position. Hence, only a lexicographic position is well defined.
+   Nevertheless, a function pos() is implemented, which just returns
+   the same value as lex().
 
    Copyright (c) 2022 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
@@ -18,76 +23,203 @@
 
 namespace CNORXZ
 {
+    /** ****
+	Static index pack.
+	Containes tuple of shared pointers to index instances.
+	@tparam Indices Index types.
+     */
     template <class... Indices>
     class SPack
     {
     public:
-	SP_DEFAULT_MEMBERS(constexpr,SPack);
+	SP_DEFAULT_MEMBERS(constexpr,SPack); /**< default constructors and assignments */
+
+	/** Construct from index pointers
+	    @param is index pointers
+	 */
 	constexpr SPack(const Sptr<Indices>&... is);
+
+	/** Construct from index pointer tuple
+	    @param is index pointer tuple
+	 */
 	constexpr SPack(const Tuple<Sptr<Indices>...>& is);
 
+	/** get underlying index pointer tuple
+	    @return underlying index pointer tuple
+	 */
 	constexpr const Tuple<Sptr<Indices>...>& all() const;
 
+	/** get pack size i.e. dimension (non-recursive)
+	    @return pack size
+	 */
 	constexpr SizeT size() const;
 
+	/** get pack element
+	    @return i'th element of the pack
+	    @tparam I static position
+	    @param i static position instance
+	 */
 	template <SizeT I>
 	constexpr decltype(auto) get(CSizeT<I> i) const;
 
+	/** get pack element
+	    @return i'th element of the pack
+	    @tparam I static position
+	    @param i static position instance
+	 */
 	template <SizeT I>
 	constexpr decltype(auto) operator[](CSizeT<I> i) const;
 
+	/** Append index on the r.h.s. of the pack.
+	    @tparam Index Type of the index to be appended
+	    @param i index to be appended
+	 */
 	template <class Index>
 	constexpr decltype(auto) rmul(const Sptr<Index>& i) const;
 
+	/** Append index on the l.h.s. of the pack.
+	    @tparam Index Type of the index to be appended
+	    @param i Index to be appended
+	 */
 	template <class Index>
 	constexpr decltype(auto) lmul(const Sptr<Index>& i) const;
 
+	/** Append another index pack on the r.h.s. of this pack
+	    @tparam Indices2 Types of the indices in the pack to be appended
+	    @param p Index pack to be appended
+	 */
 	template <class... Indices2>
 	constexpr decltype(auto) mul(const SPack<Indices2...>& p) const;
 
+	/** create a range from the index pack
+	    @return created range
+	 */
 	decltype(auto) mkRange() const;
 
+	/** Get lexicographic position if pack was transformed to a (trivial) multi-index.
+	    @return lexicographic position
+	 */
 	SizeT lex() const;
+
+	/** Get lexicographic position if pack was transformed to a (trivial) multi-index.
+	    @return lexicographic position
+	 */
 	SizeT pos() const;
 	
     private:
 	Tuple<Sptr<Indices>...> mIs;
     };
 
+    /** Create static index pack
+	@tparam Indices index types
+	@param inds Indices to create the pack from
+	@return Created pack
+     */
     template <class... Indices>
     constexpr decltype(auto) spack(const Indices&... inds);
 
+    /** Create static index pack from index pointers
+	@tparam Indices index types
+	@param inds Indices to create the pack from
+	@return Created pack
+     */
     template <class... Indices>
     constexpr decltype(auto) spackp(const Sptr<Indices>&... inds);
 
+    /** ******
+	Dynamic index pack.
+	Containes array of shared pointers to XIndex instances.
+     */
     class DPack
     {
     public:
-	DEFAULT_MEMBERS(DPack);
+	DEFAULT_MEMBERS(DPack); /**< default constructors and assignments */
+
+	/** Create pack from XIndex instance
+	    @param is Vector of XIndex pointers
+	 */
 	explicit DPack(const Vector<XIndexPtr>& is);
+
+	/** Create pack from XIndex instance (move input vector)
+	    @param is Vector of XIndex pointers
+	 */
 	explicit DPack(Vector<XIndexPtr>&& is);
 
+	/** Create pack from a static pack (SPack)
+	    @param p static pack used for construction
+	 */
 	template <class... Indices>
 	explicit DPack(const SPack<Indices...>& p);
 
+	/** get underlying index pointer vector
+	    @return underlying index pointer vector
+	 */
 	const Vector<XIndexPtr>& all() const;
+
+	/** get pack size i.e. dimension (non-recursive)
+	    @return pack size
+	 */
 	SizeT size() const;
+
+	/** get pack element
+	    @return i'th element of the pack
+	    @param i Position
+	 */
 	const XIndexPtr& get(SizeT i) const;
+
+	/** get pack element
+	    @return i'th element of the pack
+	    @param i Position
+	 */
 	const XIndexPtr& operator[](SizeT i) const;
+
+	/** Append index on the r.h.s.
+	    @param i DIndex to be appended
+	 */
 	DPack rmul(const Sptr<DIndex>& i) const;
+
+	/** Append index on the l.h.s.
+	    @param i DIndex to be appended
+	 */
 	DPack lmul(const Sptr<DIndex>& i) const;
+
+	/** Append pack on the r.h.s.
+	    @param p Pack to be appnded
+	 */
 	DPack mul(const DPack& p) const;
+
+	/** create a range from the index pack
+	    @return created range
+	 */
 	RangePtr mkRange() const;
+
+	/** Get lexicographic position if pack was transformed to a (trivial) multi-index.
+	    @return lexicographic position
+	 */
 	SizeT lex() const;
+
+	/** Get lexicographic position if pack was transformed to a (trivial) multi-index.
+	    @return lexicographic position
+	 */
 	SizeT pos() const;
 	
     private:
 	Vector<XIndexPtr> mIs;
     };
 
+    /** Create dynamic index pack
+	@tparam Indices index types
+	@param inds Indices to create the pack from
+	@return Created pack
+     */
     template <class... Indices>
     DPack dpack(const Indices&... inds);
 
+    /** Create dynamic index pack from index pointers
+	@tparam Indices index types
+	@param inds Indices to create the pack from
+	@return Created pack
+     */
     template <class... Indices>
     DPack dpackp(const Sptr<Indices>&... inds);
 }