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