ucx: ucx/list.h@8b44653541ef

     1 /*

     2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

     3  *

     4  * Copyright 2013 Olaf Wintermann. All rights reserved.

     5  *

     6  * Redistribution and use in source and binary forms, with or without

     7  * modification, are permitted provided that the following conditions are met:

     8  *

     9  *   1. Redistributions of source code must retain the above copyright

    10  *      notice, this list of conditions and the following disclaimer.

    11  *

    12  *   2. Redistributions in binary form must reproduce the above copyright

    13  *      notice, this list of conditions and the following disclaimer in the

    14  *      documentation and/or other materials provided with the distribution.

    15  *

    16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

    17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

    18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

    19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

    20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

    21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

    22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

    23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

    24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

    25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

    26  * POSSIBILITY OF SUCH DAMAGE.

    27  */

    28 /**

    29  * Double linked list implementation.

    30  *

    31  * @file   list.h

    32  * @author Mike Becker

    33  * @author Olaf Wintermann

    34  */

    36 #ifndef UCX_LIST_H

    37 #define	UCX_LIST_H

    39 #include "ucx.h"

    40 #include <stddef.h>

    42 #ifdef	__cplusplus

    43 extern "C" {

    44 #endif

    46 /**

    47  * Loop statement for UCX lists.

    48  *

    49  * The first argument is a pointer to the list. In most cases this will be the

    50  * pointer to the first element of the list, but it may also be an arbitrary

    51  * element of the list. The iteration will then start with that element.

    52  *

    53  * The second argument is the name of the iteration variable. The scope of

    54  * this variable is limited to the <code>UCX_FOREACH</code> statement.

    55  *

    56  * @param list The first element of the list

    57  * @param elem The variable name of the element

    58  */

    59 #define UCX_FOREACH(elem,list) \

    60         for (UcxList* elem = list ; elem != NULL ; elem = elem->next)

    62 /**

    63  * UCX list type

    64  * @see UcxList

    65  */

    66 typedef struct UcxList UcxList;

    67 struct UcxList {

    68     /**

    69      * List element payload.

    70      */

    71     void    *data;

    72     /**

    73      * Pointer to the next list element or <code>NULL</code>, if this is the

    74      * last element.

    75      */

    76     UcxList *next;

    77     /**

    78      * Pointer to the previous list element or <code>NULL</code>, if this is

    79      * the first element.

    80      */

    81     UcxList *prev;

    82 };

    84 UcxList *ucx_list_clone(UcxList *l, copy_func fnc, void* data);

    86 /**

    87  * Compares two UCX lists element-wise by using a compare function.

    88  *

    89  * Each element of the two specified lists are compared by using the specified

    90  * compare function and the additional data. The type and content of this

    91  * additional data depends on the cmp_func() used.

    92  *

    93  * If the list pointers denote elements within a list, the lists are compared

    94  * starting with the denoted elements. Thus any previous elements are not taken

    95  * into account. This might be useful to check, if certain list tails match

    96  * each other.

    97  *

    98  * @param list1 the first list

    99  * @param list2 the second list

   100  * @param cmpfnc the compare function

   101  * @param data additional data for the compare function

   102  * @return 1, if and only if the two lists equal element-wise, 0 otherwise

   103  */

   104 int ucx_list_equals(const UcxList *list1, const UcxList *list2,

   105         cmp_func cmpfnc, void* data);

   107 /**

   108  * Destroys the entire list.

   109  *

   110  * The members of the list are not automatically freed, so ensure they are

   111  * otherwise referenced or a memory leak will occur.

   112  *

   113  * <b>Caution:</b> the argument <b>MUST</b> denote an entire list (i.e. a call

   114  * to ucx_list_first() on the argument must return the argument itself)

   115  *

   116  * @param list The list to free.

   117  */

   118 void ucx_list_free(UcxList *list);

   119 UcxList *ucx_list_append(UcxList *list, void *data);

   120 UcxList *ucx_list_prepend(UcxList *list, void *data);

   121 UcxList *ucx_list_concat(UcxList *list1, UcxList *list2);

   122 /**

   123  * Returns the first element of a list.

   124  *

   125  * If the argument is the list pointer, it is directly returned. Otherwise

   126  * this function traverses to the first element of the list and returns the

   127  * list pointer.

   128  *

   129  * @param elem one element of the list

   130  * @return the first element of the list, the specified element is a member of

   131  */

   132 UcxList *ucx_list_first(const UcxList *elem);

   133 /**

   134  * Returns the last element of a list.

   135  *

   136  * If the argument has no successor, it is the last element and therefore

   137  * directly returned. Otherwise this function traverses to the last element of

   138  * the list and returns it.

   139  *

   140  * @param elem one element of the list

   141  * @return the last element of the list, the specified element is a member of

   142  */

   143 UcxList *ucx_list_last(const UcxList *elem);

   144 UcxList *ucx_list_get(const UcxList *list, int index);

   145 ssize_t ucx_list_indexof(const UcxList *list, const UcxList *elem);

   146 size_t ucx_list_size(const UcxList *list);

   147 ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func cmpfnc, void *data);

   148 int ucx_list_contains(UcxList *list, void *elem, cmp_func cmpfnc, void *data);

   150 UcxList *ucx_list_sort(UcxList *list, cmp_func cmpfnc, void *data);

   152 /**

   153  * Removes an element from the list.

   154  *

   155  * If the first element is removed, the list pointer changes. So it is

   156  * <i>highly recommended</i> to <i>always</i> update the pointer by calling

   157  * <code>mylist = ucx_list_remove(mylist, myelem);</code>.

   158  *

   159  * @param list the list from which the element shall be removed

   160  * @param element the element to removed

   161  * @return returns the updated list pointer or <code>NULL</code>, if the list

   162  * is now empty

   163  */

   164 UcxList *ucx_list_remove(UcxList *list, UcxList *element);

   166 #ifdef	__cplusplus

   167 }

   168 #endif

   170 #endif	/* UCX_LIST_H */

Mercurial > hg > ucx / file revision