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_init(), DLList_empty(), DLList_begin(), DLList_end(),
  44  *      DLList_have_more(), DLList_current(), DLList_next(), DLList_prev(),
  45  *      DLList_unshift(), DLList_push(), DLList_shift(), 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  * Inicializa la DLList.
  58  *
  59  * \param   list DLList a inicializar.
  60  *
  61  * \return  \ref TRUE si se inicializó bien, \ref FALSE si hay error.
  62  */
  63 bool DLList_init(DLList* list);
  64
  65 /**
  66  * Indica si la DLList está vacía.
  67  *
  68  * \param   list DLList a verificar.
  69  *
  70  * \return  \ref TRUE si está vacía, \ref FALSE si no.
  71  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  72  */
  73 bool DLList_empty(DLList* list);
  74
  75 /**
  76  * Apunta al primer elemento de la DLList devolviendolo.
  77  * Hace que el elemento actual de la DLList sea el primero y devuelve su valor.
  78  * Si está vacía, devuelve NULL.
  79  * Siempre que se quiera recorrer la DLList de izquierda a derecha debería
  80  * usarse esta función primero. Por ejemplo:
  81  * \code
  82  * DLList* l;
  83  * char*   data;
  84  * ...
  85  * for (data = DLList_begin(l); DLList_have_more(l); data = DLList_next(l)) {
  86  *      printf("El elemento actual es '%s'.\\n", data);
  87  * }
  88  * \endcode
  89  *
  90  * \param   list DLList de la cual obtener el primer elemento.
  91  *
  92  * \return  Primer elemento o NULL si está vacía.
  93  * \see     DLList_have_more(), DLList_next(), DLList_end(), DLList_prev()
  94  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  95  */
  96 void* DLList_begin(DLList* list);
  97
  98 /**
  99  * Apunta al último elemento de la DLList devolviendolo.
 100  * Hace que el elemento actual de la DLList sea el último y devuelve su valor.
 101  * Si está vacía, devuelve NULL.
 102  * Siempre que se quiera recorrer la DLList de derecha a izquierda debería
 103  * usarse esta función primero. Por ejemplo:
 104  * \code
 105  * DLList* l;
 106  * char*   data;
 107  * ...
 108  * for (data = DLList_end(l); DLList_have_more(l); data = DLList_prev(l)) {
 109  *      printf("El elemento actual es '%s'.\\n", data);
 110  * }
 111  * \endcode
 112  *
 113  * \param   list DLList de la cual obtener el último elemento.
 114  *
 115  * \return  Último elemento o NULL si está vacía.
 116  * \see     DLList_have_more(), DLList_prev(), DLList_begin(), DLList_next()
 117  * \pre     La DLList debe estar \ref DLList_init "inicializada".
 118  */
 119 void* DLList_end(DLList* list);
 120
 121 /**
 122  * Indica si se puede obtener otro elemento de la lista en una iteración.
 123  *
 124  * \param   list DLList a verificar.
 125  *
 126  * \return  \ref TRUE si se puede obtener otro elemento, \ref FALSE si no.
 127  * \see     DLList_begin(), DLList_end(), DLList_prev(), DLList_next()
 128  * \pre     La DLList debe estar \ref DLList_init "inicializada".
 129  */
 130 bool DLList_have_more(DLList* list);
 131
 132 /**
 133  * Obtiene el elemento actual de la DLList.
 134  *
 135  * \param   list DLList de la cual obtener el elemento actual.
 136  *
 137  * \return  Elemento actual o NULL si se terminó de recorrer o está vacía.
 138  * \see     DLList_prev(), DLList_next(), DLList_have_more()
 139  * \pre     La DLList debe estar \ref DLList_init "inicializada".
 140  */
 141 void* DLList_current(DLList* list);
 142
 143 /**
 144  * Obtiene el próximo elemento de la DLList.
 145  *
 146  * \param   list DLList de la cual obtener el siguiente elemento.
 147  *
 148  * \return  Siguiente elemento o NULL si es el último.
 149  * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_prev()
 150  * \pre     La DLList debe estar \ref DLList_init "inicializada".
 151  */
 152 void* DLList_next(DLList* list);
 153
 154 /**
 155  * Obtiene el elemento anterior de la DLList.
 156  *
 157  * \param   list DLList de la cual obtener el elemento anterior.
 158  *
 159  * \return  Elemento anterior o NULL si es el primero.
 160  * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_next()
 161  * \pre     La DLList debe estar \ref DLList_init "inicializada".
 162  */
 163 void* DLList_prev(DLList* list);
 164
 165 /**
 166  * Agrega un elemento al inicio de la DLList.
 167  *
 168  * \param   list DLList a la cual agregar el elemento.
 169  * \param   data Elemento a agregar.
 170  *
 171  * \return  \ref TRUE si se agregó, \ref FALSE si no hay más memoria.
 172  * \see     DLList_push(), DLList_pop(), DLList_unshift()
 173  * \pre     La DLList debe estar \ref DLList_init "inicializada".
 174  * \post    El puntero interno de la DLList apunta al nuevo elemento.
 175  */
 176 bool DLList_unshift(DLList* list, void* data);
 177
 178 /**
 179  * Agrega un elemento al final de la DLList.
 180  *
 181  * \param   list DLList a la cual agregar el elemento.
 182  * \param   data Elemento a agregar.
 183  *
 184  * \return  \ref TRUE si se agregó, \ref FALSE si no hay más memoria.
 185  * \see     DLList_pop(), DLList_shift(), DLList_unshift()
 186  * \pre     La DLList debe estar \ref DLList_init "inicializada".
 187  * \post    El puntero interno de la DLList apunta al nuevo elemento.
 188  */
 189 bool DLList_push(DLList* list, void* data);
 190
 191 /**
 192  * Saca el primer elemento de la DLList.
 193  * Elimina el primer elemento de la DLList devolviendo su contenido.
 194  * Ejemplo:
 195  * \code
 196  * DLList* l;
 197  * char*   data;
 198  * ...
 199  * while (!DLList_empty(l)) {
 200  *      data = DLList_shift(l);
 201  *      printf("El elemento actual es '%s'.\\n", data);
 202  * }
 203  * \endcode
 204  *
 205  * \param   list DLList de la cual sacar el elemento.
 206  *
 207  * \return  Primer elemento de la DLList.
 208  * \see     DLList_empty(), DLList_pop()
 209  * \pre     La DLList debe estar \ref DLList_init "inicializada" y no
 210  *          \ref DLList_empty "vacía.
 211  * \post    El puntero interno de la DLList apunta primer elemento.
 212  */
 213 void* DLList_shift(DLList* list);
 214
 215 /**
 216  * Saca el último elemento de la DLList.
 217  * Elimina el último elemento de la DLList devolviendo su contenido.
 218  * Ejemplo:
 219  * \code
 220  * DLList* l;
 221  * char*   data;
 222  * ...
 223  * while (!DLList_empty(l)) {
 224  *      data = DLList_pop(l);
 225  *      printf("El elemento actual es '%s'.\\n", data);
 226  * }
 227  * \endcode
 228  *
 229  * \param   list DLList de la cual sacar el elemento.
 230  *
 231  * \return  Último elemento de la DLList.
 232  * \see     DLList_empty(), DLList_shift()
 233  * \pre     La DLList debe estar \ref DLList_init "inicializada" y no
 234  *          \ref DLList_empty "vacía.
 235  * \post    El puntero interno de la DLList apunta último elemento.
 236  */
 237 void* DLList_pop(DLList* list);
 238
 239 #endif /* DLLIST_H */