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 3:
   6  * TODO
   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: Wed Sep 17 21:07:54 ART 2003
  13  *
  14  * $Id$
  15  */
  16
  17 #ifndef DLLIST_H
  18 #define DLLIST_H
  19
  20 /** Nodo de la lista doblemente enlazada. */
  21 struct DLListNode {
  22     /** Puntero al nodo anterior. */
  23     DLListNode* prev;
  24     /** Datos almacenados en el nodo. */
  25     void* data;
  26     /** Puntero al próximo nodo. */
  27     DLListNode* next;
  28 };
  29
  30 /**
  31  * Lista doblemente enlazada.
  32  */
  33 class DLList {
  34
  35     protected:
  36         /** Puntero al primer nodo. */
  37         DLListNode* first;
  38         /** Puntero al nodo actual. */
  39         DLListNode* current;
  40         /** Puntero al último nodo. */
  41         DLListNode* last;
  42
  43     public:
  44         /**
  45          * Crea una nueva lista.
  46          */
  47         DLList(void);
  48
  49         /**
  50          * Libera la memoria ocupada por una lista.
  51          */
  52         ~DLList(void);
  53
  54         /**
  55          * Indica si está vacía.
  56          *
  57          * \return true si está vacía, false si no.
  58          */
  59         bool empty(void);
  60
  61         /**
  62          * Apunta al primer elemento, devolviendolo.
  63          * Hace que el elemento actual sea el primero y devuelve su valor.
  64          * Si está vacía, devuelve NULL.
  65          * Siempre que se quiera recorrer la lista de izquierda a derecha
  66          * debería usarse esta función primero. Por ejemplo:
  67          * \code
  68          * DLList list;
  69          * char*  data;
  70          * ...
  71          * for (data = list.begin(); list.have_more(); data = list.next()) {
  72          *      printf("El elemento actual es '%s'.\\n", data);
  73          * }
  74          * \endcode
  75          *
  76          * \return  Primer elemento o NULL si está vacía.
  77          * \see     have_more(), next(), end(), prev()
  78          */
  79         void* begin(void);
  80
  81         /**
  82          * Apunta al último elemento, devolviendolo.
  83          * Hace que el elemento actual sea el último y devuelve su valor.
  84          * Si está vacía, devuelve NULL.
  85          * Siempre que se quiera recorrer la lista de derecha a izquierda
  86          * debería usarse esta función primero. Por ejemplo:
  87          * \code
  88          * DLList list;
  89          * char*  data;
  90          * ...
  91          * for (data = list.end(); list.have_more(); data = list.prev()) {
  92          *      printf("El elemento actual es '%s'.\\n", data);
  93          * }
  94          * \endcode
  95          *
  96          * \return  Último elemento o NULL si está vacía.
  97          * \see     DLList_have_more(), DLList_prev(), DLList_begin(), DLList_next()
  98          * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.
  99          */
 100         void* end(void);
 101
 102         /**
 103          * Indica si se puede obtener otro elemento de la lista.
 104          *
 105          * \return true si se puede obtener otro elemento, false si no.
 106          * \see    begin(), end(), prev(), next()
 107          */
 108         bool have_more(void);
 109
 110         /**
 111          * Obtiene el elemento actual.
 112          *
 113          * \return Elemento actual o NULL si se terminó de recorrer o está vacía.
 114          * \see   prev(), next(), have_more()
 115          */
 116         void* current(void);
 117
 118         /**
 119          * Obtiene el próximo elemento.
 120          *
 121          * \return  Siguiente elemento o NULL si es el último.
 122          * \see     begin(), have_more(), current(), prev()
 123          */
 124         void* next(void);
 125
 126         /**
 127          * Obtiene el elemento anterior.
 128          *
 129          * \return  Elemento anterior o NULL si es el primero.
 130          * \see     begin(), have_more(), current(), next()
 131          */
 132         void* prev(void);
 133
 134         /**
 135          * Agrega un elemento al inicio.
 136          *
 137          * \param   data Elemento a agregar.
 138          *
 139          * \return  true si se agregó, false si no hay más memoria.
 140          * \see     push(), pop(), unshift()
 141          */
 142         bool unshift(void* data);
 143
 144         /**
 145          * Agrega un elemento al final.
 146          *
 147          * \param   data Elemento a agregar.
 148          *
 149          * \return  true si se agregó, false si no hay más memoria.
 150          * \see     pop(), shift(), unshift()
 151          */
 152         bool push(void* data);
 153
 154         /**
 155          * Saca el primer elemento.
 156          * Elimina el primer elemento devolviendo su contenido.
 157          * Ejemplo:
 158          * \code
 159          * DLList list;
 160          * char*  data;
 161          * ...
 162          * while (!list.empty()) {
 163          *      data = list.shift();
 164          *      printf("El elemento actual es '%s'.\\n", data);
 165          * }
 166          * \endcode
 167          *
 168          * \return  Primer elemento o NULL si está vacía.
 169          * \see     empty(), pop(), remove_current()
 170          * \warning Es necesario comprobar antes si está vacía, ya que puede
 171          *          devolver NULL también si el elemento de la lista es NULL.
 172          */
 173         void* shift(void);
 174
 175         /**
 176          * Saca el último elemento.
 177          * Elimina el último elemento devolviendo su contenido.
 178          * Ejemplo:
 179          * \code
 180          * DLList list;
 181          * char*   data;
 182          * ...
 183          * while (!list.empty()) {
 184          *      data = list.pop();
 185          *      printf("El elemento actual es '%s'.\\n", data);
 186          * }
 187          * \endcode
 188          *
 189          * \return  Último elemento o NULL si está vacía.
 190          * \see     empty(), shift(), remove_current()
 191          * \warning Es necesario comprobar antes si está vacía, ya que puede
 192          *          devolver NULL también si el elemento de la lista es NULL.
 193          */
 194         void* pop(void);
 195
 196         /**
 197          * Elimina el elemento actual.
 198          * Elimina el elemento actual devolviendo su contenido.
 199          *
 200          * \return  Elemento actual o NULL si no hay más elementos.
 201          * \see     empty(), current(), have_more()
 202          * \warning Es necesario comprobar antes si está vacía, ya que puede
 203          *          devolver NULL también si el elemento de la lista es NULL.
 204          */
 205         void* remove_current(void);
 206
 207 #endif /* DLLIST_H */