Source/lib/utils/iterator.h

   1 /**
   2  * @file iterator.h
   3  *
   4  * @brief Interface iterator_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Jan Hutter, Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef ITERATOR_H_
  24 #define ITERATOR_H_
  25
  26 typedef struct iterator_t iterator_t;
  27
  28 /**
  29  * @brief Iterator interface, allows iteration over collections.
  30  *
  31  * iterator_t defines an interface for iterating over collections.
  32  * It allows searching, deleting, updating and inserting.
  33  *
  34  * Thanks to JMP for iterator lessons :-)
  35  *
  36  * @b Constructors:
  37  * - via linked_list_t.create_iterator, or
  38  * - any other class which supports the iterator_t interface
  39  *
  40  * @see linked_list_t
  41  *
  42  * @ingroup utils
  43  */
  44 struct iterator_t {
  45
  46         /**
  47          * @brief Iterate over all items.
  48          *
  49          * The easy way to iterate over items.
  50          *
  51          * @param this                  calling object
  52          * @param[out] value    item
  53          * @return
  54          *                                              - TRUE, if more elements are avaiable,
  55          *                                              - FALSE otherwise
  56          */
  57         bool (*iterate) (iterator_t *this, void** value);
  58
  59         /**
  60          * @brief Moves to the next element, if available.
  61          *
  62          * A newly created iterator_t object doesn't point to any item.
  63          * Call iterator_t.has_next first to point it to the first item.
  64          *
  65          * @param this                  calling object
  66          * @return
  67          *                                              - TRUE, if more elements are avaiable,
  68          *                                              - FALSE otherwise
  69          */
  70         bool (*has_next) (iterator_t *this);
  71
  72         /**
  73          * @brief Returns the current value at the iterator position.
  74          *
  75          * @param this                  calling object
  76          * @param[out] value    value is set to the current value at iterator position
  77          * @return
  78          *                                              - SUCCESS
  79          *                                              - FAILED if iterator on an invalid position
  80          */
  81         status_t (*current) (iterator_t *this, void **value);
  82
  83         /**
  84          * @brief Inserts a new item before the given iterator position.
  85          *
  86          * The iterator position is not changed after inserting
  87          *
  88          * @param this                  calling iterator
  89          * @param[in] item              value to insert in list
  90          */
  91         void (*insert_before) (iterator_t *this, void *item);
  92
  93         /**
  94          * @brief Inserts a new item after the given iterator position.
  95          *
  96          * The iterator position is not changed after inserting.
  97          *
  98          * @param this                  calling iterator
  99          * @param[in] item              value to insert in list
 100          */
 101         void (*insert_after) (iterator_t *this, void *item);
 102
 103         /**
 104          * @brief Replace the current item at current iterator position.
 105          *
 106          * The iterator position is not changed after replacing.
 107          *
 108          * @param this                  calling iterator
 109          * @param[out] old_item old value will be written here(can be NULL)
 110          * @param[in] new_item  new value
 111          *
 112          * @return
 113          *                                              - SUCCESS
 114          *                                              - FAILED if iterator is on an invalid position
 115          */
 116         status_t (*replace) (iterator_t *this, void **old_item, void *new_item);
 117
 118         /**
 119          * @brief Removes an element from list at the given iterator position.
 120          *
 121          * The position of the iterator is set in the following order:
 122          * - to the item before, if available
 123          * - otherwise to the item after, if available
 124          * - otherwise it gets reseted
 125          *
 126          * @param linked_list   calling object
 127          * @return
 128          *                                              - SUCCESS
 129          *                                              - FAILED if iterator is on an invalid position
 130          */
 131         status_t (*remove) (iterator_t *iterator);
 132
 133         /**
 134          * @brief Resets the iterator position.
 135          *
 136          * After reset, the iterator_t objects doesn't point to an element.
 137          * A call to iterator_t.has_next is necessary to do any other operations
 138          * with the resetted iterator.
 139          *
 140          * @param this                  calling object
 141          */
 142         void (*reset) (iterator_t *this);
 143
 144         /**
 145          * @brief Destroys an iterator.
 146          *
 147          * @param this                  iterator to destroy
 148          *
 149          */
 150         void (*destroy) (iterator_t *this);
 151 };
 152
 153 #endif /*ITERATOR_H_*/