src/libstrongswan/utils/iterator.h

   1 /*
   2  * Copyright (C) 2005-2006 Martin Willi
   3  * Copyright (C) 2005 Jan Hutter
   4  * Hochschule fuer Technik Rapperswil
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2 of the License, or (at your
   9  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * for more details.
  15  *
  16  * $Id$
  17  */
  18
  19 /**
  20  * @defgroup iterator iterator
  21  * @{ @ingroup utils
  22  */
  23
  24 #ifndef ITERATOR_H_
  25 #define ITERATOR_H_
  26
  27 #include <library.h>
  28
  29
  30 typedef struct iterator_t iterator_t;
  31
  32 /**
  33  * Iterator interface, allows iteration over collections.
  34  *
  35  * iterator_t defines an interface for iterating over collections.
  36  * It allows searching, deleting, updating and inserting.
  37  *
  38  * @deprecated Use enumerator instead.
  39  */
  40 struct iterator_t {
  41
  42         /**
  43          * Return number of list items.
  44          *
  45          * @return                              number of list items
  46          */
  47         int (*get_count) (iterator_t *this);
  48
  49         /**
  50          * Iterate over all items.
  51          *
  52          * The easy way to iterate over items.
  53          *
  54          * @param value         item
  55          * @return                      TRUE, if there was an element available, FALSE otherwise
  56          */
  57         bool (*iterate) (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 item          value to insert in list
  65          */
  66         void (*insert_before) (iterator_t *this, void *item);
  67
  68         /**
  69          * Inserts a new item after the given iterator position.
  70          *
  71          * The iterator position is not changed after inserting.
  72          *
  73          * @param this          calling iterator
  74          * @param item          value to insert in list
  75          */
  76         void (*insert_after) (iterator_t *this, void *item);
  77
  78         /**
  79          * Replace the current item at current iterator position.
  80          *
  81          * The iterator position is not changed after replacing.
  82          *
  83          * @param this          calling iterator
  84          * @param old           old value will be written here(can be NULL)
  85          * @param new           new value
  86          * @return                      SUCCESS, FAILED if iterator is on an invalid position
  87          */
  88         status_t (*replace) (iterator_t *this, void **old, void *new);
  89
  90         /**
  91          * Removes an element from list at the given iterator position.
  92          *
  93          * The iterator is set the the following position:
  94          * - to the item before, if available
  95          * - it gets reseted, otherwise
  96          *
  97          * @return                              SUCCESS, FAILED if iterator is on an invalid position
  98          */
  99         status_t (*remove) (iterator_t *this);
 100
 101         /**
 102          * Resets the iterator position.
 103          *
 104          * After reset, the iterator_t objects doesn't point to an element.
 105          * A call to iterator_t.has_next is necessary to do any other operations
 106          * with the resetted iterator.
 107          */
 108         void (*reset) (iterator_t *this);
 109
 110         /**
 111          * Destroys an iterator.
 112          */
 113         void (*destroy) (iterator_t *this);
 114 };
 115
 116 #endif /*ITERATOR_H_ @} */