From 21a11eb4f633b39e52407ff63bed23aa5c80ba5f Mon Sep 17 00:00:00 2001 From: Christian Zimmermann Date: Fri, 19 Jan 2024 23:32:41 +0100 Subject: [PATCH] ranges: add remaining doxy comments --- src/include/ranges/srange.h | 114 ++++++++++++++++++++++++++-- src/include/ranges/urange.h | 113 +++++++++++++++++++++++---- src/include/ranges/xindex.h | 147 ++++++++++++++++++++++++++++++------ 3 files changed, 326 insertions(+), 48 deletions(-) diff --git a/src/include/ranges/srange.h b/src/include/ranges/srange.h index ea18367..5cf1661 100644 --- a/src/include/ranges/srange.h +++ b/src/include/ranges/srange.h @@ -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 class SIndex : public IndexInterface,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 pmax() const; + + /** @copydoc IndexInterface::lmax() */ SPos 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 range() const; + /** @copydoc IndexInterface::stepSize() */ template UPos stepSize(const IndexId& id) const; + /** @copydoc IndexInterface::stringMeta() */ String stringMeta() const; - const MetaT& meta() const; - SIndex& at(const MetaT& metaPos); - decltype(auto) xpr(const Sptr>& _this) const; + /** @copydoc IndexInterface::meta() */ + const MetaT& meta() const; + + /** @copydoc IndexInterface::at() */ + SIndex& at(const MetaT& metaPos); + + /** @copydoc IndexInterface::prange() */ RangePtr prange(const SIndex& last) const; + + /** @copydoc IndexInterface::deepFormat() */ SizeT deepFormat() const; + + /** @copydoc IndexInterface::deepMax() */ SizeT deepMax() const; /** @copydoc IndexInterface::reformat() */ SIndex& reformat(const Vector& f, const Vector& s); + /** @copydoc IndexInterface::ifor() */ + decltype(auto) xpr(const Sptr>& _this) const; + + /** @copydoc IndexInterface::ifor() */ template 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 decltype(auto) operator*(const Sptr>& a, const Sptr& b); + /** **** + Specific factory for SRange. + @tparam MetaT Meta data type. + @tparam S Static size of the range. + */ template class SRangeFactory : public RangeFactoryBase { public: + + /** Construct and setup factory. + @param space Meta data array defining the range. + */ SRangeFactory(const Arr& space); + + /** Construct and setup factory. + @param space Meta data array defining the range (move). + */ SRangeFactory(Arr&& 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& 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&& 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 class SRange : public RangeInterface> { @@ -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 struct RangeCast> { + /** cast the range */ static Sptr> func(const RangePtr& r); }; diff --git a/src/include/ranges/urange.h b/src/include/ranges/urange.h index 8357503..c046081 100644 --- a/src/include/ranges/urange.h +++ b/src/include/ranges/urange.h @@ -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 class UIndex : public IndexInterface,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 range() const; + /** @copydoc IndexInterface::stepSize() */ template decltype(auto) stepSize(const IndexId& id) const; + /** @copydoc IndexInterface::stringMeta() */ String stringMeta() const; - const MetaT& meta() const; - UIndex& at(const MetaT& metaPos); - decltype(auto) xpr(const Sptr>& _this) const; + /** @copydoc IndexInterface::meta() */ + const MetaT& meta() const; + + /** @copydoc IndexInterface::at() */ + UIndex& at(const MetaT& metaPos); + + /** @copydoc IndexInterface::prange() */ RangePtr prange(const UIndex& last) const; + /** @copydoc IndexInterface::deepFormat() */ SizeT deepFormat() const; + /** @copydoc IndexInterface::deepMax() */ SizeT deepMax() const; - + /** @copydoc IndexInterface::reformat() */ UIndex& reformat(const Vector& f, const Vector& s); + /** @copydoc IndexInterface::ifor() */ template 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; + private: Sptr mRangePtr; const MetaT* mMetaPtr; @@ -86,26 +132,39 @@ namespace CNORXZ template void swap(UIndex& a, UIndex& b) { a.swap(b); } - template - decltype(auto) operator*(const Sptr>& a, const Sptr& b); + /** Make index pack of a UIndex and another index. + @param a pointer to UIndex. + @param b pointer to another index. + */ + template + decltype(auto) operator*(const Sptr>& a, const Sptr& b); - template + /** **** + Specific factory for URange. + @tparam MetaT Meta data type. + */ + template class URangeFactory : public RangeFactoryBase { public: - URangeFactory(const Vector& space); - URangeFactory(Vector&& space); - URangeFactory(const Vector& space, const RangePtr& ref); - URangeFactory(Vector&& space, const RangePtr& ref); + URangeFactory(const Vector& space); + URangeFactory(Vector&& space); + URangeFactory(const Vector& space, const RangePtr& ref); + URangeFactory(Vector&& space, const RangePtr& ref); private: URangeFactory() = default; virtual void make() override final; - Vector mSpace; + Vector 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 class URange : public RangeInterface> { @@ -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 struct RangeCast> { + /** cast the range */ static Sptr> func(const RangePtr& r); }; + /** Create an URange, calls URangeFactory. + @param space Meta data space to create an URange on. + @return Created range. + */ template RangePtr urange(const Vector& space); diff --git a/src/include/ranges/xindex.h b/src/include/ranges/xindex.h index bbb9411..e8d3000 100644 --- a/src/include/ranges/xindex.h +++ b/src/include/ranges/xindex.h @@ -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 deepFormat() const = 0; - virtual Vector deepMax() const = 0; - virtual XIndexBase& reformat(const Vector& f, const Vector& 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 deepFormat() const = 0; + + /** @copydoc IndexInterface::deepMax() */ + virtual Vector deepMax() const = 0; + + /** @copydoc IndexInterface::reformat() */ + virtual XIndexBase& reformat(const Vector& f, const Vector& s) = 0; + + /** @copydoc IndexInterface::ifor() */ virtual DXpr ifor(const DXpr& xpr, NoF&& f) const = 0; + /** @copydoc IndexInterface::formatIsTrivial() */ virtual bool formatIsTrivial() const = 0; }; - //Sptr& operator++(Sptr& i); - //Sptr& operator--(Sptr& i); - - // MultiIndex Wrapper: + /** **** + Index Wrapper. + @tparam Index Type of index to be wrapped. + @tparam Meta Meta data type of wrapped index. + */ template 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& i); + + /** Construct. + @param i Index to be wrapped. + */ XIndex(const IndexInterface& 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 deepFormat() const override final; virtual Vector deepMax() const override final; virtual XIndex& reformat(const Vector& f, const Vector& 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 ifor(const DXpr& 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 { static constexpr bool value = true; }; - + + /** Create XIndex pointer. + @param i Index to be wrapped. + @return Pointer to created index wrapper. + */ template inline XIndexPtr xindexPtr(const Sptr& 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(const Sptr& i);