1 /* 2 * Copyright (c) 2020, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file includes definitions for a generic item-pointer iterator class. 32 */ 33 34 #ifndef ITERATOR_UTILS_HPP_ 35 #define ITERATOR_UTILS_HPP_ 36 37 namespace ot { 38 39 /** 40 * @addtogroup core-iterator-utils 41 * 42 * @brief 43 * This module includes definitions for OpenThread generic item-pointer iterator class. 44 * 45 * @{ 46 */ 47 48 /** 49 * Is used as a base class for those item-pointer iterators. 50 * 51 * These iterators have common methods and operators like `Advance()` and `++` and hold a pointer to the 52 * object. 53 * 54 * Users of this class should follow CRTP-style inheritance, i.e., `IteratorType` class itself should publicly inherit 55 * from `ItemPtrIterator<ItemType, IteratorType>`. 56 * 57 * @tparam ItemType The type of the object that the iterator points to. 58 * @tparam IteratorType The Iterator class that inherits this class. The class MUST have a method `Advance()` which 59 * moves the pointer to the next. `Advance()` SHALL NOT be called when `IsDone()` is `true` and 60 * would set the pointer to `nullptr` when there's no more elements. 61 */ 62 template <typename ItemType, typename IteratorType> class ItemPtrIterator 63 { 64 public: 65 /** 66 * Indicates whether there are no more items to be accessed (iterator has reached the end). 67 * 68 * @retval TRUE There are no more items to be accessed (iterator has reached the end). 69 * @retval FALSE The current item is valid. 70 */ IsDone(void) const71 bool IsDone(void) const { return mItem == nullptr; } 72 73 /** 74 * Overloads `++` operator (pre-increment) to advance the iterator. 75 * 76 * The iterator is moved to point to the next item using IteratorType's `Advance` method. 77 * If there are no more items, the iterator becomes empty (i.e., `operator*` returns `nullptr` and `IsDone()` 78 * returns `true`). 79 */ operator ++(void)80 void operator++(void) { static_cast<IteratorType *>(this)->Advance(); } 81 82 /** 83 * Overloads `++` operator (post-increment) to advance the iterator. 84 * 85 * The iterator is moved to point to the next item using IteratorType's `Advance` method. 86 * If there are no more items, the iterator becomes empty (i.e., `operator*` returns `nullptr` and `IsDone()` 87 * returns `true`). 88 */ operator ++(int)89 void operator++(int) { static_cast<IteratorType *>(this)->Advance(); } 90 91 /** 92 * Overloads the `*` dereference operator and gets a reference to then item to which the iterator is 93 * currently pointing. 94 * 95 * MUST be used when the iterator is not empty/finished (i.e., `IsDone()` returns `false`). 96 * 97 * @returns A reference to the item currently pointed by the iterator. 98 */ operator *(void)99 ItemType &operator*(void) { return *mItem; } 100 101 /** 102 * Overloads the `->` dereference operator and gets a pointer to the item to which the iterator is 103 * currently pointing. 104 * 105 * @returns A pointer to the item associated with the iterator, or `nullptr` if iterator is empty/done. 106 */ operator ->(void)107 ItemType *operator->(void) { return mItem; } 108 109 /** 110 * Overloads operator `==` to evaluate whether or not two `Iterator` instances point to the same 111 * item. 112 * 113 * @param[in] aOther The other `Iterator` to compare with. 114 * 115 * @retval TRUE If the two `Iterator` objects point to the same item or both are done. 116 * @retval FALSE If the two `Iterator` objects do not point to the same item. 117 */ operator ==(const IteratorType & aOther) const118 bool operator==(const IteratorType &aOther) const { return mItem == aOther.mItem; } 119 120 /** 121 * Overloads operator `!=` to evaluate whether or not two `Iterator` instances point to the same 122 * child entry. 123 * 124 * @param[in] aOther The other `Iterator` to compare with. 125 * 126 * @retval TRUE If the two `Iterator` objects do not point to the same item. 127 * @retval FALSE If the two `Iterator` objects point to the same item or both are done. 128 */ operator !=(const IteratorType & aOther) const129 bool operator!=(const IteratorType &aOther) const { return mItem != aOther.mItem; } 130 131 protected: 132 /** 133 * Default constructor 134 */ ItemPtrIterator(void)135 ItemPtrIterator(void) 136 : mItem(nullptr) 137 { 138 } 139 140 /** 141 * Constructor with an Item pointer. 142 */ ItemPtrIterator(ItemType * item)143 explicit ItemPtrIterator(ItemType *item) 144 : mItem(item) 145 { 146 } 147 148 ItemType *mItem; 149 }; 150 151 /** 152 * @} 153 */ 154 155 } // namespace ot 156 157 #endif // ITERATOR_UTILS_HPP_ 158