--- a/src/ucx/list.h Tue Dec 27 17:54:00 2016 +0100 +++ b/src/ucx/list.h Tue Dec 27 18:42:36 2016 +0100 @@ -1,7 +1,7 @@ /* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * - * Copyright 2015 Olaf Wintermann. All rights reserved. + * Copyright 2016 Olaf Wintermann. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: @@ -46,13 +46,13 @@ /** * Loop statement for UCX lists. * - * The first argument is a pointer to the list. In most cases this will be the + * The first argument is the name of the iteration variable. The scope of + * this variable is limited to the <code>UCX_FOREACH</code> statement. + * + * The second argument is a pointer to the list. In most cases this will be the * pointer to the first element of the list, but it may also be an arbitrary * element of the list. The iteration will then start with that element. * - * The second argument is the name of the iteration variable. The scope of - * this variable is limited to the <code>UCX_FOREACH</code> statement. - * * @param list The first element of the list * @param elem The variable name of the element */ @@ -102,13 +102,12 @@ UcxList *ucx_list_clone(UcxList *list, copy_func cpyfnc, void* data); /** - * Creates an element-wise copy of a list using an UcxAllocator. + * Creates an element-wise copy of a list using a UcxAllocator. * * See ucx_list_clone() for details. * - * Keep in mind, that you might want to pass the allocator as an (part of the) - * argument for the <code>data</code> parameter, if you want the copy_func() to - * make use of the allocator. + * You might want to pass the allocator via the <code>data</code> parameter, + * to access it within the copy function for making deep copies. * * @param allocator the allocator to use * @param list the list to copy @@ -146,17 +145,19 @@ * Destroys the entire list. * * The members of the list are not automatically freed, so ensure they are - * otherwise referenced or a memory leak will occur. + * otherwise referenced or destroyed by ucx_list_free_contents(). + * Otherwise, a memory leak is likely to occur. * * <b>Caution:</b> the argument <b>MUST</b> denote an entire list (i.e. a call * to ucx_list_first() on the argument must return the argument itself) * * @param list the list to free + * @see ucx_list_free_contents() */ void ucx_list_free(UcxList *list); /** - * Destroys the entire list using an UcxAllocator. + * Destroys the entire list using a UcxAllocator. * * See ucx_list_free() for details. * @@ -167,6 +168,20 @@ void ucx_list_free_a(UcxAllocator *allocator, UcxList *list); /** + * Destroys the contents of the specified list by calling the specified + * destructor on each of them. + * + * Note, that the contents are not usable afterwards and the list should be + * destroyed with ucx_list_free(). + * + * @param list the list for which the contents shall be freed + * @param destr the destructor function (e.g. stdlib free()) + * @see ucx_list_free() + */ +void ucx_list_free_content(UcxList* list, ucx_destructor destr); + + +/** * Inserts an element at the end of the list. * * This is generally an O(n) operation, as the end of the list is retrieved with @@ -181,7 +196,7 @@ UcxList *ucx_list_append(UcxList *list, void *data); /** - * Inserts an element at the end of the list using an UcxAllocator. + * Inserts an element at the end of the list using a UcxAllocator. * * See ucx_list_append() for details. * @@ -212,7 +227,7 @@ UcxList *ucx_list_prepend(UcxList *list, void *data); /** - * Inserts an element at the beginning of the list using an UcxAllocator. + * Inserts an element at the beginning of the list using a UcxAllocator. * * See ucx_list_prepend() for details. * @@ -327,7 +342,7 @@ int ucx_list_contains(UcxList *list, void *elem, cmp_func cmpfnc, void *data); /** - * Sorts an UcxList with natural merge sort. + * Sorts a UcxList with natural merge sort. * * This function uses O(n) additional temporary memory for merge operations * that is automatically freed after each merge. @@ -357,7 +372,7 @@ UcxList *ucx_list_remove(UcxList *list, UcxList *element); /** - * Removes an element from the list using an UcxAllocator. + * Removes an element from the list using a UcxAllocator. * * See ucx_list_remove() for details. *