From 4c71fac091a60d4d9990475054e627bd6a1b882b Mon Sep 17 00:00:00 2001 From: Christian Zimmermann Date: Sat, 13 Jan 2024 18:26:28 +0100 Subject: [PATCH] more documentation; WIP: mrange doc --- src/include/ranges/eindex.h | 55 ++++++++++++++-- src/include/ranges/index_format.h | 104 ++++++++++++++++++++++++++++-- src/include/ranges/index_mul.h | 48 +++++++++++++- src/include/ranges/index_traits.h | 2 +- src/include/ranges/index_utils.h | 29 --------- src/include/ranges/lindex.h | 46 +++++++++++-- src/include/ranges/mrange.h | 82 ++++++++++++++++++----- 7 files changed, 303 insertions(+), 63 deletions(-) delete mode 100644 src/include/ranges/index_utils.h diff --git a/src/include/ranges/eindex.h b/src/include/ranges/eindex.h index f7c0bc7..f7e2c81 100644 --- a/src/include/ranges/eindex.h +++ b/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 class EIndex : public LIndex,L> { @@ -28,9 +38,15 @@ namespace CNORXZ typedef typename LIndex,L>::IB IB; typedef typename LIndex,L>::RangeType RangeType; - DEFAULT_MEMBERS(EIndex); + DEFAULT_MEMBERS(EIndex); /**< default constructors and assignments */ EIndex(const Sptr,L>>& i); + /** @copydoc IndexInterface::ifor() + + Specialization for EIndex: access all elements + at once, allowing usage of vector extensions + @see EFor + */ template decltype(auto) ifor(const Xpr& xpr, F&& f) const; @@ -38,6 +54,10 @@ namespace CNORXZ Sptr,L>> mLI; }; + /** *** + EIndex is an index + @see is_index + */ template struct is_index> { @@ -53,25 +73,52 @@ namespace CNORXZ { static constexpr bool value = true; }; - + + /** Make index pack from EIndex and second index of arbitrary type + */ template decltype(auto) operator*(const Sptr>& a, const Sptr& b); + /** Create Eindex pointer from LIndex pointer + */ template decltype(auto) eindexPtr(const Sptr,L>>& i); + /** Create Eindex pointer from SIndex pointer + @tparam L Static index label + */ template decltype(auto) eindexPtr(const Sptr>& i); + /** Create Eindex pointer from LIndex pointer + @param l Static index label + */ template decltype(auto) eindexPtr(const Sptr>& i, CSizeT 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 decltype(auto) eplex(const Sptr& 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 decltype(auto) eplex(const Sptr& i, CSizeT s, CSizeT 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 decltype(auto) eplex(const Sptr& i, CSizeT s, CSizeT l1, CSizeT l2); diff --git a/src/include/ranges/index_format.h b/src/include/ranges/index_format.h index 9f80d32..f67ae74 100644 --- a/src/include/ranges/index_format.h +++ b/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 struct is_static_format { CXZ_CVAL_FALSE; }; - + + /** **** + Multi index format of static size. + Wrapper of standard array of UPos. + @tparam N Format size + */ template class MFormat { public: typedef Arr 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& b); + /** Construct MFormat from format of arbitrary type. + The input format size has to match the static size N. + @param f Input format + */ template constexpr MFormat(const FormatT& f); + /** Get underlying array. */ const Arr& all() const; + + /** Get format size. */ constexpr decltype(auto) size() const; + /** Get format element. + @param i CSizeT indicating static element position + */ template constexpr decltype(auto) get(CSizeT i) const; + /** Get format element. + @param i CSizeT indicating static element position + */ template constexpr decltype(auto) operator[](CSizeT i) const; @@ -46,27 +71,58 @@ namespace CNORXZ }; + /** **** + MFormat has static size. + @see is_static_format + */ template struct is_static_format> { CXZ_CVAL_TRUE; }; + /** **** + Multi index format of static size. + Wrapper of standard tuple of position types. + @tparam PosT Position types. + */ template class GMFormat { public: typedef Tuple 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& b); + + /** Construct from tuple (move). + @param b Input tuple. + */ explicit constexpr GMFormat(Tuple&& 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 constexpr GMFormat(const FormatT& f); + /** Get underlying tuple. */ const Tuple& all() const; + + /** Get format size. */ constexpr decltype(auto) size() const; + /** Get format element. + @param i CSizeT indicating static element position + */ template constexpr decltype(auto) get(CSizeT i) const; + /** Get format element. + @param i CSizeT indicating static element position + */ template constexpr decltype(auto) operator[](CSizeT i) const; @@ -74,38 +130,76 @@ namespace CNORXZ Tuple mB; }; + /** Create GMFormat from position types. + @param ps Position types. + */ template constexpr decltype(auto) gmformat(const PosT&... ps); + /** **** + GMFormat has static size. + @see is_static_format + */ template struct is_static_format> { CXZ_CVAL_TRUE; }; + /** **** + Multi index format of variable size + Wrapper of standard vector of UPos. + */ class YFormat { public: typedef Vector InputType; - DEFAULT_MEMBERS(YFormat); + DEFAULT_MEMBERS(YFormat); /**< default constructors and assignments */ + + /** Construct from vector. + @param b Input vector. + */ explicit YFormat(const Vector& b); + /** Construct from format of arbitrary type. + @param f Input format. + */ template YFormat(const FormatT& f); + /** Get underlying vector. */ const Vector& all() const; + + /** Get format size. */ SizeT size() const; + /** Get format element. + @param i CSizeT indicating static element position + */ template const UPos& get(CSizeT i) const; + /** Get format element. + @param i CSizeT indicating static element position + */ template const UPos& operator[](CSizeT 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 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& f, const Vector& s); } diff --git a/src/include/ranges/index_mul.h b/src/include/ranges/index_mul.h index 5e08cb3..de023d1 100644 --- a/src/include/ranges/index_mul.h +++ b/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, Isq js); }; + /** Combine two indices to a static index 2-pack. + @param a First index. + @param b Second index. + @return Static index 2-pack + */ template inline decltype(auto) operator*(const IndexInterface& a, const IndexInterface& 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 inline decltype(auto) operator*(const IndexInterface& a, const SPack& 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 inline decltype(auto) operator*(const SPack& a, const IndexInterface& 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 inline decltype(auto) operator*(const SPack& a, const SPack& 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 inline decltype(auto) operator*(const IndexInterface& 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 inline decltype(auto) operator*(const DPack& a, const IndexInterface& 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 decltype(auto) iptrMul(const Sptr& a, const Sptr& b); } diff --git a/src/include/ranges/index_traits.h b/src/include/ranges/index_traits.h index 439337f..601a96e 100644 --- a/src/include/ranges/index_traits.h +++ 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 **/ diff --git a/src/include/ranges/index_utils.h b/src/include/ranges/index_utils.h deleted file mode 100644 index e2f3cb4..0000000 --- a/src/include/ranges/index_utils.h +++ /dev/null @@ -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 - constexpr decltype(auto) autoiPtr(const SPack& pack); - - inline SPtr autoiPtr(const DPack& pack); - -} - -#endif diff --git a/src/include/ranges/lindex.h b/src/include/ranges/lindex.h index 283d347..1053909 100644 --- a/src/include/ranges/lindex.h +++ b/src/include/ranges/lindex.h @@ -2,10 +2,12 @@ /** @file include/ranges/lindex.h - @brief ... + @brief Statically labeled index. - - Copyright (c) 2022 Christian Zimmermann. All rights reserved. + Static index labels are usefull to resolve extensions and relations to + 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 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& i); + /** @copydoc IndexInterface::id() + Specialization: Static id equals L. + */ IndexId id() const; + /** @copydoc IndexInterface::stepSize() + Specialization: stepSize may be static. + */ template decltype(auto) stepSize(const IndexId& id) const; + /** @copydoc IndexInterface::stepSize() */ template decltype(auto) ifor(const Xpr& xpr, F&& f) const; @@ -43,6 +60,10 @@ namespace CNORXZ Sptr mI; }; + /** *** + LIndex is an index + @see is_index + */ template struct is_index> { @@ -59,12 +80,27 @@ namespace CNORXZ static constexpr bool value = index_expression_exists::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 decltype(auto) operator*(const Sptr>& a, const Sptr& b); + /** Create LIndex from index pointer. + @param i Input index. + @tparam L Static label. + @return Resulting LIndex. + */ template decltype(auto) lindexPtr(const Sptr& i); + /** Create LIndex from index pointer. + @param i Input index. + @param l CSizeT indicating the static label. + @return Resulting LIndex. + */ template decltype(auto) lindexPtr(const Sptr& i, CSizeT l); } diff --git a/src/include/ranges/mrange.h b/src/include/ranges/mrange.h index 2d9b1c0..155fc40 100644 --- a/src/include/ranges/mrange.h +++ b/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 - // -> 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 GMIndex : public IndexInterface, Tuple > @@ -32,7 +42,6 @@ namespace CNORXZ typedef IndexInterface, Tuple> IB; - //typedef Tuple...> IndexPack; typedef Tuple MetaType; typedef MRange 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 range() const; + /** @copydoc IndexInterface::stepSize() */ template decltype(auto) stepSize(const IndexId& 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>& _this) const; - + + /** @copydoc IndexInterface::prange() */ + RangePtr prange(const GMIndex& last) const; + + /** @copydoc IndexInterface::deepFormat() */ + auto deepFormat() const; + + /** @copydoc IndexInterface::deepMax() */ + auto deepMax() const; + + /** @copydoc IndexInterface::reformat() */ + GMIndex& reformat(const Vector& f, const Vector& s); + + /** @copydoc IndexInterface::ifor() */ template constexpr decltype(auto) ifor(const Xpr& xpr, F&& f) const; + /** @copydoc IndexInterface::formatIsTrivial() */ + bool formatIsTrivial() const; + + /** @copydoc IndexInterface::xpr() */ + decltype(auto) xpr(const Sptr>& _this) const; + // replace sub-index instances; only use if you know what you are doing! GMIndex& operator()(const Sptr>& mi); GMIndex& operator()(); @@ -89,18 +148,9 @@ namespace CNORXZ const SPack& pack() const; const auto& format() const; const auto& lexFormat() const; - RangePtr prange(const GMIndex& last) const; - auto deepFormat() const; - auto deepMax() const; - - /** @copydoc IndexInterface::reformat() */ - GMIndex& reformat(const Vector& f, const Vector& s); GMIndex& setFormat(const FormatT& bs); - /** @copydoc IndexInterface::formatIsTrivial() */ - bool formatIsTrivial() const; - private: template static constexpr decltype(auto) mkLexFormat(const SPack& ipack, Isq is);