src/libstrongswan/utils/iterator.h

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