more doc
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful

This commit is contained in:
Christian Zimmermann 2024-01-14 23:57:42 +01:00
parent 4c71fac091
commit ac352206c7
4 changed files with 178 additions and 78 deletions

View file

@ -36,9 +36,9 @@ The tools of the library are accessible within the namespace `CNORXZ`.
### Basics and Library organization ### 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: 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. * `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<MetaT>`, `SIndex<MetaT,S>`, `PIndex<IndexT>`, `MIndex<IndexTs...>`, `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<Index,MetaT>`). For each range type there is a corresponding index type (`CIndex`, `UIndex<MetaT>`, `SIndex<MetaT,S>`, `PIndex<IndexT>`, `MIndex<IndexTs...>`, `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<Index,MetaT>`).
@ -66,7 +66,7 @@ Apart from range specific indices, there exist also special indices:
* `BIndex<T>` : The same as `AIndex`, but not const. * `BIndex<T>` : 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<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`. 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`.

View file

@ -4,7 +4,7 @@
@file include/ranges/crange.h @file include/ranges/crange.h
@brief CRange and CIndex declaration. @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 Mail: chizeta@f3l.de
**/ **/
@ -34,8 +34,8 @@ namespace CNORXZ
DEFAULT_MEMBERS(CIndex); /**< default constructors and assignments */ DEFAULT_MEMBERS(CIndex); /**< default constructors and assignments */
/** Construct index from range and position. /** Construct index from range and position.
@param range Range to iterate over @param range Range to iterate over.
@param pos lexicographic position @param pos lexicographic position.
*/ */
CIndex(const RangePtr& range, SizeT pos = 0); CIndex(const RangePtr& range, SizeT pos = 0);
@ -123,30 +123,30 @@ namespace CNORXZ
Sptr<RangeType> mRangePtr; Sptr<RangeType> mRangePtr;
}; };
/** make index pack of a CIndex and another index /** make index pack of a CIndex and another index.
@tparam type of the second index @tparam type of the second index.
@param a pointer to CIndex @param a pointer to CIndex.
@param b pointer to another index @param b pointer to another index.
*/ */
template <class I> template <class I>
decltype(auto) operator*(const Sptr<CIndex>& a, const Sptr<I>& b); decltype(auto) operator*(const Sptr<CIndex>& a, const Sptr<I>& b);
/** **** /** ****
specific factory for CRange Specific factory for CRange.
*/ */
class CRangeFactory : public RangeFactoryBase class CRangeFactory : public RangeFactoryBase
{ {
public: public:
typedef CRange oType; typedef CRange oType;
/** Construct and setup factory /** Construct and setup factory.
@param size Size of the range to be constructed @param size Size of the range to be constructed.
*/ */
CRangeFactory(SizeT size); CRangeFactory(SizeT size);
/** Construct and setup factory /** Construct and setup factory.
@param size Size of the range to be constructed @param size Size of the range to be constructed.
@param ref Range the range to be constructed is related to @param ref Range the range to be constructed is related to.
*/ */
CRangeFactory(SizeT size, RangePtr ref); CRangeFactory(SizeT size, RangePtr ref);

View file

@ -2,10 +2,10 @@
/** /**
@file include/ranges/mrange.cc.h @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 Mail: chizeta@f3l.de
**/ **/
@ -21,9 +21,9 @@
namespace CNORXZ namespace CNORXZ
{ {
/************************ /*=========================+
* GMIndex (private) * | GMIndex (private) |
************************/ +=========================*/
template <class FormatT, class... Indices> template <class FormatT, class... Indices>
template <SizeT... Is> template <SizeT... Is>
@ -147,9 +147,9 @@ namespace CNORXZ
} }
} }
/*************** /*===============+
* GMIndex * | GMIndex |
***************/ +===============*/
template <class FormatT, class... Indices> template <class FormatT, class... Indices>
constexpr GMIndex<FormatT,Indices...>::GMIndex(const GMIndex& i) : constexpr GMIndex<FormatT,Indices...>::GMIndex(const GMIndex& i) :
@ -613,15 +613,6 @@ namespace CNORXZ
return *this; return *this;
} }
template <class BT1, class BT2, class... Indices>
decltype(auto) replaceFormat(const BT1& bs1, const Sptr<GMIndex<BT2,Indices...>>& gmi)
{
return iter<0,sizeof...(Indices)>
( [&](auto i) { return gmi->pack()[CSizeT<i>{}]; },
[&](const auto&... e) { return std::make_shared<GMIndex<BT1,Indices...>>
( bs1, e... ); } );
}
template <class... Indices> template <class... Indices>
constexpr decltype(auto) mindex(const Sptr<Indices>&... is) constexpr decltype(auto) mindex(const Sptr<Indices>&... is)
{ {
@ -652,9 +643,9 @@ namespace CNORXZ
return iptrMul(a, b); return iptrMul(a, b);
} }
/********************* /*=====================+
* MRangeFactory * | MRangeFactory |
*********************/ +=====================*/
template <class... Ranges> template <class... Ranges>
MRangeFactory<Ranges...>::MRangeFactory(const Tuple<Sptr<Ranges>...>& rs) : MRangeFactory<Ranges...>::MRangeFactory(const Tuple<Sptr<Ranges>...>& rs) :
@ -683,9 +674,9 @@ namespace CNORXZ
} }
} }
/************** /*==============+
* MRange * | MRange |
**************/ +==============*/
template <class... Ranges> template <class... Ranges>
MRange<Ranges...>::MRange(const Tuple<Sptr<Ranges>...>& rs) : MRange<Ranges...>::MRange(const Tuple<Sptr<Ranges>...>& rs) :
@ -703,7 +694,6 @@ namespace CNORXZ
template <class... Ranges> template <class... Ranges>
MArray<RangePtr> MRange<Ranges...>::sub() const MArray<RangePtr> MRange<Ranges...>::sub() const
{ {
// TODO: ZRange (meta and index pos static!)
if constexpr(NR == 0) { if constexpr(NR == 0) {
return MArray<RangePtr>(); return MArray<RangePtr>();
} }
@ -791,9 +781,9 @@ namespace CNORXZ
return k; return k;
} }
/************************ /*========================+
* MRange (private) * | MRange (private) |
************************/ +========================*/
template <class... Ranges> template <class... Ranges>
decltype(auto) MRange<Ranges...>::mkA() const decltype(auto) MRange<Ranges...>::mkA() const
@ -802,9 +792,9 @@ namespace CNORXZ
[](const auto&... xs) { return Arr<RangePtr,NR> { xs... }; } ); [](const auto&... xs) { return Arr<RangePtr,NR> { xs... }; } );
} }
/**************************** /*============================+
* non-member functions * | non-member functions |
****************************/ +============================*/
template <class... Ranges> template <class... Ranges>
RangePtr mrange(const Sptr<Ranges>&... rs) RangePtr mrange(const Sptr<Ranges>&... rs)

View file

@ -2,7 +2,7 @@
/** /**
@file include/ranges/mrange.h @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. 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); static constexpr SizeT NI = sizeof...(Indices);
INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType); INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType);
/** Default constructor. */
constexpr GMIndex() = default; constexpr GMIndex() = default;
/** Move constructor (default). */
constexpr GMIndex(GMIndex&& i) = default; constexpr GMIndex(GMIndex&& i) = default;
/** Move assignment (default). */
constexpr GMIndex& operator=(GMIndex&& i) = default; constexpr GMIndex& operator=(GMIndex&& i) = default;
// no defaults:
/** Copy constructor (no default, copy sub-index instances). */
constexpr GMIndex(const GMIndex& i); constexpr GMIndex(const GMIndex& i);
/** Copy assignment (no default, copy sub-index instances). */
constexpr GMIndex& operator=(const GMIndex& i); constexpr GMIndex& operator=(const GMIndex& i);
/** Construct from index pack. */
constexpr GMIndex(const SPack<Indices...>& pack); constexpr GMIndex(const SPack<Indices...>& pack);
/** Construct from index pack and format. */
constexpr GMIndex(const FormatT& format, const SPack<Indices...>& pack); constexpr GMIndex(const FormatT& format, const SPack<Indices...>& pack);
/** Construct from index pointers. */
constexpr GMIndex(const Sptr<Indices>&... is); constexpr GMIndex(const Sptr<Indices>&... is);
/** Construct from index pointers and format. */
constexpr GMIndex(const FormatT& format, const Sptr<Indices>&... is); constexpr GMIndex(const FormatT& format, const Sptr<Indices>&... is);
/** Construct from range. */
constexpr GMIndex(const RangePtr& range, SizeT lexpos = 0); constexpr GMIndex(const RangePtr& range, SizeT lexpos = 0);
/** Construct from range and format. */
constexpr GMIndex(const RangePtr& range, const FormatT& format, SizeT lexpos = 0); constexpr GMIndex(const RangePtr& range, const FormatT& format, SizeT lexpos = 0);
/** @copydoc IndexInterface::operator=(SizeT) */ /** @copydoc IndexInterface::operator=(SizeT) */
@ -142,13 +162,24 @@ namespace CNORXZ
decltype(auto) xpr(const Sptr<MIndex<Indices...>>& _this) const; decltype(auto) xpr(const Sptr<MIndex<Indices...>>& _this) const;
// replace sub-index instances; only use if you know what you are doing! // 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<MIndex<Indices...>>& mi); GMIndex& operator()(const Sptr<MIndex<Indices...>>& mi);
/** Update index position according to the sub-indices. */
GMIndex& operator()(); GMIndex& operator()();
/** Get index pack. */
const SPack<Indices...>& pack() const; const SPack<Indices...>& pack() const;
/** Get index format. */
const auto& format() const; const auto& format() const;
/** Get lexicographic index format. */
const auto& lexFormat() const; const auto& lexFormat() const;
/** Assign new index format. */
GMIndex& setFormat(const FormatT& bs); GMIndex& setFormat(const FormatT& bs);
private: private:
@ -185,53 +216,114 @@ namespace CNORXZ
PMaxT mPMax; PMaxT mPMax;
}; };
template <class BT1, class BT2, class... Indices> /** ****
decltype(auto) replaceFormat(const BT1& bs1, const Sptr<GMIndex<BT2,Indices...>>& gmi); Specialization of index_has_const_size for GMIndex.
@see index_has_const_size
template <class... Indices> */
struct index_has_const_size<MIndex<Indices...>> template <class FormatT, class... Indices>
struct index_has_const_size<GMIndex<FormatT,Indices...>>
{ static constexpr bool value = (index_has_const_size<Indices>::value and ...); }; { static constexpr bool value = (index_has_const_size<Indices>::value and ...); };
template <class... Indices> /** ****
struct index_const_size<MIndex<Indices...>> Specialization of index_const_size for GMIndex.
@see index_const_size
*/
template <class FormatT, class... Indices>
struct index_const_size<GMIndex<FormatT,Indices...>>
{ static constexpr SizeT value = (index_const_size<Indices>::value * ...); }; { static constexpr SizeT value = (index_const_size<Indices>::value * ...); };
template <class... Indices> /** ****
struct index_dim<MIndex<Indices...>> Specialization of index_dim for GMIndex.
@see index_dim
*/
template <class FormatT, class... Indices>
struct index_dim<GMIndex<FormatT,Indices...>>
{ static constexpr SizeT value = sizeof...(Indices); }; { static constexpr SizeT value = sizeof...(Indices); };
template <class... Indices> /** ****
struct has_sub<MIndex<Indices...>> Specialization of has_sub for GMIndex.
@see has_sub
*/
template <class FormatT, class... Indices>
struct has_sub<GMIndex<FormatT,Indices...>>
{ static constexpr bool value = true; }; { static constexpr bool value = true; };
template <class... Indices> /** ****
struct has_static_sub<MIndex<Indices...>> Specialization of has_static_sub for GMIndex.
@see has_static_sub
*/
template <class FormatT, class... Indices>
struct has_static_sub<GMIndex<FormatT,Indices...>>
{ static constexpr bool value = true; }; { static constexpr bool value = true; };
template <class... Indices> /** ****
struct index_is_multi<MIndex<Indices...>> Specialization of index_is_multi for GMIndex.
@see index_is_multi
*/
template <class FormatT, class... Indices>
struct index_is_multi<GMIndex<FormatT,Indices...>>
{ static constexpr bool value = true; }; { 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 <class... Indices>
struct index_expression_exists<MIndex<Indices...>>
{
static constexpr bool value = (index_expression_exists<Indices>::value and ...);
};
/** Create MIndex from index pointers.
@param is Input index pointers.
*/
template <class... Indices> template <class... Indices>
constexpr decltype(auto) mindex(const Sptr<Indices>&... is); constexpr decltype(auto) mindex(const Sptr<Indices>&... is);
/** Create MIndex from index pack.
@param pack Pack of input indices.
*/
template <class... Indices> template <class... Indices>
constexpr decltype(auto) mindex(const SPack<Indices...>& pack); constexpr decltype(auto) mindex(const SPack<Indices...>& pack);
/** Create pointer to MIndex from index pack.
@param pack Pack of input indices.
*/
template <class... Indices> template <class... Indices>
constexpr decltype(auto) mindexPtr(const SPack<Indices...>& pack); constexpr decltype(auto) mindexPtr(const SPack<Indices...>& pack);
/** Create pointer to GMIndex from index pack and format.
@param bs Index format.
@param pack Pack of input indices.
*/
template <class FormatT, class... Indices> template <class FormatT, class... Indices>
constexpr decltype(auto) gmindexPtr(const FormatT& bs, const SPack<Indices...>& pack); constexpr decltype(auto) gmindexPtr(const FormatT& bs, const SPack<Indices...>& 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 <class I1, class FormatT, class... Indices> template <class I1, class FormatT, class... Indices>
decltype(auto) operator*(const Sptr<GMIndex<FormatT,Indices...>>& a, const Sptr<I1>& b); decltype(auto) operator*(const Sptr<GMIndex<FormatT,Indices...>>& a, const Sptr<I1>& b);
/** ****
Specific factory for MRange.
@tparam Ranges Types of the sub-ranges.
*/
template <class... Ranges> template <class... Ranges>
class MRangeFactory : public RangeFactoryBase class MRangeFactory : public RangeFactoryBase
{ {
public: public:
/** Construct and setup factory.
@param rs Tuple of sub-ranges.
*/
MRangeFactory(const Tuple<Sptr<Ranges>...>& rs); MRangeFactory(const Tuple<Sptr<Ranges>...>& 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<Sptr<Ranges>...>& rs, const RangePtr& ref); MRangeFactory(const Tuple<Sptr<Ranges>...>& rs, const RangePtr& ref);
private: private:
@ -241,7 +333,11 @@ namespace CNORXZ
Tuple<Sptr<Ranges>...> mRs; Tuple<Sptr<Ranges>...> mRs;
RangePtr mRef; RangePtr mRef;
}; };
/** ****
Multi Range with compile-time fixed number of sub-ranges
of compile-time fixed type.
*/
template <class... Ranges> template <class... Ranges>
class MRange : public RangeInterface<MRange<Ranges...>> class MRange : public RangeInterface<MRange<Ranges...>>
{ {
@ -261,19 +357,35 @@ namespace CNORXZ
virtual const TypeInfo& type() const override final; virtual const TypeInfo& type() const override final;
virtual const TypeInfo& metaType() const override final; virtual const TypeInfo& metaType() const override final;
virtual RangePtr extend(const RangePtr& r) const override final; virtual RangePtr extend(const RangePtr& r) const override final;
/** Get sub-ranges. */
decltype(auto) space() const; decltype(auto) space() const;
/** Get sub-range.
@param pos Position of the sub-range.
*/
const MetaType get(SizeT pos) const; 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; SizeT getMeta(const MetaType& metaPos) const;
protected: protected:
/** Dafault constructor */
MRange() = default; MRange() = default;
MRange(const MRange& in) = delete; MRange(const MRange& in) = delete;
MRange& operator=(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<Sptr<Ranges>...>& rs); MRange(const Tuple<Sptr<Ranges>...>& rs);
Tuple<Sptr<Ranges>...> mRs; Tuple<Sptr<Ranges>...> mRs; /**< Tuple of pointers to sub-ranges. */
Arr<RangePtr,NR> mA; Arr<RangePtr,NR> mA; /**< Array of abstract base pointers to sub-ranges. Redundant to mRs */
virtual Vector<Uuid> key() const override final; virtual Vector<Uuid> key() const override final;
private: private:
@ -281,24 +393,22 @@ namespace CNORXZ
decltype(auto) mkA() const; decltype(auto) mkA() const;
}; };
/** Create MRange pointer.
@param rs Pointer to sub-ranges.
*/
template <class... Ranges> template <class... Ranges>
RangePtr mrange(const Sptr<Ranges>&... rs); RangePtr mrange(const Sptr<Ranges>&... rs);
/** ****
Specialization of RangeCast for MRange.
@see RangeCast.
*/
template <class... Ranges> template <class... Ranges>
struct RangeCast<MRange<Ranges...>> struct RangeCast<MRange<Ranges...>>
{ {
static Sptr<MRange<Ranges...>> func(const RangePtr& r); static Sptr<MRange<Ranges...>> 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 <class... Indices>
struct index_expression_exists<MIndex<Indices...>>
{
static constexpr bool value = (index_expression_exists<Indices>::value and ...);
};
} }