From 4a80161f33b2158b61977a2e6ee705660bc0b19b Mon Sep 17 00:00:00 2001 From: Brett Date: Thu, 26 Sep 2024 02:53:11 -0400 Subject: [PATCH] docs --- CMakeLists.txt | 2 +- include/blt/std/iterator.h | 205 +++++++++++++++++++++++++++---------- 2 files changed, 152 insertions(+), 55 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 997dcec..44a26ae 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.20) include(cmake/color.cmake) -set(BLT_VERSION 0.21.2) +set(BLT_VERSION 0.21.3) set(BLT_TEST_VERSION 0.0.1) set(BLT_TARGET BLT) diff --git a/include/blt/std/iterator.h b/include/blt/std/iterator.h index 79c1411..c1f0119 100644 --- a/include/blt/std/iterator.h +++ b/include/blt/std/iterator.h @@ -41,7 +41,10 @@ namespace blt template> class enumerate_wrapper; - // struct which is returned by the enumerator + /** + * struct which is returned by the enumerator. + * @tparam T type to store. + */ template struct enumerate_item { @@ -49,6 +52,11 @@ namespace blt T value; }; + /** + * base class for iterators which operate on pairs of values. Handles comparison. + * @tparam Iter1 first iterator type. this will be used for comparison. + * @tparam Iter2 second iterator type. this value is not modified by this class. + */ template class pair_iterator_base { @@ -81,6 +89,10 @@ namespace blt Iter2 m_iter2; }; + /** + * Base class for all enumerator iterators. Handles the deference (*) operator. + * @tparam Iter iterator type + */ template class enumerate_iterator_base : public pair_iterator_base { @@ -105,6 +117,10 @@ namespace blt } }; + /** + * Forward iterator base class for the enumerator. Contains the ++ operator. + * @tparam Iter iterator type. + */ template class enumerate_forward_iterator : public enumerate_iterator_base { @@ -126,6 +142,10 @@ namespace blt } }; + /** + * Bidirectional iterator base class for the enumerator. Contains the -- operator. + * @tparam Iter iterator type. + */ template class enumerate_bidirectional_iterator : public enumerate_forward_iterator { @@ -147,6 +167,10 @@ namespace blt } }; + /** + * Wrapper class specialization for forward iterators. + * @tparam Iter iterator type + */ template class enumerate_wrapper, std::void_t>> : public enumerate_forward_iterator @@ -162,6 +186,10 @@ namespace blt using enumerate_forward_iterator::enumerate_forward_iterator; }; + /** + * Wrapper class for bidirectional iterators or random access iterators. + * @tparam Iter iterator type. + */ template class enumerate_wrapper, std::void_t>> : public enumerate_bidirectional_iterator @@ -177,6 +205,11 @@ namespace blt using enumerate_bidirectional_iterator::enumerate_bidirectional_iterator; }; + /** + * Base class for the enumerator. Holds the begin and end iterators. + * @tparam Iter iterator type. + * @tparam IterWrapper wrapper used to iterate (enumerate_wrapper) + */ template class enumerator_base { @@ -196,12 +229,46 @@ namespace blt { return end_; } - + + /** + * Creates an enumerator that skips the first n elements. + * @param amount amount of values to skip. + */ + auto skip(blt::size_t amount) + { + auto begin = this->begin_; + for (blt::size_t i = 0; i < amount; i++) + ++begin; + return enumerator{begin.base(), + this->end_.base(), + begin.get_index(), + this->end_.get_index()}; + } + + /** + * Creates an enumerator that yields the first n elements, or UB if the underlying iterator ends sooner. + * @param amount amount to take. + */ + auto take(blt::size_t amount) + { + auto end = this->begin(); + for (blt::size_t i = 0; i < amount; i++) + ++end; + return enumerator{this->begin_.base(), + end.base(), + this->begin_.get_index(), + end.get_index()}; + } protected: IterWrapper begin_; IterWrapper end_; }; + /** + * Reversible (bidirectional) base class for the enumerator. + * @tparam Iter iterator type. + * @tparam IterWrapper wrapper used to iterate (enumerate_wrapper). + */ template class enumerator_reversible : public enumerator_base { @@ -216,6 +283,9 @@ namespace blt IterWrapper{enumerate_wrapper{std::move(end), end_index}}) {} + /** + * Reverses the enumerator’s direction. + */ auto rev() const { return enumerator_rev{this->end_.base(), @@ -223,30 +293,41 @@ namespace blt this->end_.get_index(), this->begin_.get_index()}; } + }; + + /** + * Random access base class for the enumerator. Has updated skip and take methods which make use of the random access nature of the iterator. + * @tparam Iter iterator type. + * @tparam IterWrapper wrapper used to iterate (enumerate_wrapper). + */ + template + class enumerator_random_access : public enumerator_reversible + { + public: + using enumerator_reversible::enumerator_reversible; auto skip(blt::size_t amount) { - auto begin = this->begin_; - for (blt::size_t i = 0; i < amount; i++) - ++begin; - return enumerator{begin.base(), + return enumerator{this->begin_.base() + amount, this->end_.base(), - begin.get_index(), + this->begin_.get_index() + amount, this->end_.get_index()}; } auto take(blt::size_t amount) { - auto end = this->begin(); - for (blt::size_t i = 0; i < amount; i++) - ++end; return enumerator{this->begin_.base(), - end.base(), + this->begin_.base() + amount, this->begin_.get_index(), - end.get_index()}; + this->begin_.get_index() + amount}; } }; + /** + * Reversible (bidirectional) base class for the enumerator, operates in reverse for reverse enumeration. + * @tparam Iter iterator type. + * @tparam IterWrapper wrapper used to iterate (std::reverse_iterator). + */ template class enumerator_reversible_rev : public enumerator_reversible { @@ -284,8 +365,42 @@ namespace blt end.get_index()}; } }; + + /** + * Random access base class for the enumerator. Has updated skip and take methods which make use of the random access nature of the iterator. + * Operates in reverse for reverse enumeration. + * @tparam Iter iterator type. + * @tparam IterWrapper wrapper used to iterate (std::reverse_iterator). + */ + template + class enumerator_random_access_rev : public enumerator_reversible_rev + { + public: + using enumerator_reversible_rev::enumerator_reversible_rev; + + auto skip(blt::size_t amount) + { + return enumerator_rev{this->begin_.base().base() - amount, + this->end_.base().base(), + this->begin_.base().get_index() - amount, + this->end_.base().get_index()}; + } + + auto take(blt::size_t amount) + { + return enumerator_rev{this->begin_.base().base(), + this->begin_.base().base() - amount, + this->begin_.base().get_index(), + this->begin_.base().get_index() - amount}; + } + }; + + } + /** + * Enumerator specialization for forward iterators + */ template class enumerator, std::void_t>> : public iterator::enumerator_base> @@ -294,6 +409,9 @@ namespace blt using iterator::enumerator_base>::enumerator_base; }; + /** + * Enumerator specialization for bidirectional iterators + */ template class enumerator, std::void_t>> : public iterator::enumerator_reversible> @@ -302,30 +420,20 @@ namespace blt using iterator::enumerator_reversible>::enumerator_reversible; }; + /** + * Enumerator specialization for random access iterators + */ template class enumerator, std::void_t>> - : public iterator::enumerator_reversible> + : public iterator::enumerator_random_access> { public: - using iterator::enumerator_reversible>::enumerator_reversible; - - auto skip(blt::size_t amount) - { - return enumerator{this->begin_.base() + amount, - this->end_.base(), - this->begin_.get_index() + amount, - this->end_.get_index()}; - } - - auto take(blt::size_t amount) - { - return enumerator{this->begin_.base(), - this->begin_.base() + amount, - this->begin_.get_index(), - this->begin_.get_index() + amount}; - } + using iterator::enumerator_random_access>::enumerator_random_access; }; + /** + * Reverse enumerator specialization for bidirectional iterators + */ template class enumerator_rev, std::void_t>> : public iterator::enumerator_reversible_rev>> @@ -334,30 +442,19 @@ namespace blt using iterator::enumerator_reversible_rev>>::enumerator_reversible_rev; }; + /** + * Reverse enumerator specialization for random access iterators + */ template class enumerator_rev, std::void_t>> - : public iterator::enumerator_reversible_rev>> + : public iterator::enumerator_random_access_rev>> { public: - using iterator::enumerator_reversible_rev>>::enumerator_reversible_rev; - - auto skip(blt::size_t amount) - { - return enumerator_rev{this->begin_.base().base() - amount, - this->end_.base().base(), - this->begin_.base().get_index() - amount, - this->end_.base().get_index()}; - } - - auto take(blt::size_t amount) - { - return enumerator_rev{this->begin_.base().base(), - this->begin_.base().base() - amount, - this->begin_.base().get_index(), - this->begin_.base().get_index() - amount}; - } + using iterator::enumerator_random_access_rev>>::enumerator_random_access_rev; }; + // CTAD for enumerators + template enumerator(Iter, Iter) -> enumerator; @@ -367,12 +464,6 @@ namespace blt template enumerator(Iter, Iter, blt::size_t, blt::size_t) -> enumerator; - template - static inline auto enumerate(const T& container) - { - return enumerator{container.begin(), container.end(), container.size()}; - } - template static inline auto enumerate(const T(& container)[size]) { @@ -397,6 +488,12 @@ namespace blt return enumerator{container.begin(), container.end(), container.size()}; } + template + static inline auto enumerate(const T& container) + { + return enumerator{container.begin(), container.end(), container.size()}; + } + } #endif //BLT_ITERATOR_H