dllist.h

   1 /* vim: set et sts=4 sw=4 fdm=indent fdl=1 fdn=1 fo+=t tw=80:
   2  *
   3  * Taller de Programación (75.42).
   4  *
   5  * Ejercicio Número 2:
   6  * Programa calculadora.
   7  *
   8  * Copyleft 2003 - Leandro Lucarella <llucare@fi.uba.ar>
   9  * Puede copiar, modificar y distribuir este programa bajo los términos de
  10  * la licencia GPL (http://www.gnu.org/).
  11  *
  12  * Creado: sáb ago 30 19:59:12 ART 2003
  13  *
  14  * $Id$
  15  */
  16
  17 #ifndef DLLIST_H
  18 #define DLLIST_H
  19
  20 #include "bool.h"
  21
  22 /** Nodo de la lista doblemente enlazada. */
  23 typedef struct DLNodeStruct DLNode;
  24
  25 /** Nodo de la lista doblemente enlazada. */
  26 struct DLNodeStruct {
  27     /** Puntero al nodo anterior. */
  28     DLNode* prev;
  29     /** Datos almacenados en el nodo. */
  30     void*  data;
  31     /** Puntero al próximo nodo. */
  32     DLNode* next;
  33 };
  34
  35 /**
  36  * Lista doblemente enlazada.
  37  *
  38  * \see DLList_new(), DLList_delete(), DLList_empty(), DLList_begin(),
  39  *      DLList_end(), DLList_have_more(), DLList_current(), DLList_next(),
  40  *      DLList_prev(), DLList_unshift(), DLList_push(), DLList_shift(),
  41  *      DLList_pop()
  42  */
  43 typedef struct {
  44     /** Puntero al primer nodo. */
  45     DLNode* first;
  46     /** Puntero al nodo actual. */
  47     DLNode* current;
  48     /** Puntero al último nodo. */
  49     DLNode* last;
  50 } DLList;
  51
  52 /**
  53  * Crea una nueva lista.
  54  *
  55  * \return  Puntero a la nueva DLList o NULL si no hay más memoria.
  56  */
  57 DLList* DLList_new(void);
  58
  59 /**
  60  * Libera la memoria ocupada por una lista.
  61  *
  62  * \param   list DLList a liberar.
  63  *
  64  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
  65  */
  66 void DLList_delete(DLList* list);
  67
  68 /**
  69  * Indica si la DLList está vacía.
  70  *
  71  * \param   list DLList a verificar.
  72  *
  73  * \return  \ref TRUE si está vacía, \ref FALSE si no.
  74  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
  75  */
  76 bool DLList_empty(DLList* list);
  77
  78 /**
  79  * Apunta al primer elemento de la DLList devolviendolo.
  80  * Hace que el elemento actual de la DLList sea el primero y devuelve su valor.
  81  * Si está vacía, devuelve NULL.
  82  * Siempre que se quiera recorrer la DLList de izquierda a derecha debería
  83  * usarse esta función primero. Por ejemplo:
  84  * \code
  85  * DLList* l;
  86  * char*   data;
  87  * ...
  88  * for (data = DLList_begin(l); DLList_have_more(l); data = DLList_next(l)) {
  89  *      printf("El elemento actual es '%s'.\\n", data);
  90  * }
  91  * \endcode
  92  *
  93  * \param   list DLList de la cual obtener el primer elemento.
  94  *
  95  * \return  Primer elemento o NULL si está vacía.
  96  * \see     DLList_have_more(), DLList_next(), DLList_end(), DLList_prev()
  97  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
  98  */
  99 void* DLList_begin(DLList* list);
 100
 101 /**
 102  * Apunta al último elemento de la DLList devolviendolo.
 103  * Hace que el elemento actual de la DLList sea el último y devuelve su valor.
 104  * Si está vacía, devuelve NULL.
 105  * Siempre que se quiera recorrer la DLList de derecha a izquierda debería
 106  * usarse esta función primero. Por ejemplo:
 107  * \code
 108  * DLList* l;
 109  * char*   data;
 110  * ...
 111  * for (data = DLList_end(l); DLList_have_more(l); data = DLList_prev(l)) {
 112  *      printf("El elemento actual es '%s'.\\n", data);
 113  * }
 114  * \endcode
 115  *
 116  * \param   list DLList de la cual obtener el último elemento.
 117  *
 118  * \return  Último elemento o NULL si está vacía.
 119  * \see     DLList_have_more(), DLList_prev(), DLList_begin(), DLList_next()
 120  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
 121  */
 122 void* DLList_end(DLList* list);
 123
 124 /**
 125  * Indica si se puede obtener otro elemento de la lista en una iteración.
 126  *
 127  * \param   list DLList a verificar.
 128  *
 129  * \return  \ref TRUE si se puede obtener otro elemento, \ref FALSE si no.
 130  * \see     DLList_begin(), DLList_end(), DLList_prev(), DLList_next()
 131  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
 132  */
 133 bool DLList_have_more(DLList* list);
 134
 135 /**
 136  * Obtiene el elemento actual de la DLList.
 137  *
 138  * \param   list DLList de la cual obtener el elemento actual.
 139  *
 140  * \return  Elemento actual o NULL si se terminó de recorrer o está vacía.
 141  * \see     DLList_prev(), DLList_next(), DLList_have_more()
 142  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
 143  */
 144 void* DLList_current(DLList* list);
 145
 146 /**
 147  * Obtiene el próximo elemento de la DLList.
 148  *
 149  * \param   list DLList de la cual obtener el siguiente elemento.
 150  *
 151  * \return  Siguiente elemento o NULL si es el último.
 152  * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_prev()
 153  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
 154  */
 155 void* DLList_next(DLList* list);
 156
 157 /**
 158  * Obtiene el elemento anterior de la DLList.
 159  *
 160  * \param   list DLList de la cual obtener el elemento anterior.
 161  *
 162  * \return  Elemento anterior o NULL si es el primero.
 163  * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_next()
 164  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
 165  */
 166 void* DLList_prev(DLList* list);
 167
 168 /**
 169  * Agrega un elemento al inicio de la DLList.
 170  *
 171  * \param   list DLList a la cual agregar el elemento.
 172  * \param   data Elemento a agregar.
 173  *
 174  * \return  \ref TRUE si se agregó, \ref FALSE si no hay más memoria.
 175  * \see     DLList_push(), DLList_pop(), DLList_unshift()
 176  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
 177  * \post    El puntero interno de la DLList apunta al nuevo elemento.
 178  */
 179 bool DLList_unshift(DLList* list, void* data);
 180
 181 /**
 182  * Agrega un elemento al final de la DLList.
 183  *
 184  * \param   list DLList a la cual agregar el elemento.
 185  * \param   data Elemento a agregar.
 186  *
 187  * \return  \ref TRUE si se agregó, \ref FALSE si no hay más memoria.
 188  * \see     DLList_pop(), DLList_shift(), DLList_unshift()
 189  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
 190  * \post    El puntero interno de la DLList apunta al nuevo elemento.
 191  */
 192 bool DLList_push(DLList* list, void* data);
 193
 194 /**
 195  * Saca el primer elemento de la DLList.
 196  * Elimina el primer elemento de la DLList devolviendo su contenido.
 197  * Ejemplo:
 198  * \code
 199  * DLList* l;
 200  * char*   data;
 201  * ...
 202  * while (!DLList_empty(l)) {
 203  *      data = DLList_shift(l);
 204  *      printf("El elemento actual es '%s'.\\n", data);
 205  * }
 206  * \endcode
 207  *
 208  * \param   list DLList de la cual sacar el elemento.
 209  *
 210  * \return  Primer elemento de la DLList.
 211  * \see     DLList_empty(), DLList_pop()
 212  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente y no
 213  *          debe estar \ref DLList_empty "vacía".
 214  * \post    El puntero interno de la DLList apunta primer elemento.
 215  */
 216 void* DLList_shift(DLList* list);
 217
 218 /**
 219  * Saca el último elemento de la DLList.
 220  * Elimina el último elemento de la DLList devolviendo su contenido.
 221  * Ejemplo:
 222  * \code
 223  * DLList* l;
 224  * char*   data;
 225  * ...
 226  * while (!DLList_empty(l)) {
 227  *      data = DLList_pop(l);
 228  *      printf("El elemento actual es '%s'.\\n", data);
 229  * }
 230  * \endcode
 231  *
 232  * \param   list DLList de la cual sacar el elemento.
 233  *
 234  * \return  Último elemento de la DLList.
 235  * \see     DLList_empty(), DLList_shift()
 236  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente y no
 237  *          debe estar \ref DLList_empty "vacía".
 238  * \post    El puntero interno de la DLList apunta último elemento.
 239  */
 240 void* DLList_pop(DLList* list);
 241
 242 /**
 243  * Elimina el elemento actual de la DLList.
 244  * Elimina el elemento actual de la DLList devolviendo su contenido.
 245  *
 246  * \param   list DLList de la cual sacar el elemento.
 247  *
 248  * \return  Elemento actual de la DLList o NULL si no hay más elementos.
 249  * \see     DLList_empty(), DLList_current(), DLList_have_more()
 250  * \pre     La DLList debe estar \ref DLList_new "creada" correctamente y
 251  *          debe \ref DLList_have_more "tener un elemento actual" (por lo que
 252  *          también debe estar no \ref DLList_empty "vacía").
 253  * \post    El puntero interno de la DLList apunta al próximo elemento.
 254  */
 255 void* DLList_remove_current(DLList* list);
 256
 257 #endif /* DLLIST_H */