From 170fa5ce4aed638ab1572d4160736d0f2cb722e6 Mon Sep 17 00:00:00 2001 From: fktn Date: Tue, 7 Jan 2025 08:09:38 +0900 Subject: [PATCH] added doxygen comments again --- include/fkYAML/detail/map_range_proxy.hpp | 66 +++++++++++++ include/fkYAML/detail/reverse_iterator.hpp | 44 +++++++++ single_include/fkYAML/node.hpp | 110 +++++++++++++++++++++ 3 files changed, 220 insertions(+) diff --git a/include/fkYAML/detail/map_range_proxy.hpp b/include/fkYAML/detail/map_range_proxy.hpp index fa8fd862..27020ce2 100644 --- a/include/fkYAML/detail/map_range_proxy.hpp +++ b/include/fkYAML/detail/map_range_proxy.hpp @@ -14,67 +14,110 @@ FK_YAML_DETAIL_NAMESPACE_BEGIN +/// @brief A helper iterator class which wraps a mapping iterator object. +/// @tparam Iterator The base iterator type. template class map_iterator_proxy { public: + /// @brief The type of the pointed-to elements by base iterators. using value_type = Iterator; + + /// @brief The type to represent difference between the pointed-to elements by base iterators. using difference_type = std::ptrdiff_t; + + /// @brief The type of the pointed-to element references by base iterators. using reference = value_type&; + + /// @brief The type of the pointed-to element pointers by base iterators. using pointer = value_type*; + + /// @brief The iterator category. using iterator_category = std::forward_iterator_tag; + /// @brief Constructs a map_iterator_proxy object. map_iterator_proxy() = default; + /// @brief Constructs a map_iterator_proxy object with an Iterator object. + /// @param i A base iterator object. map_iterator_proxy(const Iterator& i) noexcept : m_base_iterator(i) { } + /// @brief Copy constructs a map_iterator_proxy object. map_iterator_proxy(const map_iterator_proxy&) = default; + + /// @brief Copy assigns a map_iterator_proxy object. map_iterator_proxy& operator=(const map_iterator_proxy&) = default; + + /// @brief Move constructs a map_iterator_proxy object. map_iterator_proxy(map_iterator_proxy&&) = default; + + /// @biref Move assigns a map_iterator_proxy object. map_iterator_proxy& operator=(map_iterator_proxy&&) = default; + /// @brief Destructs a map_iterator_proxy object. ~map_iterator_proxy() = default; + /// @brief Get reference to the base iterator object. + /// @return Reference to the base iterator object. reference operator*() noexcept { return m_base_iterator; } + /// @brief Get pointer to the base iterator object. + /// @return Pointer to the base iterator object. pointer operator->() noexcept { return &m_base_iterator; } + /// @brief Pre-increments the base iterator object. + /// @return Reference to this map_iterator_proxy object. map_iterator_proxy& operator++() noexcept { ++m_base_iterator; return *this; } + /// @brief Post-increments the base iterator object. + /// @return A map_iterator_proxy object with its base iterator incremented. map_iterator_proxy operator++(int) & noexcept { auto result = *this; ++(*this); return result; } + /// @brief Check equality between map_iterator_proxy objects. + /// @param rhs A map_iterator_proxy object to compare with. + /// @return true if this map_iterator_proxy object is equal to `rhs`, false otherwise. bool operator==(const map_iterator_proxy& rhs) const noexcept { return m_base_iterator == rhs.m_base_iterator; } + /// @brief Check inequality between map_iterator_proxy objects. + /// @param rhs A map_iterator_proxy object to compare with. + /// @return true if this map_iterator_proxy object is not equal to `rhs`, false otherwise. bool operator!=(const map_iterator_proxy& rhs) const noexcept { return m_base_iterator != rhs.m_base_iterator; } + /// @brief Get the mapping key node pointed by the base iterator. + /// @return Reference to the mapping key node. typename Iterator::reference key() const { return m_base_iterator.key(); } + /// @brief Get the mapping value node pointed by the base iterator. + /// @return Reference to the mapping value node. typename Iterator::reference value() const noexcept { return m_base_iterator.value(); } private: + /// The base iterator object. Iterator m_base_iterator {}; }; +/// @brief A helper struct which allows accessing node iterator member functions in range-based for loops. +/// @tparam BasicNodeType A basic_node template instance type. template class map_range_proxy { static_assert( @@ -82,40 +125,63 @@ class map_range_proxy { "map_range_proxy only accepts a basic_node type as its template parameter."); public: + /// @brief The type of non-const iterators. using iterator = map_iterator_proxy::value, typename BasicNodeType::const_iterator, typename BasicNodeType::iterator>::type>; + /// @brief The type of const iterators. using const_iterator = map_iterator_proxy; + /// @brief Constructs a map_range_proxy object with a BasicNodeType object. + /// @param map A mapping node object. map_range_proxy(BasicNodeType& map) noexcept : mp_map(&map) { } + /// @brief Copy constructs a map_range_proxy object. map_range_proxy(const map_range_proxy&) = default; + + /// @brief Copy assigns a map_range_proxy object. + /// @return Reference to this map_range_proxy object. map_range_proxy& operator=(const map_range_proxy&) = default; + + /// @brief Move constructs a map_range_proxy object. map_range_proxy(map_range_proxy&&) = default; + + /// @brief Move assigns a map_range_proxy object. + /// @return Reference to this map_range_proxy object. map_range_proxy& operator=(map_range_proxy&&) = default; + /// @brief Destructs a map_range_proxy object. ~map_range_proxy() = default; + /// @brief Get an iterator to the first element. + /// @return An iterator to the first element. iterator begin() noexcept { return {mp_map->begin()}; } + /// @brief Get a const iterator to the first element. + /// @return A const iterator to the first element. const_iterator begin() const noexcept { return {mp_map->cbegin()}; } + /// @brief Get an iterator to the past-the-last element. + /// @return An iterator to the past-the-last element. iterator end() noexcept { return {mp_map->end()}; } + /// @brief Get a const iterator to the past-the-last element. + /// @return A const iterator to the past-the-last element. const_iterator end() const noexcept { return {mp_map->cend()}; } private: + /// Pointer to the mapping node object. (non-null) BasicNodeType* mp_map {nullptr}; }; diff --git a/include/fkYAML/detail/reverse_iterator.hpp b/include/fkYAML/detail/reverse_iterator.hpp index ccd2db5a..da064e0e 100644 --- a/include/fkYAML/detail/reverse_iterator.hpp +++ b/include/fkYAML/detail/reverse_iterator.hpp @@ -64,11 +64,18 @@ class reverse_iterator { : m_current(i) { } + /// @brief Copy constructs a reverse_iterator object with a compatible reverse_iterator object. + /// @tparam U A compatible iterator type with Iterator. + /// @param other A compatible reverse_iterator object. template >::value, int> = 0> reverse_iterator(const reverse_iterator& other) noexcept : m_current(other.base()) { } + /// @brief Copy assigns a reverse_iterator object with a compatible reverse_iterator object. + /// @tparam U A compatible iterator type with Iterator. + /// @param other A compatible reverse_iterator object. + /// @return Reference to this reverse_iterator object. template >::value, int> = 0> reverse_iterator& operator=(const reverse_iterator& other) noexcept { m_current = other.base(); @@ -172,34 +179,71 @@ class reverse_iterator { } private: + /// Iterator m_current; }; +/// @brief Check equality between reverse_iterator objects. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if the two reverse_iterator objects are equal, false otherwise. template inline bool operator==(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() == rhs.base(); } +/// @brief Check inequality between reverse_iterator objects. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if the two reverse_iterator objects are not equal, false otherwise. template inline bool operator!=(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() != rhs.base(); } +/// @brief Check if `lhs` is less than `rhs`. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if `lhs` is less than `rhs`, false otherwise. template inline bool operator<(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() > rhs.base(); } +/// @brief Check if `lhs` is less than or equal to `rhs`. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if `lhs` is less than or equal to `rhs`, false otherwise. template inline bool operator<=(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() >= rhs.base(); } +/// @brief Check if `lhs` is greater than `rhs`. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if `lhs` is greater than `rhs`, false otherwise. template inline bool operator>(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() < rhs.base(); } +/// @brief Check if `lhs` is greater than or equal to `rhs`. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if `lhs` is greater than or equal to `rhs`, false otherwise. template inline bool operator>=(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() <= rhs.base(); diff --git a/single_include/fkYAML/node.hpp b/single_include/fkYAML/node.hpp index de6064eb..e6cd8d61 100644 --- a/single_include/fkYAML/node.hpp +++ b/single_include/fkYAML/node.hpp @@ -10220,67 +10220,110 @@ struct tuple_element> { FK_YAML_DETAIL_NAMESPACE_BEGIN +/// @brief A helper iterator class which wraps a mapping iterator object. +/// @tparam Iterator The base iterator type. template class map_iterator_proxy { public: + /// @brief The type of the pointed-to elements by base iterators. using value_type = Iterator; + + /// @brief The type to represent difference between the pointed-to elements by base iterators. using difference_type = std::ptrdiff_t; + + /// @brief The type of the pointed-to element references by base iterators. using reference = value_type&; + + /// @brief The type of the pointed-to element pointers by base iterators. using pointer = value_type*; + + /// @brief The iterator category. using iterator_category = std::forward_iterator_tag; + /// @brief Constructs a map_iterator_proxy object. map_iterator_proxy() = default; + /// @brief Constructs a map_iterator_proxy object with an Iterator object. + /// @param i A base iterator object. map_iterator_proxy(const Iterator& i) noexcept : m_base_iterator(i) { } + /// @brief Copy constructs a map_iterator_proxy object. map_iterator_proxy(const map_iterator_proxy&) = default; + + /// @brief Copy assigns a map_iterator_proxy object. map_iterator_proxy& operator=(const map_iterator_proxy&) = default; + + /// @brief Move constructs a map_iterator_proxy object. map_iterator_proxy(map_iterator_proxy&&) = default; + + /// @biref Move assigns a map_iterator_proxy object. map_iterator_proxy& operator=(map_iterator_proxy&&) = default; + /// @brief Destructs a map_iterator_proxy object. ~map_iterator_proxy() = default; + /// @brief Get reference to the base iterator object. + /// @return Reference to the base iterator object. reference operator*() noexcept { return m_base_iterator; } + /// @brief Get pointer to the base iterator object. + /// @return Pointer to the base iterator object. pointer operator->() noexcept { return &m_base_iterator; } + /// @brief Pre-increments the base iterator object. + /// @return Reference to this map_iterator_proxy object. map_iterator_proxy& operator++() noexcept { ++m_base_iterator; return *this; } + /// @brief Post-increments the base iterator object. + /// @return A map_iterator_proxy object with its base iterator incremented. map_iterator_proxy operator++(int) & noexcept { auto result = *this; ++(*this); return result; } + /// @brief Check equality between map_iterator_proxy objects. + /// @param rhs A map_iterator_proxy object to compare with. + /// @return true if this map_iterator_proxy object is equal to `rhs`, false otherwise. bool operator==(const map_iterator_proxy& rhs) const noexcept { return m_base_iterator == rhs.m_base_iterator; } + /// @brief Check inequality between map_iterator_proxy objects. + /// @param rhs A map_iterator_proxy object to compare with. + /// @return true if this map_iterator_proxy object is not equal to `rhs`, false otherwise. bool operator!=(const map_iterator_proxy& rhs) const noexcept { return m_base_iterator != rhs.m_base_iterator; } + /// @brief Get the mapping key node pointed by the base iterator. + /// @return Reference to the mapping key node. typename Iterator::reference key() const { return m_base_iterator.key(); } + /// @brief Get the mapping value node pointed by the base iterator. + /// @return Reference to the mapping value node. typename Iterator::reference value() const noexcept { return m_base_iterator.value(); } private: + /// The base iterator object. Iterator m_base_iterator {}; }; +/// @brief A helper struct which allows accessing node iterator member functions in range-based for loops. +/// @tparam BasicNodeType A basic_node template instance type. template class map_range_proxy { static_assert( @@ -10288,40 +10331,63 @@ class map_range_proxy { "map_range_proxy only accepts a basic_node type as its template parameter."); public: + /// @brief The type of non-const iterators. using iterator = map_iterator_proxy::value, typename BasicNodeType::const_iterator, typename BasicNodeType::iterator>::type>; + /// @brief The type of const iterators. using const_iterator = map_iterator_proxy; + /// @brief Constructs a map_range_proxy object with a BasicNodeType object. + /// @param map A mapping node object. map_range_proxy(BasicNodeType& map) noexcept : mp_map(&map) { } + /// @brief Copy constructs a map_range_proxy object. map_range_proxy(const map_range_proxy&) = default; + + /// @brief Copy assigns a map_range_proxy object. + /// @return Reference to this map_range_proxy object. map_range_proxy& operator=(const map_range_proxy&) = default; + + /// @brief Move constructs a map_range_proxy object. map_range_proxy(map_range_proxy&&) = default; + + /// @brief Move assigns a map_range_proxy object. + /// @return Reference to this map_range_proxy object. map_range_proxy& operator=(map_range_proxy&&) = default; + /// @brief Destructs a map_range_proxy object. ~map_range_proxy() = default; + /// @brief Get an iterator to the first element. + /// @return An iterator to the first element. iterator begin() noexcept { return {mp_map->begin()}; } + /// @brief Get a const iterator to the first element. + /// @return A const iterator to the first element. const_iterator begin() const noexcept { return {mp_map->cbegin()}; } + /// @brief Get an iterator to the past-the-last element. + /// @return An iterator to the past-the-last element. iterator end() noexcept { return {mp_map->end()}; } + /// @brief Get a const iterator to the past-the-last element. + /// @return A const iterator to the past-the-last element. const_iterator end() const noexcept { return {mp_map->cend()}; } private: + /// Pointer to the mapping node object. (non-null) BasicNodeType* mp_map {nullptr}; }; @@ -10991,11 +11057,18 @@ class reverse_iterator { : m_current(i) { } + /// @brief Copy constructs a reverse_iterator object with a compatible reverse_iterator object. + /// @tparam U A compatible iterator type with Iterator. + /// @param other A compatible reverse_iterator object. template >::value, int> = 0> reverse_iterator(const reverse_iterator& other) noexcept : m_current(other.base()) { } + /// @brief Copy assigns a reverse_iterator object with a compatible reverse_iterator object. + /// @tparam U A compatible iterator type with Iterator. + /// @param other A compatible reverse_iterator object. + /// @return Reference to this reverse_iterator object. template >::value, int> = 0> reverse_iterator& operator=(const reverse_iterator& other) noexcept { m_current = other.base(); @@ -11099,34 +11172,71 @@ class reverse_iterator { } private: + /// Iterator m_current; }; +/// @brief Check equality between reverse_iterator objects. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if the two reverse_iterator objects are equal, false otherwise. template inline bool operator==(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() == rhs.base(); } +/// @brief Check inequality between reverse_iterator objects. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if the two reverse_iterator objects are not equal, false otherwise. template inline bool operator!=(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() != rhs.base(); } +/// @brief Check if `lhs` is less than `rhs`. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if `lhs` is less than `rhs`, false otherwise. template inline bool operator<(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() > rhs.base(); } +/// @brief Check if `lhs` is less than or equal to `rhs`. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if `lhs` is less than or equal to `rhs`, false otherwise. template inline bool operator<=(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() >= rhs.base(); } +/// @brief Check if `lhs` is greater than `rhs`. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if `lhs` is greater than `rhs`, false otherwise. template inline bool operator>(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() < rhs.base(); } +/// @brief Check if `lhs` is greater than or equal to `rhs`. +/// @tparam IteratorL Base iterator type for `lhs`. +/// @tparam IteratorR Base iterator type for `rhs`. +/// @param lhs A reverse_iterator object. +/// @param rhs A reverse_iterator object. +/// @return true if `lhs` is greater than or equal to `rhs`, false otherwise. template inline bool operator>=(const reverse_iterator& lhs, const reverse_iterator& rhs) { return lhs.base() <= rhs.base();