From ac352206c71251c3f49baaa55cbfeb77ad34876b Mon Sep 17 00:00:00 2001 From: Christian Zimmermann Date: Sun, 14 Jan 2024 23:57:42 +0100 Subject: [PATCH] more doc --- README.md | 8 +- src/include/ranges/crange.h | 26 ++--- src/include/ranges/mrange.cc.h | 50 ++++------ src/include/ranges/mrange.h | 172 +++++++++++++++++++++++++++------ 4 files changed, 178 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 324e643..19c0247 100644 --- a/README.md +++ b/README.md @@ -36,9 +36,9 @@ The tools of the library are accessible within the namespace `CNORXZ`. ### 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). +This library consists of several building blocks. For simple usage, the most important building blocks are [ranges](#sec-ranges), [indices](#sec-indices) and [arrays](#sec-array-types). -#### Ranges +#### Ranges {#sec-ranges} Basically, a *range* defines a meta data space. There are several range class types, which are derived from the abstract base class `RangeBase`. Ranges can only be created by the corresponding factory and exclusively exist within a shared pointer; they cannot be copied. Available range class types are: @@ -54,7 +54,7 @@ Basically, a *range* defines a meta data space. There are several range class ty * `YRange` : The same as `MRange` but the number of ranges and their types can be specified at runtime. -#### Indices +#### Indices {#sec-indices} For each range type there is a corresponding index type (`CIndex`, `UIndex`, `SIndex`, `PIndex`, `MIndex`, `YIndex`). They act as const iterators on the ranges and are a crucial component to define operations on containers. In contrast to the ranges, all index types must be known at compile time (static polymorphism, `IndexInterface`). @@ -66,7 +66,7 @@ Apart from range specific indices, there exist also special indices: * `BIndex` : The same as `AIndex`, but not const. -#### Array types +#### Array types {#sec-array-types} Finally, there are the container classes (arrays), which are derived from `CArrayBase` (const) or `ArrayBase` 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`. 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` (const view) or `Slice`. diff --git a/src/include/ranges/crange.h b/src/include/ranges/crange.h index cfef60b..6eb1fbb 100644 --- a/src/include/ranges/crange.h +++ b/src/include/ranges/crange.h @@ -4,7 +4,7 @@ @file include/ranges/crange.h @brief CRange and CIndex declaration. - Copyright (c) 2022 Christian Zimmermann. All rights reserved. + Copyright (c) 2024 Christian Zimmermann. All rights reserved. Mail: chizeta@f3l.de **/ @@ -34,8 +34,8 @@ namespace CNORXZ DEFAULT_MEMBERS(CIndex); /**< default constructors and assignments */ /** Construct index from range and position. - @param range Range to iterate over - @param pos lexicographic position + @param range Range to iterate over. + @param pos lexicographic position. */ CIndex(const RangePtr& range, SizeT pos = 0); @@ -123,30 +123,30 @@ namespace CNORXZ Sptr mRangePtr; }; - /** make index pack of a CIndex and another index - @tparam type of the second index - @param a pointer to CIndex - @param b pointer to another index + /** make index pack of a CIndex and another index. + @tparam type of the second index. + @param a pointer to CIndex. + @param b pointer to another index. */ template decltype(auto) operator*(const Sptr& a, const Sptr& b); /** **** - specific factory for CRange + Specific factory for CRange. */ class CRangeFactory : public RangeFactoryBase { public: typedef CRange oType; - /** Construct and setup factory - @param size Size of the range to be constructed + /** Construct and setup factory. + @param size Size of the range to be constructed. */ CRangeFactory(SizeT size); - /** Construct and setup factory - @param size Size of the range to be constructed - @param ref Range the range to be constructed is related to + /** Construct and setup factory. + @param size Size of the range to be constructed. + @param ref Range the range to be constructed is related to. */ CRangeFactory(SizeT size, RangePtr ref); diff --git a/src/include/ranges/mrange.cc.h b/src/include/ranges/mrange.cc.h index b9ea9ac..368f8bc 100644 --- a/src/include/ranges/mrange.cc.h +++ b/src/include/ranges/mrange.cc.h @@ -2,10 +2,10 @@ /** @file include/ranges/mrange.cc.h - @brief ... + @brief MRange, GMIndex and MIndex, member definition. - Copyright (c) 2022 Christian Zimmermann. All rights reserved. + Copyright (c) 2024 Christian Zimmermann. All rights reserved. Mail: chizeta@f3l.de **/ @@ -21,9 +21,9 @@ namespace CNORXZ { - /************************ - * GMIndex (private) * - ************************/ + /*=========================+ + | GMIndex (private) | + +=========================*/ template template @@ -147,9 +147,9 @@ namespace CNORXZ } } - /*************** - * GMIndex * - ***************/ + /*===============+ + | GMIndex | + +===============*/ template constexpr GMIndex::GMIndex(const GMIndex& i) : @@ -613,15 +613,6 @@ namespace CNORXZ return *this; } - template - decltype(auto) replaceFormat(const BT1& bs1, const Sptr>& gmi) - { - return iter<0,sizeof...(Indices)> - ( [&](auto i) { return gmi->pack()[CSizeT{}]; }, - [&](const auto&... e) { return std::make_shared> - ( bs1, e... ); } ); - } - template constexpr decltype(auto) mindex(const Sptr&... is) { @@ -652,9 +643,9 @@ namespace CNORXZ return iptrMul(a, b); } - /********************* - * MRangeFactory * - *********************/ + /*=====================+ + | MRangeFactory | + +=====================*/ template MRangeFactory::MRangeFactory(const Tuple...>& rs) : @@ -683,9 +674,9 @@ namespace CNORXZ } } - /************** - * MRange * - **************/ + /*==============+ + | MRange | + +==============*/ template MRange::MRange(const Tuple...>& rs) : @@ -703,7 +694,6 @@ namespace CNORXZ template MArray MRange::sub() const { - // TODO: ZRange (meta and index pos static!) if constexpr(NR == 0) { return MArray(); } @@ -791,9 +781,9 @@ namespace CNORXZ return k; } - /************************ - * MRange (private) * - ************************/ + /*========================+ + | MRange (private) | + +========================*/ template decltype(auto) MRange::mkA() const @@ -802,9 +792,9 @@ namespace CNORXZ [](const auto&... xs) { return Arr { xs... }; } ); } - /**************************** - * non-member functions * - ****************************/ + /*============================+ + | non-member functions | + +============================*/ template RangePtr mrange(const Sptr&... rs) diff --git a/src/include/ranges/mrange.h b/src/include/ranges/mrange.h index 155fc40..b0bda2f 100644 --- a/src/include/ranges/mrange.h +++ b/src/include/ranges/mrange.h @@ -2,7 +2,7 @@ /** @file include/ranges/mrange.h - @brief MRange, GMIndex and MIndex declaration + @brief MRange, GMIndex and MIndex declaration. MRange is a multi-range consisting of of a compile-time fixed number of sub-ranges. @@ -47,18 +47,38 @@ namespace CNORXZ static constexpr SizeT NI = sizeof...(Indices); INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType); + + /** Default constructor. */ constexpr GMIndex() = default; + + /** Move constructor (default). */ constexpr GMIndex(GMIndex&& i) = default; + + /** Move assignment (default). */ constexpr GMIndex& operator=(GMIndex&& i) = default; - // no defaults: + + /** Copy constructor (no default, copy sub-index instances). */ constexpr GMIndex(const GMIndex& i); + + /** Copy assignment (no default, copy sub-index instances). */ constexpr GMIndex& operator=(const GMIndex& i); + /** Construct from index pack. */ constexpr GMIndex(const SPack& pack); + + /** Construct from index pack and format. */ constexpr GMIndex(const FormatT& format, const SPack& pack); + + /** Construct from index pointers. */ constexpr GMIndex(const Sptr&... is); + + /** Construct from index pointers and format. */ constexpr GMIndex(const FormatT& format, const Sptr&... is); + + /** Construct from range. */ constexpr GMIndex(const RangePtr& range, SizeT lexpos = 0); + + /** Construct from range and format. */ constexpr GMIndex(const RangePtr& range, const FormatT& format, SizeT lexpos = 0); /** @copydoc IndexInterface::operator=(SizeT) */ @@ -142,13 +162,24 @@ namespace CNORXZ decltype(auto) xpr(const Sptr>& _this) const; // replace sub-index instances; only use if you know what you are doing! + /** Replace sub-index instances and update index position correspondingly. + @param new index instances. + */ GMIndex& operator()(const Sptr>& mi); + + /** Update index position according to the sub-indices. */ GMIndex& operator()(); + /** Get index pack. */ const SPack& pack() const; + + /** Get index format. */ const auto& format() const; + + /** Get lexicographic index format. */ const auto& lexFormat() const; + /** Assign new index format. */ GMIndex& setFormat(const FormatT& bs); private: @@ -185,53 +216,114 @@ namespace CNORXZ PMaxT mPMax; }; - template - decltype(auto) replaceFormat(const BT1& bs1, const Sptr>& gmi); - - template - struct index_has_const_size> + /** **** + Specialization of index_has_const_size for GMIndex. + @see index_has_const_size + */ + template + struct index_has_const_size> { static constexpr bool value = (index_has_const_size::value and ...); }; - template - struct index_const_size> + /** **** + Specialization of index_const_size for GMIndex. + @see index_const_size + */ + template + struct index_const_size> { static constexpr SizeT value = (index_const_size::value * ...); }; - template - struct index_dim> + /** **** + Specialization of index_dim for GMIndex. + @see index_dim + */ + template + struct index_dim> { static constexpr SizeT value = sizeof...(Indices); }; - template - struct has_sub> + /** **** + Specialization of has_sub for GMIndex. + @see has_sub + */ + template + struct has_sub> { static constexpr bool value = true; }; - template - struct has_static_sub> + /** **** + Specialization of has_static_sub for GMIndex. + @see has_static_sub + */ + template + struct has_static_sub> { static constexpr bool value = true; }; - template - struct index_is_multi> + /** **** + Specialization of index_is_multi for GMIndex. + @see index_is_multi + */ + template + struct index_is_multi> { static constexpr bool value = true; }; + /** *** + MIndex can be used as expression if all its sub-indices can be used as expression + @see index_expression_exists + */ + template + struct index_expression_exists> + { + static constexpr bool value = (index_expression_exists::value and ...); + }; + + /** Create MIndex from index pointers. + @param is Input index pointers. + */ template constexpr decltype(auto) mindex(const Sptr&... is); + /** Create MIndex from index pack. + @param pack Pack of input indices. + */ template constexpr decltype(auto) mindex(const SPack& pack); + /** Create pointer to MIndex from index pack. + @param pack Pack of input indices. + */ template constexpr decltype(auto) mindexPtr(const SPack& pack); + /** Create pointer to GMIndex from index pack and format. + @param bs Index format. + @param pack Pack of input indices. + */ template constexpr decltype(auto) gmindexPtr(const FormatT& bs, const SPack& pack); - + + /** Specialization for index multiplication with GMIndex on the l.h.s. + @param a First index of type GMIndex. + @param b Second index of arbitrary type. + */ template decltype(auto) operator*(const Sptr>& a, const Sptr& b); + /** **** + Specific factory for MRange. + @tparam Ranges Types of the sub-ranges. + */ template class MRangeFactory : public RangeFactoryBase { public: + + /** Construct and setup factory. + @param rs Tuple of sub-ranges. + */ MRangeFactory(const Tuple...>& rs); + + /** Construct and setup factory. + @param rs Tuple of sub-ranges. + @param ref Range the range to be constructed is related to. + */ MRangeFactory(const Tuple...>& rs, const RangePtr& ref); private: @@ -241,7 +333,11 @@ namespace CNORXZ Tuple...> mRs; RangePtr mRef; }; - + + /** **** + Multi Range with compile-time fixed number of sub-ranges + of compile-time fixed type. + */ template class MRange : public RangeInterface> { @@ -261,19 +357,35 @@ namespace CNORXZ virtual const TypeInfo& type() const override final; virtual const TypeInfo& metaType() const override final; virtual RangePtr extend(const RangePtr& r) const override final; - + + /** Get sub-ranges. */ decltype(auto) space() const; + + /** Get sub-range. + @param pos Position of the sub-range. + */ const MetaType get(SizeT pos) const; + + /** Get lexicographic position according to the given meta data value. + @param metaPos Meta data value. + */ SizeT getMeta(const MetaType& metaPos) const; protected: + + /** Dafault constructor */ MRange() = default; + MRange(const MRange& in) = delete; MRange& operator=(const MRange& in) = delete; + + /** Construct from sub-ranges + @param rs Tuple of pointers to sub-ranges. + */ MRange(const Tuple...>& rs); - Tuple...> mRs; - Arr mA; + Tuple...> mRs; /**< Tuple of pointers to sub-ranges. */ + Arr mA; /**< Array of abstract base pointers to sub-ranges. Redundant to mRs */ virtual Vector key() const override final; private: @@ -281,24 +393,22 @@ namespace CNORXZ decltype(auto) mkA() const; }; + /** Create MRange pointer. + @param rs Pointer to sub-ranges. + */ template RangePtr mrange(const Sptr&... rs); + /** **** + Specialization of RangeCast for MRange. + @see RangeCast. + */ template struct RangeCast> { static Sptr> func(const RangePtr& r); }; - /** *** - MIndex can be used as expression if all its sub-indices can be used as expression - @see index_expression_exists - */ - template - struct index_expression_exists> - { - static constexpr bool value = (index_expression_exists::value and ...); - }; }