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 list is empty
  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          * @return
  67          *                                              - SUCCESS
  68          *                                              - FAILED
  69          */
  70         status_t (*insert_before) (iterator_t *this, void *item);
  71
  72         /**
  73          * Inserts a new item after the given iterator position.
  74          *
  75          * The iterator position is not changed after inserting.
  76          *
  77          * @param this                  calling iterator
  78          * @param [in]item              value to insert in list
  79          * @return
  80          *                                              - SUCCESS
  81          *                                              - FAILED
  82          */
  83         status_t (*insert_after) (iterator_t *this, void *item);
  84
  85         /**
  86          * @brief removes an element from list at the given iterator position.
  87          *
  88          * The position of the iterator is set in the following order:
  89          * - to the item before, if available
  90          * - otherwise to the item after, if available
  91          * - otherwise it gets reseted
  92          *
  93          * @param linked_list   calling object
  94          * @return
  95          *                                              - SUCCESS
  96          *                                              - FAILED
  97          */
  98         status_t (*remove) (iterator_t *iterator);
  99
 100         /**
 101          * @brief Resets the iterator position.
 102          *
 103          * After reset, the iterator stands NOT on an element.
 104          * A call to has_next is necessary to do any other operations
 105          * with the resetted iterator.
 106          *
 107          * @param this                  calling object
 108          * @return                              SUCCESS in any case
 109          */
 110         status_t (*reset) (iterator_t *this);
 111
 112         /**
 113          * @brief Destroys an iterator.
 114          *
 115          * @param this                  iterator to destroy
 116          * @return                              SUCCESS in any case
 117          *
 118          */
 119         status_t (*destroy) (iterator_t *this);
 120 };
 121
 122 #endif /*ITERATOR_H_*/