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
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<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.
#### 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`.

View file

@ -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<RangeType> 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 <class I>
decltype(auto) operator*(const Sptr<CIndex>& a, const Sptr<I>& 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);

View file

@ -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 <class FormatT, class... Indices>
template <SizeT... Is>
@ -147,9 +147,9 @@ namespace CNORXZ
}
}
/***************
* GMIndex *
***************/
/*===============+
| GMIndex |
+===============*/
template <class FormatT, class... Indices>
constexpr GMIndex<FormatT,Indices...>::GMIndex(const GMIndex& i) :
@ -613,15 +613,6 @@ namespace CNORXZ
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>
constexpr decltype(auto) mindex(const Sptr<Indices>&... is)
{
@ -652,9 +643,9 @@ namespace CNORXZ
return iptrMul(a, b);
}
/*********************
* MRangeFactory *
*********************/
/*=====================+
| MRangeFactory |
+=====================*/
template <class... Ranges>
MRangeFactory<Ranges...>::MRangeFactory(const Tuple<Sptr<Ranges>...>& rs) :
@ -683,9 +674,9 @@ namespace CNORXZ
}
}
/**************
* MRange *
**************/
/*==============+
| MRange |
+==============*/
template <class... Ranges>
MRange<Ranges...>::MRange(const Tuple<Sptr<Ranges>...>& rs) :
@ -703,7 +694,6 @@ namespace CNORXZ
template <class... Ranges>
MArray<RangePtr> MRange<Ranges...>::sub() const
{
// TODO: ZRange (meta and index pos static!)
if constexpr(NR == 0) {
return MArray<RangePtr>();
}
@ -791,9 +781,9 @@ namespace CNORXZ
return k;
}
/************************
* MRange (private) *
************************/
/*========================+
| MRange (private) |
+========================*/
template <class... Ranges>
decltype(auto) MRange<Ranges...>::mkA() const
@ -802,9 +792,9 @@ namespace CNORXZ
[](const auto&... xs) { return Arr<RangePtr,NR> { xs... }; } );
}
/****************************
* non-member functions *
****************************/
/*============================+
| non-member functions |
+============================*/
template <class... Ranges>
RangePtr mrange(const Sptr<Ranges>&... rs)

View file

@ -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<Indices...>& pack);
/** Construct from index pack and format. */
constexpr GMIndex(const FormatT& format, const SPack<Indices...>& pack);
/** Construct from index pointers. */
constexpr GMIndex(const Sptr<Indices>&... is);
/** Construct from index pointers and format. */
constexpr GMIndex(const FormatT& format, const Sptr<Indices>&... 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<MIndex<Indices...>>& _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<MIndex<Indices...>>& mi);
/** Update index position according to the sub-indices. */
GMIndex& operator()();
/** Get index pack. */
const SPack<Indices...>& 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 <class BT1, class BT2, class... Indices>
decltype(auto) replaceFormat(const BT1& bs1, const Sptr<GMIndex<BT2,Indices...>>& gmi);
template <class... Indices>
struct index_has_const_size<MIndex<Indices...>>
/** ****
Specialization of index_has_const_size for GMIndex.
@see index_has_const_size
*/
template <class FormatT, class... Indices>
struct index_has_const_size<GMIndex<FormatT,Indices...>>
{ 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 * ...); };
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); };
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; };
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; };
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; };
/** ***
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>
constexpr decltype(auto) mindex(const Sptr<Indices>&... is);
/** Create MIndex from index pack.
@param pack Pack of input indices.
*/
template <class... Indices>
constexpr decltype(auto) mindex(const SPack<Indices...>& pack);
/** Create pointer to MIndex from index pack.
@param pack Pack of input indices.
*/
template <class... Indices>
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>
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>
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>
class MRangeFactory : public RangeFactoryBase
{
public:
/** Construct and setup factory.
@param rs Tuple of sub-ranges.
*/
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);
private:
@ -241,7 +333,11 @@ namespace CNORXZ
Tuple<Sptr<Ranges>...> mRs;
RangePtr mRef;
};
/** ****
Multi Range with compile-time fixed number of sub-ranges
of compile-time fixed type.
*/
template <class... Ranges>
class MRange : public RangeInterface<MRange<Ranges...>>
{
@ -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<Sptr<Ranges>...>& rs);
Tuple<Sptr<Ranges>...> mRs;
Arr<RangePtr,NR> mA;
Tuple<Sptr<Ranges>...> mRs; /**< Tuple of pointers to sub-ranges. */
Arr<RangePtr,NR> mA; /**< Array of abstract base pointers to sub-ranges. Redundant to mRs */
virtual Vector<Uuid> 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 <class... Ranges>
RangePtr mrange(const Sptr<Ranges>&... rs);
/** ****
Specialization of RangeCast for MRange.
@see RangeCast.
*/
template <class... Ranges>
struct RangeCast<MRange<Ranges...>>
{
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 ...);
};
}