2008-08-06 11:15:24 -07:00
/* EINA - EFL data type library
* Copyright ( C ) 2002 - 2008 Carsten Haitzler , Vincent Torri , Jorge Luis Zapata Muga
*
* This library is free software ; you can redistribute it and / or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation ; either
* version 2.1 of the License , or ( at your option ) any later version .
*
* This library is distributed in the hope that it will be useful ,
* but WITHOUT ANY WARRANTY ; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE . See the GNU
* Lesser General Public License for more details .
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library ;
* if not , see < http : //www.gnu.org/licenses/>.
*/
2008-07-30 05:46:55 -07:00
# ifndef EINA_LIST_H_
# define EINA_LIST_H_
2008-08-08 07:20:11 -07:00
# include <stdlib.h>
2008-09-26 04:41:55 -07:00
# include "eina_config.h"
2008-07-30 06:35:49 -07:00
# include "eina_types.h"
2008-08-13 02:19:34 -07:00
# include "eina_iterator.h"
# include "eina_accessor.h"
2008-09-25 07:46:16 -07:00
# include "eina_magic.h"
2008-07-30 06:35:49 -07:00
2008-09-18 22:22:43 -07:00
/**
* @ addtogroup Eina_Data_Types_Group Data Types
*
* @ {
*/
/**
* @ addtogroup Eina_Containers_Group Containers
*
* @ {
*/
/**
* @ defgroup Eina_List_Group List
*
* @ {
*/
2008-09-22 22:17:49 -07:00
/**
* @ typedef Eina_List
* Type for a generic single linked list .
*/
2008-07-30 05:46:55 -07:00
typedef struct _Eina_List Eina_List ;
2008-09-22 22:17:49 -07:00
2008-08-08 07:20:11 -07:00
typedef struct _Eina_List_Accounting Eina_List_Accounting ;
2008-09-22 22:17:49 -07:00
/**
* @ struct _Eina_List
* Type for a generic single linked list .
*/
2008-08-08 07:20:11 -07:00
struct _Eina_List /** A linked list node */
{
void * data ; /**< Pointer to list element payload */
Eina_List * next ; /**< Next member in the list */
Eina_List * prev ; /**< Previous member in the list */
struct _Eina_List_Accounting * accounting ; /**< Private list accounting info - don't touch */
2008-12-05 22:53:14 -08:00
* eina/src/include/eina_array.h,
* eina/src/include/eina_f16p16.h,
* eina/src/include/eina_accessor.h,
* eina/src/include/eina_list.h,
* eina/src/include/eina_iterator.h,
* eina/src/lib/eina_rectangle.c,
* eina/src/lib/eina_list.c,
* eina/src/lib/eina_array.c,
* eina/src/lib/eina_hash.c,
* eina/src/lib/eina_module.c,
* eina/src/lib/eina_stringshare.c,
* eina/src/lib/eina_benchmark.c: Fix for windows compilation.
SVN revision: 38663
2009-01-20 07:56:48 -08:00
EINA_MAGIC
2008-08-08 07:20:11 -07:00
} ;
2008-09-22 22:17:49 -07:00
2008-08-08 07:20:11 -07:00
struct _Eina_List_Accounting
{
Eina_List * last ;
2008-08-13 02:19:34 -07:00
unsigned int count ;
* eina/src/include/eina_array.h,
* eina/src/include/eina_f16p16.h,
* eina/src/include/eina_accessor.h,
* eina/src/include/eina_list.h,
* eina/src/include/eina_iterator.h,
* eina/src/lib/eina_rectangle.c,
* eina/src/lib/eina_list.c,
* eina/src/lib/eina_array.c,
* eina/src/lib/eina_hash.c,
* eina/src/lib/eina_module.c,
* eina/src/lib/eina_stringshare.c,
* eina/src/lib/eina_benchmark.c: Fix for windows compilation.
SVN revision: 38663
2009-01-20 07:56:48 -08:00
EINA_MAGIC
2008-08-08 07:20:11 -07:00
} ;
2008-08-07 06:09:09 -07:00
EAPI int eina_list_init ( void ) ;
EAPI int eina_list_shutdown ( void ) ;
eina gets lots of gcc attributes to its api.
this should help with optimizations and code correctness, please see
"info gcc" for detailed explanation on these.
if you experience some functions not working as expected, please
double check if they're not marked with EINA_PURE or EINA_CONST, maybe
I misused them. Remove the macro and try again.
brief explanation:
* EINA_WARN_UNUSED_RESULT: if you forgot to use the return of some
function, it will emit a warning (and -Werror will make it an
error). This way it will be harder to miss the attribution
"l = eina_list_append(l, v)".
* EINA_ARG_NONNULL(index, index...): if you give it an explicit NULL
argument, or some tool (ie: clang) finds it could get a NULL but
this is not accepted by API, then a warning will be emitted. This
will help those that still use eina_hash_add() as if it is
evas_hash_add().
* EINA_MALLOC: any non-NULL pointer it returns cannot alias any other
pointer valid when function returns.
* EINA_PURE: function have no effects other than the return and this
return just depend on parameters and/or globals. You might call
this function in a loop a thousand times and it will return the
same value, thus you may move this function outside the loop and
remove it.
* EINA_CONST: stricter version of EINA_PURE, it will not check for
global parameters, that is, you cannot consider pointer
arguments. Use it for math things like "int sqrt(int)".
* EINA_PRINTF(fmt, arg): will check format parameter specified in
position "fmt" and passed arguments starting at position "arg", it
will check for things like giving integers where short or strings
were expected.
* EINA_SCANF(fmt, arg): similar to eina_printf().
* EINA_FORMAT(fmt): for use with things like dgettext(), it will get
a printf-like format string and modifies it.
Please review and test it with your software, make sure you make clean
before you install the new version so it has any effect.
If you find some functions are missing EINA_WARN_UNUSED_RESULT and
EINA_ARG_NONNULL or others, please add them.
SVN revision: 38323
2008-12-26 05:17:51 -08:00
EAPI Eina_List * eina_list_append ( Eina_List * list , const void * data ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_prepend ( Eina_List * list , const void * data ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
2008-12-26 10:31:14 -08:00
EAPI Eina_List * eina_list_append_relative ( Eina_List * list , const void * data , const void * relative ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_append_relative_list ( Eina_List * list , const void * data , Eina_List * relative ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_prepend_relative ( Eina_List * list , const void * data , const void * relative ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_prepend_relative_list ( Eina_List * list , const void * data , Eina_List * relative ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_remove ( Eina_List * list , const void * data ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_remove_list ( Eina_List * list , Eina_List * remove_list ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_promote_list ( Eina_List * list , Eina_List * move_list ) EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
2009-01-26 06:46:02 -08:00
EAPI Eina_List * eina_list_demote_list ( Eina_List * list , Eina_List * move_list ) ;
2008-12-26 10:31:14 -08:00
EAPI void * eina_list_data_find ( const Eina_List * list , const void * data ) EINA_PURE EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_data_find_list ( const Eina_List * list , const void * data ) EINA_PURE EINA_ARG_NONNULL ( 2 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_free ( Eina_List * list ) ;
EAPI void * eina_list_nth ( const Eina_List * list , unsigned int n ) EINA_PURE EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_nth_list ( const Eina_List * list , unsigned int n ) EINA_PURE EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_reverse ( Eina_List * list ) EINA_WARN_UNUSED_RESULT ;
2009-03-17 05:52:38 -07:00
EAPI Eina_List * eina_list_reverse_clone ( const Eina_List * list ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_clone ( const Eina_List * list ) EINA_WARN_UNUSED_RESULT ;
2008-12-26 10:31:14 -08:00
EAPI Eina_List * eina_list_sort ( Eina_List * list , unsigned int size , Eina_Compare_Cb func ) EINA_ARG_NONNULL ( 3 ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_merge ( Eina_List * left , Eina_List * right ) EINA_WARN_UNUSED_RESULT ;
EAPI Eina_List * eina_list_sorted_merge ( Eina_List * left , Eina_List * right , Eina_Compare_Cb func ) EINA_ARG_NONNULL ( 3 ) EINA_WARN_UNUSED_RESULT ;
2009-01-26 06:46:02 -08:00
EAPI void * eina_list_search_sorted ( const Eina_List * list , Eina_Compare_Cb func , const void * data ) ;
EAPI void * eina_list_search_unsorted ( const Eina_List * list , Eina_Compare_Cb func , const void * data ) ;
eina gets lots of gcc attributes to its api.
this should help with optimizations and code correctness, please see
"info gcc" for detailed explanation on these.
if you experience some functions not working as expected, please
double check if they're not marked with EINA_PURE or EINA_CONST, maybe
I misused them. Remove the macro and try again.
brief explanation:
* EINA_WARN_UNUSED_RESULT: if you forgot to use the return of some
function, it will emit a warning (and -Werror will make it an
error). This way it will be harder to miss the attribution
"l = eina_list_append(l, v)".
* EINA_ARG_NONNULL(index, index...): if you give it an explicit NULL
argument, or some tool (ie: clang) finds it could get a NULL but
this is not accepted by API, then a warning will be emitted. This
will help those that still use eina_hash_add() as if it is
evas_hash_add().
* EINA_MALLOC: any non-NULL pointer it returns cannot alias any other
pointer valid when function returns.
* EINA_PURE: function have no effects other than the return and this
return just depend on parameters and/or globals. You might call
this function in a loop a thousand times and it will return the
same value, thus you may move this function outside the loop and
remove it.
* EINA_CONST: stricter version of EINA_PURE, it will not check for
global parameters, that is, you cannot consider pointer
arguments. Use it for math things like "int sqrt(int)".
* EINA_PRINTF(fmt, arg): will check format parameter specified in
position "fmt" and passed arguments starting at position "arg", it
will check for things like giving integers where short or strings
were expected.
* EINA_SCANF(fmt, arg): similar to eina_printf().
* EINA_FORMAT(fmt): for use with things like dgettext(), it will get
a printf-like format string and modifies it.
Please review and test it with your software, make sure you make clean
before you install the new version so it has any effect.
If you find some functions are missing EINA_WARN_UNUSED_RESULT and
EINA_ARG_NONNULL or others, please add them.
SVN revision: 38323
2008-12-26 05:17:51 -08:00
static inline Eina_List * eina_list_last ( const Eina_List * list ) EINA_PURE EINA_WARN_UNUSED_RESULT ;
static inline Eina_List * eina_list_next ( const Eina_List * list ) EINA_PURE EINA_WARN_UNUSED_RESULT ;
static inline Eina_List * eina_list_prev ( const Eina_List * list ) EINA_PURE EINA_WARN_UNUSED_RESULT ;
static inline void * eina_list_data_get ( const Eina_List * list ) EINA_PURE EINA_WARN_UNUSED_RESULT ;
static inline unsigned int eina_list_count ( const Eina_List * list ) EINA_PURE ;
EAPI Eina_Iterator * eina_list_iterator_new ( const Eina_List * list ) EINA_MALLOC EINA_WARN_UNUSED_RESULT ;
2009-03-17 06:05:02 -07:00
EAPI Eina_Iterator * eina_list_iterator_reversed_new ( const Eina_List * list ) EINA_MALLOC EINA_WARN_UNUSED_RESULT ;
eina gets lots of gcc attributes to its api.
this should help with optimizations and code correctness, please see
"info gcc" for detailed explanation on these.
if you experience some functions not working as expected, please
double check if they're not marked with EINA_PURE or EINA_CONST, maybe
I misused them. Remove the macro and try again.
brief explanation:
* EINA_WARN_UNUSED_RESULT: if you forgot to use the return of some
function, it will emit a warning (and -Werror will make it an
error). This way it will be harder to miss the attribution
"l = eina_list_append(l, v)".
* EINA_ARG_NONNULL(index, index...): if you give it an explicit NULL
argument, or some tool (ie: clang) finds it could get a NULL but
this is not accepted by API, then a warning will be emitted. This
will help those that still use eina_hash_add() as if it is
evas_hash_add().
* EINA_MALLOC: any non-NULL pointer it returns cannot alias any other
pointer valid when function returns.
* EINA_PURE: function have no effects other than the return and this
return just depend on parameters and/or globals. You might call
this function in a loop a thousand times and it will return the
same value, thus you may move this function outside the loop and
remove it.
* EINA_CONST: stricter version of EINA_PURE, it will not check for
global parameters, that is, you cannot consider pointer
arguments. Use it for math things like "int sqrt(int)".
* EINA_PRINTF(fmt, arg): will check format parameter specified in
position "fmt" and passed arguments starting at position "arg", it
will check for things like giving integers where short or strings
were expected.
* EINA_SCANF(fmt, arg): similar to eina_printf().
* EINA_FORMAT(fmt): for use with things like dgettext(), it will get
a printf-like format string and modifies it.
Please review and test it with your software, make sure you make clean
before you install the new version so it has any effect.
If you find some functions are missing EINA_WARN_UNUSED_RESULT and
EINA_ARG_NONNULL or others, please add them.
SVN revision: 38323
2008-12-26 05:17:51 -08:00
EAPI Eina_Accessor * eina_list_accessor_new ( const Eina_List * list ) EINA_MALLOC EINA_WARN_UNUSED_RESULT ;
2008-08-13 02:19:34 -07:00
2008-09-22 22:17:49 -07:00
/**
2008-11-02 01:41:14 -08:00
* @ def EINA_LIST_FOREACH
2008-09-22 22:17:49 -07:00
* @ brief Macro to iterate over a list easily .
*
* @ param list The list to iterate over .
* @ param l A list that is used as loop index .
2008-11-02 01:41:14 -08:00
* @ param data The data .
2008-09-22 22:17:49 -07:00
*
* This macro allow the iteration over @ p list in an easy way . It
* iterates from the first element to the last one . @ p data is the
* data of each element of the list . @ p l is an # Eina_List that is
* used as counter .
*
* This macro can be used for freeing the data of alist , like in
* the following example :
*
* @ code
* Eina_List * list ;
* Eina_List * l ;
* char * data ;
*
* // list is already filled,
* // its elements are just duplicated strings,
2008-11-02 01:41:14 -08:00
* // EINA_LIST_FOREACH will be used to free those strings
2008-09-22 22:17:49 -07:00
*
2008-11-02 01:41:14 -08:00
* EINA_LIST_FOREACH ( list , l , data )
2008-09-22 22:17:49 -07:00
* free ( data ) ;
2009-02-27 08:32:22 -08:00
* eina_list_free ( list ) ;
2008-09-22 22:17:49 -07:00
* @ endcode
2008-12-05 18:13:01 -08:00
*
2009-02-27 08:32:22 -08:00
* @ note this example is not optimal algorithm to release a list since
* it will walk the list twice , but it serves as an example . For
* optimized version use EINA_LIST_FREE ( )
*
* @ warning do not delete list nodes , specially the current node ,
* while iterating . If you wish to do so , use
* EINA_LIST_FOREACH_SAFE ( ) .
2008-09-22 22:17:49 -07:00
*/
2008-10-21 05:49:29 -07:00
# define EINA_LIST_FOREACH(list, l, data) for (l = list, data = eina_list_data_get(l); l; l = eina_list_next(l), data = eina_list_data_get(l))
2008-07-30 05:46:55 -07:00
2009-02-25 12:19:32 -08:00
/**
* @ def EINA_LIST_REVERSE_FOREACH
* @ brief Macro to iterate over a list easily in the reverse order .
*
* @ param list The list to iterate over .
* @ param l A list that is used as loop index .
* @ param data The data .
*
* This macro allow the reversed iteration over @ p list in an easy
* way . It iterates from the last element to the first one . @ p data is
* the data of each element of the list . @ p l is an # Eina_List that is
* used as counter .
*
* This macro can be used for freeing the data of alist , like in
* the following example :
*
* @ code
* Eina_List * list ;
* Eina_List * l ;
* char * data ;
*
* // list is already filled,
* // its elements are just duplicated strings,
* // EINA_LIST_REVERSE_FOREACH will be used to free those strings
*
* EINA_LIST_REVERSE_FOREACH ( list , l , data )
* free ( data ) ;
2009-02-27 08:32:22 -08:00
* eina_list_free ( list ) ;
2009-02-25 12:19:32 -08:00
* @ endcode
*
2009-02-27 08:32:22 -08:00
* @ note this example is not optimal algorithm to release a list since
* it will walk the list twice , but it serves as an example . For
* optimized version use EINA_LIST_FREE ( )
*
* @ warning do not delete list nodes , specially the current node ,
* while iterating . If you wish to do so , use
* EINA_LIST_REVERSE_FOREACH_SAFE ( ) .
2009-02-25 12:19:32 -08:00
*/
# define EINA_LIST_REVERSE_FOREACH(list, l, data) for (l = eina_list_last(list), data = eina_list_data_get(l); l; l = eina_list_prev(l), data = eina_list_data_get(l))
2008-12-05 18:13:01 -08:00
/**
* @ def EINA_LIST_FOREACH_SAFE
* @ brief Macro to iterate over a list easily , supporting deletion .
*
* @ param list The list to iterate over .
* @ param l A list that is used as loop index .
* @ param l_next A second list that is used as loop next index .
* @ param data The data .
*
* This macro allow the iteration over @ p list in an easy way . It
* iterates from the first element to the last one . @ p data is the
* data of each element of the list . @ p l is an # Eina_List that is
* used as counter .
*
* This is the safe version , which stores the next pointer in @ p l_next
* before proceeding , so deletion of @ b current node is safe . If you wish
* to remove anything else , remember to set @ p l_next accordingly .
*
* This macro can be used for freeing list nodes , like in
* the following example :
*
* @ code
* Eina_List * list ;
* Eina_List * l ;
* Eina_List * l_next ;
* char * data ;
*
* // list is already filled,
* // its elements are just duplicated strings,
* // EINA_LIST_FOREACH_SAFE will be used to free elements that match "key".
*
* EINA_LIST_FOREACH_SAFE ( list , l , l_next , data )
* if ( strcmp ( data , " key " ) = = 0 ) {
* free ( data ) ;
* list = eina_list_remove_list ( list , l ) ;
* }
* @ endcode
*/
# define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) for (l = list, l_next = eina_list_next(l), data = eina_list_data_get(l); l; l = l_next, l_next = eina_list_next(l), data = eina_list_data_get(l))
2009-02-25 12:19:32 -08:00
/**
* @ def EINA_LIST_REVERSE_FOREACH_SAFE
* @ brief Macro to iterate over a list easily in the reverse order ,
* supporting deletion .
*
* @ param list The list to iterate over .
* @ param l A list that is used as loop index .
* @ param l_prev A second list that is used as loop previous index .
* @ param data The data .
*
* This macro allow the reversed iteration over @ p list in an easy
* way . It iterates from the last element to the first one . @ p data is
* the data of each element of the list . @ p l is an # Eina_List that is
* used as counter .
*
* This is the safe version , which stores the previous pointer in @ p
* l_prev before proceeding , so deletion of @ b current node is
* safe . If you wish to remove anything else , remember to set @ p
* l_prev accordingly .
*
* This macro can be used for freeing list nodes , like in
* the following example :
*
* @ code
* Eina_List * list ;
* Eina_List * l ;
* Eina_List * l_prev ;
* char * data ;
*
* // list is already filled,
* // its elements are just duplicated strings,
* // EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that match "key".
*
* EINA_LIST_REVERSE_FOREACH_SAFE ( list , l , l_prev , data )
* if ( strcmp ( data , " key " ) = = 0 ) {
* free ( data ) ;
* list = eina_list_remove_list ( list , l ) ;
* }
* @ endcode
*/
# define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) for (l = list, l_prev = eina_list_prev(l), data = eina_list_data_get(l); l; l = l_prev, l_prev = eina_list_prev(l), data = eina_list_data_get(l))
2009-02-27 08:32:22 -08:00
/**
* Easy way to free the while list while being able to release its pointed data .
*
* @ code
* Eina_List * list ;
* char * data ;
*
* // list is already filled,
* // its elements are just duplicated strings,
*
* EINA_LIST_FREE ( list , data )
* free ( data ) ;
* @ endcode
*
* If you do not need to release node data then use eina_list_free ( ) .
*
* @ see eina_list_free ( )
*/
2009-02-20 08:44:26 -08:00
# define EINA_LIST_FREE(list, data) for (data = list ? eina_list_data_get(list) : NULL; list; list = eina_list_remove_list(list, list), data = list ? eina_list_data_get(list) : NULL)
2008-12-05 18:13:01 -08:00
2008-08-08 07:20:11 -07:00
# include "eina_inline_list.x"
2008-07-30 05:46:55 -07:00
2008-09-18 22:22:43 -07:00
/**
* @ }
*/
/**
* @ }
*/
/**
* @ }
*/
2008-07-30 05:46:55 -07:00
# endif /* EINA_LIST_H_ */