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