src/lib/eina_iterator.c

   1 /*
   2  * vim:ts=8:sw=3:sts=8:noexpandtab:cino=>5n-3f0^-2{2
   3  */
   4 /* EINA - EFL data type library
   5  * Copyright (C) 2002-2008 Cedric Bail
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library;
  19  * if not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 #ifdef HAVE_CONFIG_H
  23 # include "config.h"
  24 #endif
  25
  26 #include <stdlib.h>
  27
  28 #include "eina_config.h"
  29 #include "eina_private.h"
  30
  31 /* undefs EINA_ARG_NONULL() so NULL checks are not compiled out! */
  32 #include "eina_safety_checks.h"
  33 #include "eina_iterator.h"
  34
  35 /*============================================================================*
  36  *                                  Local                                     *
  37  *============================================================================*/
  38
  39 /**
  40  * @cond LOCAL
  41  */
  42
  43 #define EINA_MAGIC_CHECK_ITERATOR(d)                            \
  44   do {                                                          \
  45     if (!EINA_MAGIC_CHECK(d, EINA_MAGIC_ITERATOR))              \
  46       EINA_MAGIC_FAIL(d, EINA_MAGIC_ITERATOR);                  \
  47   } while(0);
  48
  49 /**
  50  * @endcond
  51  */
  52
  53
  54 /*============================================================================*
  55  *                                 Global                                     *
  56  *============================================================================*/
  57
  58 /*============================================================================*
  59  *                                   API                                      *
  60  *============================================================================*/
  61
  62 /**
  63  * @addtogroup Eina_Iterator_Group Iterator Functions
  64  *
  65  * @brief These functions manage iterators on containers.
  66  *
  67  * These functions allow to access elements of a container in a
  68  * generic way, without knowing which container is used (a bit like
  69  * iterators in the C++ STL). Iterators only allows sequential access
  70  * (that is, from an element to the next one). For random access, see
  71  * @ref Eina_Accessor_Group.
  72  *
  73  * An iterator is created from container data types, so no creation
  74  * function is available here. An iterator is deleted with
  75  * eina_iterator_free(). To get the data and iterate, use
  76  * eina_iterator_next(). To call a function on all the elements of a
  77  * container, use eina_iterator_foreach().
  78  *
  79  * @{
  80  */
  81
  82 /**
  83  * @internal
  84  * @brief Initialize the iterator module.
  85  *
  86  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
  87  *
  88  * This function sets up the iterator module of Eina. It is called by
  89  * eina_init().
  90  *
  91  * @see eina_init()
  92  */
  93 Eina_Bool
  94 eina_iterator_init(void)
  95 {
  96    return eina_magic_string_set(EINA_MAGIC_ITERATOR, "Eina Iterator");
  97 }
  98
  99 /**
 100  * @internal
 101  * @brief Shut down the iterator module.
 102  *
 103  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
 104  *
 105  * This function shuts down the iterator module set up by
 106  * eina_iterator_init(). It is called by eina_shutdown().
 107  *
 108  * @see eina_shutdown()
 109  */
 110 Eina_Bool
 111 eina_iterator_shutdown(void)
 112 {
 113    return EINA_TRUE;
 114 }
 115
 116 /**
 117  * @brief Free an iterator.
 118  *
 119  * @param iterator The iterator to free.
 120  *
 121  * This function frees @p iterator if it is not @c NULL;
 122  */
 123 EAPI void
 124 eina_iterator_free(Eina_Iterator *iterator)
 125 {
 126    EINA_MAGIC_CHECK_ITERATOR(iterator);
 127    EINA_SAFETY_ON_NULL_RETURN(iterator);
 128    EINA_SAFETY_ON_NULL_RETURN(iterator->free);
 129    iterator->free(iterator);
 130 }
 131
 132 /**
 133  * @brief Return the container of an iterator.
 134  *
 135  * @param iterator The iterator.
 136  * @return The container which created the iterator.
 137  *
 138  * This function returns the container which created @p iterator. If
 139  * @p iterator is @c NULL, this function returns @c NULL.
 140  */
 141 EAPI void *
 142 eina_iterator_container_get(Eina_Iterator *iterator)
 143 {
 144    EINA_MAGIC_CHECK_ITERATOR(iterator);
 145    EINA_SAFETY_ON_NULL_RETURN_VAL(iterator, NULL);
 146    EINA_SAFETY_ON_NULL_RETURN_VAL(iterator->get_container, NULL);
 147    return iterator->get_container(iterator);
 148 }
 149
 150 /**
 151  * @brief Return the value of the current element and go to the next one.
 152  *
 153  * @param iterator The iterator.
 154  * @param data The data of the element.
 155  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 156  *
 157  * This function returns the value of the current element pointed by
 158  * @p iterator in @p data, then goes to the next element. If @p
 159  * iterator is @c NULL or if a problem occured, #EINA_FALSE is
 160  * returned, otherwise #EINA_TRUE is returned.
 161  */
 162 EAPI Eina_Bool
 163 eina_iterator_next(Eina_Iterator *iterator, void **data)
 164 {
 165    if (!iterator) return EINA_FALSE;
 166    EINA_MAGIC_CHECK_ITERATOR(iterator);
 167    EINA_SAFETY_ON_NULL_RETURN_VAL(iterator, EINA_FALSE);
 168    EINA_SAFETY_ON_NULL_RETURN_VAL(iterator->next, EINA_FALSE);
 169    EINA_SAFETY_ON_NULL_RETURN_VAL(data, EINA_FALSE);
 170    return iterator->next(iterator, data);
 171 }
 172
 173 /**
 174  * @brief Iterate over the container and execute a callback on each element.
 175  *
 176  * @param iterator The iterator.
 177  * @param cb The callback called on each iteration.
 178  * @param fdata The data passed to the callback.
 179  *
 180  * This function iterates over the elements pointed by @p iterator,
 181  * beginning from the current element. For Each element, the callback
 182  * @p cb is called with the data @p fdata.If @p iterator is @c NULL,
 183  * the function returns immediatly.
 184  */
 185 EAPI void
 186 eina_iterator_foreach(Eina_Iterator *iterator,
 187                       Eina_Each cb,
 188                       const void *fdata)
 189 {
 190    const void *container;
 191    void *data;
 192
 193    EINA_MAGIC_CHECK_ITERATOR(iterator);
 194    EINA_SAFETY_ON_NULL_RETURN(iterator);
 195    EINA_SAFETY_ON_NULL_RETURN(iterator->get_container);
 196    EINA_SAFETY_ON_NULL_RETURN(iterator->next);
 197    EINA_SAFETY_ON_NULL_RETURN(cb);
 198
 199    container = iterator->get_container(iterator);
 200    while (iterator->next(iterator, &data) == EINA_TRUE) {
 201       if (cb(container, data, (void*) fdata) != EINA_TRUE) return ;
 202    }
 203 }
 204
 205 /**
 206  * @}
 207  */