ranges: add remaining doxy comments
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful

This commit is contained in:
Christian Zimmermann 2024-01-19 23:32:41 +01:00
parent a5031d80b1
commit 21a11eb4f6
3 changed files with 326 additions and 48 deletions

View file

@ -2,10 +2,9 @@
/**
@file include/ranges/srange.h
@brief ...
@brief SRange, SRangeFactory and SIndex declaration.
Copyright (c) 2022 Christian Zimmermann. All rights reserved.
Copyright (c) 2024 Christian Zimmermann. All rights reserved.
Mail: chizeta@f3l.de
**/
@ -20,6 +19,11 @@
namespace CNORXZ
{
/** ****
Specific index for SRange.
@tparam MetaT Meta data type.
@tparam S Static size of the range.
*/
template <typename MetaT, SizeT S>
class SIndex : public IndexInterface<SIndex<MetaT,S>,MetaT>
{
@ -29,43 +33,88 @@ namespace CNORXZ
typedef MetaT MetaType;
INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType);
DEFAULT_MEMBERS(SIndex);
DEFAULT_MEMBERS(SIndex); /**< default constructors and assignments */
/** Construct index from range and position.
@param range Range to iterate over.
@param pos lexicographic position.
*/
SIndex(const RangePtr& range, SizeT pos = 0);
/** @copydoc IndexInterface::operator=(SizeT) */
SIndex& operator=(SizeT lexpos);
/** @copydoc IndexInterface::operator++() */
SIndex& operator++();
/** @copydoc IndexInterface::operator--() */
SIndex& operator--();
/** @copydoc IndexInterface::operator+() */
SIndex operator+(Int n) const;
/** @copydoc IndexInterface::operator-() */
SIndex operator-(Int n) const;
/** @copydoc IndexInterface::operator-(SIndex) */
SizeT operator-(const SIndex& i) const;
/** @copydoc IndexInterface::operator+=() */
SIndex& operator+=(Int n);
/** @copydoc IndexInterface::operator-=() */
SIndex& operator-=(Int n);
/** @copydoc IndexInterface::lex() */
SizeT lex() const;
/** @copydoc IndexInterface::pmax() */
SPos<S> pmax() const;
/** @copydoc IndexInterface::lmax() */
SPos<S> lmax() const;
/** @copydoc IndexInterface::id() */
IndexId<0> id() const;
/** @copydoc IndexInterface::operator*() */
const MetaT& operator*() const;
/** @copydoc IndexInterface::dim() */
SizeT dim() const; // = 1
/** @copydoc IndexInterface::range() */
Sptr<RangeType> range() const;
/** @copydoc IndexInterface::stepSize() */
template <SizeT I>
UPos stepSize(const IndexId<I>& id) const;
/** @copydoc IndexInterface::stringMeta() */
String stringMeta() const;
const MetaT& meta() const;
SIndex& at(const MetaT& metaPos);
decltype(auto) xpr(const Sptr<SIndex<MetaType,S>>& _this) const;
/** @copydoc IndexInterface::meta() */
const MetaT& meta() const;
/** @copydoc IndexInterface::at() */
SIndex& at(const MetaT& metaPos);
/** @copydoc IndexInterface::prange() */
RangePtr prange(const SIndex<MetaType,S>& last) const;
/** @copydoc IndexInterface::deepFormat() */
SizeT deepFormat() const;
/** @copydoc IndexInterface::deepMax() */
SizeT deepMax() const;
/** @copydoc IndexInterface::reformat() */
SIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s);
/** @copydoc IndexInterface::ifor() */
decltype(auto) xpr(const Sptr<SIndex<MetaType,S>>& _this) const;
/** @copydoc IndexInterface::ifor() */
template <class Xpr, class F>
decltype(auto) ifor(const Xpr& xpr, F&& f) const;
@ -77,16 +126,43 @@ namespace CNORXZ
const MetaT* mMetaPtr;
};
/** Make index pack of a SIndex and another index.
@param a pointer to SIndex.
@param b pointer to another index.
*/
template <typename MetaT, SizeT S, class I1>
decltype(auto) operator*(const Sptr<SIndex<MetaT,S>>& a, const Sptr<I1>& b);
/** ****
Specific factory for SRange.
@tparam MetaT Meta data type.
@tparam S Static size of the range.
*/
template <typename MetaT, SizeT S>
class SRangeFactory : public RangeFactoryBase
{
public:
/** Construct and setup factory.
@param space Meta data array defining the range.
*/
SRangeFactory(const Arr<MetaT,S>& space);
/** Construct and setup factory.
@param space Meta data array defining the range (move).
*/
SRangeFactory(Arr<MetaT,S>&& space);
/** Construct and setup factory.
@param space Meta data array defining the range.
@param ref Range the range to be constructed is related to.
*/
SRangeFactory(const Arr<MetaT,S>& space, const RangePtr& ref);
/** Construct and setup factory.
@param space Meta data array defining the range (move).
@param ref Range the range to be constructed is related to.
*/
SRangeFactory(Arr<MetaT,S>&& space, const RangePtr& ref);
private:
@ -97,6 +173,12 @@ namespace CNORXZ
RangePtr mRef;
};
/** ****
Static size range.
The same as URange, but the range size is compile-time fixed.
@tparam MetaT Meta data type.
@tparam S Static range size.
*/
template <typename MetaT, SizeT S>
class SRange : public RangeInterface<SRange<MetaT,S>>
{
@ -114,8 +196,19 @@ namespace CNORXZ
virtual const TypeInfo& metaType() const override final;
virtual RangePtr extend(const RangePtr& r) const override final;
/** return meta data at given position.
@param pos position, size type
*/
const MetaT& get(SizeT pos) const;
/** Get underlying meta data array.
@return Pointer to first position of meta data array.
*/
const MetaT* get() const;
/** return position for given meta data.
@param metaPos meta data, size type
*/
SizeT getMeta(const MetaT& metaPos) const;
private:
@ -132,9 +225,16 @@ namespace CNORXZ
SERIALIZATION_FUNCTIONS_NOPUB;
};
/** ***
Specialize RangeCast for casts to SRange
@see RangeCast
@tparam MetaT Meta data type.
@tparam S Static range size.
*/
template <typename MetaT, SizeT S>
struct RangeCast<SRange<MetaT,S>>
{
/** cast the range */
static Sptr<SRange<MetaT,S>> func(const RangePtr& r);
};

View file

@ -2,10 +2,9 @@
/**
@file include/ranges/urange.h
@brief ...
@brief URange, URangeFactory and UIndex declaration.
Copyright (c) 2022 Christian Zimmermann. All rights reserved.
Copyright (c) 2024 Christian Zimmermann. All rights reserved.
Mail: chizeta@f3l.de
**/
@ -23,6 +22,10 @@
namespace CNORXZ
{
/** ****
Specific index for URange.
@tparam MetaT Meta data type.
*/
template <typename MetaT>
class UIndex : public IndexInterface<UIndex<MetaT>,MetaT>
{
@ -33,51 +36,94 @@ namespace CNORXZ
typedef MetaT MetaType;
INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType);
DEFAULT_MEMBERS(UIndex);
DEFAULT_MEMBERS(UIndex); /**< default constructors and assignments */
/** Construct index from range and position.
@param range Range to iterate over.
@param pos lexicographic position.
*/
UIndex(const RangePtr& range, SizeT pos = 0);
/** @copydoc IndexInterface::operator=(SizeT) */
UIndex& operator=(SizeT lexpos);
/** @copydoc IndexInterface::operator++() */
UIndex& operator++();
/** @copydoc IndexInterface::operator--() */
UIndex& operator--();
/** @copydoc IndexInterface::operator+() */
UIndex operator+(Int n) const;
/** @copydoc IndexInterface::operator-() */
UIndex operator-(Int n) const;
/** @copydoc IndexInterface::operator-(UIndex) */
SizeT operator-(const UIndex& i) const;
/** @copydoc IndexInterface::operator+=() */
UIndex& operator+=(Int n);
/** @copydoc IndexInterface::operator-=() */
UIndex& 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*() */
const MetaT& operator*() const;
/** @copydoc IndexInterface::dim() */
SizeT dim() const; // = 1
/** @copydoc IndexInterface::range() */
Sptr<RangeType> range() const;
/** @copydoc IndexInterface::stepSize() */
template <SizeT I>
decltype(auto) stepSize(const IndexId<I>& id) const;
/** @copydoc IndexInterface::stringMeta() */
String stringMeta() const;
const MetaT& meta() const;
UIndex& at(const MetaT& metaPos);
decltype(auto) xpr(const Sptr<UIndex<MetaType>>& _this) const;
/** @copydoc IndexInterface::meta() */
const MetaT& meta() const;
/** @copydoc IndexInterface::at() */
UIndex& at(const MetaT& metaPos);
/** @copydoc IndexInterface::prange() */
RangePtr prange(const UIndex<MetaType>& last) const;
/** @copydoc IndexInterface::deepFormat() */
SizeT deepFormat() const;
/** @copydoc IndexInterface::deepMax() */
SizeT deepMax() const;
/** @copydoc IndexInterface::reformat() */
UIndex& 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;
/** @copydoc IndexInterface::formatIsTrivial() */
bool formatIsTrivial() const;
/** @copydoc IndexInterface::xpr() */
decltype(auto) xpr(const Sptr<UIndex<MetaType>>& _this) const;
private:
Sptr<RangeType> mRangePtr;
const MetaT* mMetaPtr;
@ -86,26 +132,39 @@ namespace CNORXZ
template <typename MetaT>
void swap(UIndex<MetaT>& a, UIndex<MetaT>& b) { a.swap(b); }
template <typename MetaType, class I1>
decltype(auto) operator*(const Sptr<UIndex<MetaType>>& a, const Sptr<I1>& b);
/** Make index pack of a UIndex and another index.
@param a pointer to UIndex.
@param b pointer to another index.
*/
template <typename MetaT, class I1>
decltype(auto) operator*(const Sptr<UIndex<MetaT>>& a, const Sptr<I1>& b);
template <typename MetaType>
/** ****
Specific factory for URange.
@tparam MetaT Meta data type.
*/
template <typename MetaT>
class URangeFactory : public RangeFactoryBase
{
public:
URangeFactory(const Vector<MetaType>& space);
URangeFactory(Vector<MetaType>&& space);
URangeFactory(const Vector<MetaType>& space, const RangePtr& ref);
URangeFactory(Vector<MetaType>&& space, const RangePtr& ref);
URangeFactory(const Vector<MetaT>& space);
URangeFactory(Vector<MetaT>&& space);
URangeFactory(const Vector<MetaT>& space, const RangePtr& ref);
URangeFactory(Vector<MetaT>&& space, const RangePtr& ref);
private:
URangeFactory() = default;
virtual void make() override final;
Vector<MetaType> mSpace;
Vector<MetaT> mSpace;
RangePtr mRef;
};
/** ****
Uni-(1-)dimensional range with non-trivial meta data space
i.e. the parameter space can be arbitrary.
@tparam MetaT Meta data type.
*/
template <typename MetaT>
class URange : public RangeInterface<URange<MetaT>>
{
@ -123,8 +182,21 @@ namespace CNORXZ
virtual const TypeInfo& metaType() const override final;
virtual RangePtr extend(const RangePtr& r) const override final;
/** Get meta data at given range position.
@param pos Integer indicating requested position.
@return Meta data at given postion.
*/
const MetaType& get(SizeT pos) const;
/** Get meta data array.
@return Pointer to first element of the underlying meta data array.
*/
const MetaType* get() const;
/** Get range position for given meta data.
@param metaPos Meta data.
@return Position of the given meta data if it is contained by the range.
*/
SizeT getMeta(const MetaType& metaPos) const;
private:
@ -141,12 +213,21 @@ namespace CNORXZ
SERIALIZATION_FUNCTIONS_NOPUB;
};
/** ***
Specialize RangeCast for casts to URange
@see RangeCast
*/
template <typename MetaType>
struct RangeCast<URange<MetaType>>
{
/** cast the range */
static Sptr<URange<MetaType>> func(const RangePtr& r);
};
/** Create an URange, calls URangeFactory.
@param space Meta data space to create an URange on.
@return Created range.
*/
template <typename MetaT>
RangePtr urange(const Vector<MetaT>& space);

View file

@ -2,10 +2,9 @@
/**
@file include/ranges/xindex.h
@brief ...
@brief XIndexBase and XIndex template declaration.
Copyright (c) 2022 Christian Zimmermann. All rights reserved.
Copyright (c) 2024 Christian Zimmermann. All rights reserved.
Mail: chizeta@f3l.de
**/
@ -20,66 +19,145 @@
namespace CNORXZ
{
/** ****
Abstract index wrapper base.
Can be used for index polymorphism.
Only use if absolutely necessary, indices should always reveal as much as possible
to the compiler!
*/
class XIndexBase
{
public:
//typedef DType MetaType;
DEFAULT_MEMBERS(XIndexBase);
DEFAULT_MEMBERS(XIndexBase); /**< default constructors and assignments */
/** Virtual default destructor */
virtual ~XIndexBase() = default;
/** Copy this index
@return Pointer to the copy.
*/
virtual XIndexPtr copy() const = 0;
/** Current position.
@return Current position.
*/
virtual SizeT pos() const = 0;
/** @copydoc IndexInterface::operator=(SizeT) */
virtual XIndexBase& operator=(SizeT lexpos) = 0;
/** @copydoc IndexInterface::operator++() */
virtual XIndexBase& operator++() = 0;
/** @copydoc IndexInterface::operator--() */
virtual XIndexBase& operator--() = 0;
/** @copydoc IndexInterface::operator+() */
virtual XIndexPtr operator+(Int n) const = 0;
/** @copydoc IndexInterface::operator-() */
virtual XIndexPtr operator-(Int n) const = 0;
/** @copydoc IndexInterface::operator-(UIndex) */
virtual SizeT operator-(const XIndexBase& i) const = 0;
/** @copydoc IndexInterface::operator+=() */
virtual XIndexBase& operator+=(Int n) = 0;
/** @copydoc IndexInterface::operator-=() */
virtual XIndexBase& operator-=(Int n) = 0;
/** @copydoc IndexInterface::lex() */
virtual SizeT lex() const = 0;
/** @copydoc IndexInterface::pmax() */
virtual UPos pmax() const = 0;
/** @copydoc IndexInterface::lmax() */
virtual UPos lmax() const = 0;
/** @copydoc IndexInterface::id() */
virtual IndexId<0> id() const = 0;
/** @copydoc IndexInterface::operator*() */
virtual DType operator*() const = 0;
/** @copydoc IndexInterface::dim() */
virtual SizeT dim() const = 0;
virtual RangePtr range() const = 0;
virtual UPos stepSize(const IndexId<0>& id) const = 0;
virtual RangePtr prange(const XIndexPtr& last) const = 0;
virtual Vector<SizeT> deepFormat() const = 0;
virtual Vector<SizeT> deepMax() const = 0;
virtual XIndexBase& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s) = 0;
/** @copydoc IndexInterface::range() */
virtual RangePtr range() const = 0;
/** @copydoc IndexInterface::stepSize() */
virtual UPos stepSize(const IndexId<0>& id) const = 0;
/** @copydoc IndexInterface::stringMeta() */
virtual String stringMeta() const = 0;
/** @copydoc IndexInterface::meta() */
virtual DType meta() const = 0;
/** @copydoc IndexInterface::at() */
virtual XIndexBase& at(const DType& meta) = 0;
/** @copydoc IndexInterface::prange() */
virtual RangePtr prange(const XIndexPtr& last) const = 0;
/** @copydoc IndexInterface::deepFormat() */
virtual Vector<SizeT> deepFormat() const = 0;
/** @copydoc IndexInterface::deepMax() */
virtual Vector<SizeT> deepMax() const = 0;
/** @copydoc IndexInterface::reformat() */
virtual XIndexBase& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s) = 0;
/** @copydoc IndexInterface::ifor() */
virtual DXpr<None> ifor(const DXpr<None>& xpr, NoF&& f) const = 0;
/** @copydoc IndexInterface::formatIsTrivial() */
virtual bool formatIsTrivial() const = 0;
};
//Sptr<XIndexBase>& operator++(Sptr<XIndexBase>& i);
//Sptr<XIndexBase>& operator--(Sptr<XIndexBase>& i);
// MultiIndex Wrapper:
/** ****
Index Wrapper.
@tparam Index Type of index to be wrapped.
@tparam Meta Meta data type of wrapped index.
*/
template <class Index, typename Meta>
class XIndex : public XIndexBase
{
public:
DEFAULT_C(XIndex);
// no default copy/assignment (have to copy objects in shared ptr)
DEFAULT_C(XIndex); /** < default constructor. */
/** Copy constructor.
No default: have to copy objects in shared ptr.
*/
XIndex(const XIndex& i);
/** Move constructor.
*/
XIndex(XIndex&& i);
/** Copy assignment.
No default: have to copy objects in shared ptr.
*/
XIndex& operator=(const XIndex& i);
/** Move assignment.
*/
XIndex& operator=(XIndex&& i);
/** Construct.
@param i Pointer to index to be wrapped.
*/
XIndex(const IndexPtr<Index,Meta>& i);
/** Construct.
@param i Index to be wrapped.
*/
XIndex(const IndexInterface<Index,Meta>& i);
virtual XIndexPtr copy() const override final;
@ -104,20 +182,24 @@ namespace CNORXZ
virtual SizeT dim() const override final;
virtual RangePtr range() const override final;
virtual UPos stepSize(const IndexId<0>& id) const override final;
virtual String stringMeta() const override final;
virtual DType meta() const override final;
virtual XIndexBase& at(const DType& meta) override final;
virtual RangePtr prange(const XIndexPtr& last) const override final;
virtual Vector<SizeT> deepFormat() const override final;
virtual Vector<SizeT> deepMax() const override final;
virtual XIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s) override final;
virtual String stringMeta() const override final;
virtual DType meta() const override final;
virtual XIndexBase& at(const DType& meta) override final;
virtual DXpr<None> ifor(const DXpr<None>& xpr, NoF&& f) const override final;
virtual bool formatIsTrivial() const override final;
/** Get underlying index instance.
@return Reference to index.
*/
Index& get();
/** Get underlying index instance (const).
@return Reference to index.
*/
const Index& get() const;
private:
@ -125,13 +207,28 @@ namespace CNORXZ
};
/** ****
Specialization: has_sub for XIndexBase.
XIndexBase can have sub-indices.
@see has_sub.
*/
template <>
struct has_sub<XIndexBase>
{ static constexpr bool value = true; };
/** Create XIndex pointer.
@param i Index to be wrapped.
@return Pointer to created index wrapper.
*/
template <class Index>
inline XIndexPtr xindexPtr(const Sptr<Index>& i);
/** Specialization of xindexPtr().
If input index type is already a XIndex, the corresponding pointer is just passed.
This is to avoid unwanted chains of index wrappers.
@param i Input index.
@return i.
*/
template <>
inline XIndexPtr xindexPtr<XIndexBase>(const Sptr<XIndexBase>& i);