Source/charon/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  * @ingroup utils
  35  */
  36 struct iterator_t {
  37
  38         /**
  39          * Moves to the next element, if available.
  40          *
  41          * @param this                  calling object
  42          * @return
  43          *                                              - TRUE, if more elements are avaiable,
  44          *                                              - FALSE otherwise
  45          */
  46         bool (*has_next) (iterator_t *this);
  47
  48         /**
  49          * Returns the current value at the iterator position.
  50          *
  51          * @param this                  calling object
  52          * @param[out] value    value is set to the current value at iterator position
  53          * @return
  54          *                                              - SUCCESS
  55          *                                              - FAILED if iterator on an invalid position
  56          */
  57         status_t (*current) (iterator_t *this, void **value);
  58
  59         /**
  60          * Inserts a new item before the given iterator position.
  61          *
  62          * The iterator position is not changed after inserting
  63          *
  64          * @param this                  calling iterator
  65          * @param[in] item              value to insert in list
  66          */
  67         void (*insert_before) (iterator_t *this, void *item);
  68
  69         /**
  70          * @brief Inserts a new item after the given iterator position.
  71          *
  72          * The iterator position is not changed after inserting.
  73          *
  74          * @param this                  calling iterator
  75          * @param[in] item              value to insert in list
  76          */
  77         void (*insert_after) (iterator_t *this, void *item);
  78
  79         /**
  80          * @brief removes an element from list at the given iterator position.
  81          *
  82          * The position of the iterator is set in the following order:
  83          * - to the item before, if available
  84          * - otherwise to the item after, if available
  85          * - otherwise it gets reseted
  86          *
  87          * @param linked_list   calling object
  88          * @return
  89          *                                              - SUCCESS
  90          *                                              - FAILED if iterator is on an invalid position
  91          */
  92         status_t (*remove) (iterator_t *iterator);
  93
  94         /**
  95          * @brief Resets the iterator position.
  96          *
  97          * After reset, the iterator stands NOT on an element.
  98          * A call to has_next is necessary to do any other operations
  99          * with the resetted iterator.
 100          *
 101          * @param this                  calling object
 102          * @return                              SUCCESS in any case
 103          */
 104         void (*reset) (iterator_t *this);
 105
 106         /**
 107          * @brief Destroys an iterator.
 108          *
 109          * @param this                  iterator to destroy
 110          * @return                              SUCCESS in any case
 111          *
 112          */
 113         void (*destroy) (iterator_t *this);
 114 };
 115
 116 #endif /*ITERATOR_H_*/