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