From 97f1652f7d6c29ae3be186f7e1500ddd81fd0467 Mon Sep 17 00:00:00 2001 From: Philipp Schafft Date: Thu, 8 Nov 2018 13:52:30 +0000 Subject: [PATCH] Feature: Added some comments on how the igloo_list_t API is to be used --- include/igloo/list.h | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/include/igloo/list.h b/include/igloo/list.h index df4b632..7a1e2ab 100644 --- a/include/igloo/list.h +++ b/include/igloo/list.h @@ -45,22 +45,54 @@ struct igloo_list_iterator_tag { }; /* ---[ END PRIVATE ]--- */ +/* To create lists use: igloo_ro_new(igloo_list_t) + */ + +/* Clear a list (remove all elements). */ int igloo_list_clear(igloo_list_t *list); +/* Preallocate space for later mass-adding of elements. */ void igloo_list_preallocate(igloo_list_t *list, size_t request); +/* Limit elements to those of the given type. */ int igloo_list_set_type__real(igloo_list_t *list, const igloo_ro_type_t *type); #define igloo_list_set_type(list,type) igloo_list_set_type__real((list),(igloo_ro__type__ ## type)) +/* Add an element at the end of the list. */ int igloo_list_push(igloo_list_t *list, igloo_ro_t element); +/* Add an element at the begin of a list. */ int igloo_list_unshift(igloo_list_t *list, igloo_ro_t element); +/* Get and remove the first element from the list. */ igloo_ro_t igloo_list_shift(igloo_list_t *list); +/* Get and remove the last element from the list. */ igloo_ro_t igloo_list_pop(igloo_list_t *list); +/* Merge the content of the list elements into the list list. The list elements is not changed. */ int igloo_list_merge(igloo_list_t *list, igloo_list_t *elements); +/* Creates a new iterator that can be used to walk the list. + * The memory pointed to by storage of size storage_length is used to store the iterator's internal + * values. It must be allocated (e.g. on stack) untill igloo_list_iterator_end() is called. + * igloo_list_iterator_storage_t is provided to be used as storage object. + * Example: + * igloo_list_iterator_storage_t storage; + * igloo_list_iterator_t *iterator = igloo_list_iterator_start(list, &storage, sizeof(storage)); + */ igloo_list_iterator_t * igloo_list_iterator_start(igloo_list_t *list, void *storage, size_t storage_length); +/* Get next element from iterator. */ igloo_ro_t igloo_list_iterator_next(igloo_list_iterator_t *iterator); +/* Destory iterator. */ void igloo_list_iterator_end(igloo_list_iterator_t *iterator); +/* Rewind iterator. The next call to igloo_list_iterator_next() will return the first element again. */ int igloo_list_iterator_rewind(igloo_list_iterator_t *iterator); +/* Go thru all elements in the list. + * Parameters: + * list: the list to use. + * type: the type of elements in the list + * var: the variable to store the current element in. + * code: the code block to be used in the loop. + * + * Note: This can only be used on lists that contain only one type of objects. + * See also: igloo_list_set_type() + */ #define igloo_list_foreach(list,type,var,code) \ do { \ igloo_list_iterator_storage_t __igloo_list_iterator_storage; \