git.sesse.net Git - vlc/blob - modules/codec/cmml/xlist.h

   1 /*****************************************************************************
   2  * xlist.h : a simple doubly linked list in C (header file)
   3  *****************************************************************************
   4  * Copyright (C) 2003-2004 Commonwealth Scientific and Industrial Research
   5  *                         Organisation (CSIRO) Australia
   6  * Copyright (C) 2000-2004 the VideoLAN team
   7  *
   8  * $Id$
   9  *
  10  * Authors: Conrad Parker <Conrad.Parker@csiro.au>
  11  *          Andre Pang <Andre.Pang@csiro.au>
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  26  *****************************************************************************/
  27
  28
  29 #ifndef __XLIST__
  30 #define __XLIST__
  31
  32 /**
  33  * A doubly linked list
  34  */
  35 typedef struct _XList XList;
  36
  37 struct _XList {
  38   XList * prev;
  39   XList * next;
  40   void * data;
  41 };
  42
  43 /**
  44  * Signature of a cloning function.
  45  */
  46 typedef void * (*XCloneFunc) (void * data);
  47
  48 /**
  49  * Signature of a freeing function.
  50  */
  51 typedef void * (*XFreeFunc) (void * data);
  52
  53 /** Create a new list
  54  * \return a new list
  55  */
  56 XList * xlist_new (void);
  57
  58 /**
  59  * Clone a list using the default clone function
  60  * \param list the list to clone
  61  * \returns a newly cloned list
  62  */
  63 XList * xlist_clone (XList * list);
  64
  65 /**
  66  * Clone a list using a custom clone function
  67  * \param list the list to clone
  68  * \param clone the function to use to clone a list item
  69  * \returns a newly cloned list
  70  */
  71 XList * xlist_clone_with (XList * list, XCloneFunc clone);
  72
  73 /**
  74  * Return the tail element of a list
  75  * \param list the list
  76  * \returns the tail element
  77  */
  78 XList * xlist_tail (XList * list);
  79
  80 /**
  81  * Prepend a new node to a list containing given data
  82  * \param list the list
  83  * \param data the data element of the newly created node
  84  * \returns the new list head
  85  */
  86 XList * xlist_prepend (XList * list, void * data);
  87
  88 /**
  89  * Append a new node to a list containing given data
  90  * \param list the list
  91  * \param data the data element of the newly created node
  92  * \returns the head of the list
  93  */
  94 XList * xlist_append (XList * list, void * data);
  95
  96 /**
  97  * Add a new node containing given data before a given node
  98  * \param list the list
  99  * \param data the data element of the newly created node
 100  * \param node the node before which to add the newly created node
 101  * \returns the head of the list (which may have changed)
 102  */
 103 XList * xlist_add_before (XList * list, void * data, XList * node);
 104
 105 /**
 106  * Add a new node containing given data after a given node
 107  * \param list the list
 108  * \param data the data element of the newly created node
 109  * \param node the node after which to add the newly created node
 110  * \returns the head of the list
 111  */
 112 XList * xlist_add_after (XList * list, void * data, XList * node);
 113
 114 /**
 115  * Find the first node containing given data in a list
 116  * \param list the list
 117  * \param data the data element to find
 118  * \returns the first node containing given data, or NULL if it is not found
 119  */
 120 XList * xlist_find (XList * list, void * data);
 121
 122 /**
 123  * Remove a node from a list
 124  * \param list the list
 125  * \param node the node to remove
 126  * \returns the head of the list (which may have changed)
 127  */
 128 XList * xlist_remove (XList * list, XList * node);
 129
 130 /**
 131  * Query the number of items in a list
 132  * \param list the list
 133  * \returns the number of nodes in the list
 134  */
 135 int xlist_length (XList * list);
 136
 137 /**
 138  * Query if a list is empty, ie. contains no items
 139  * \param list the list
 140  * \returns 1 if the list is empty, 0 otherwise
 141  */
 142 int xlist_is_empty (XList * list);
 143
 144 /**
 145  * Query if the list is singleton, ie. contains exactly one item
 146  * \param list the list
 147  * \returns 1 if the list is singleton, 0 otherwise
 148  */
 149 int xlist_is_singleton (XList * list);
 150
 151 /**
 152  * Free a list, using a given function to free each data element
 153  * \param list the list
 154  * \param free_func a function to free each data element
 155  * \returns NULL on success
 156  */
 157 XList * xlist_free_with (XList * list, XFreeFunc free_func);
 158
 159 /**
 160  * Free a list, using anx_free() to free each data element
 161  * \param list the list
 162  * \returns NULL on success
 163  */
 164 XList * xlist_free (XList * list);
 165
 166 #endif /* __XLIST__ */
 167
 168