Últimos retoques.

[z.facultad/75.42/calculadora.git] / dllist.h

diff --git a/dllist.h b/dllist.h
index d9ad1f781d59330e05f2731a67bbbef7f7b191c8..674fbc3b34f19195cfa9d2a5b66e278ee4381062 100644 (file)
--- a/dllist.h
+++ b/dllist.h
@@ -17,12 +17,7 @@
 #ifndef DLLIST_H
 #define DLLIST_H
 
 #ifndef DLLIST_H
 #define DLLIST_H
 

-
-/** Tipo de dato booleano. */
-typedef enum {
-    FALSE,      /**< Falso. */
-    TRUE        /**< Verdadero. */
-} bool;
+#include "bool.h"

 
 /** Nodo de la lista doblemente enlazada. */
 typedef struct DLNodeStruct DLNode;
 
 /** Nodo de la lista doblemente enlazada. */
 typedef struct DLNodeStruct DLNode;


@@ -37,7 +32,14 @@ struct DLNodeStruct {
     DLNode* next;
 };
 
     DLNode* next;
 };
 

-/** Lista doblemente enlazada. */
+/**
+ * Lista doblemente enlazada.
+ *
+ * \see DLList_new(), DLList_delete(), DLList_empty(), DLList_begin(),
+ *      DLList_end(), DLList_have_more(), DLList_current(), DLList_next(),
+ *      DLList_prev(), DLList_unshift(), DLList_push(), DLList_shift(),
+ *      DLList_pop()
+ */

 typedef struct {
     /** Puntero al primer nodo. */
     DLNode* first;
 typedef struct {
     /** Puntero al primer nodo. */
     DLNode* first;


@@ -48,21 +50,28 @@ typedef struct {
 } DLList;
 
 /**
 } DLList;
 
 /**

- * Inicializa la DLList.
+ * Crea una nueva lista.
+ *
+ * \return  Puntero a la nueva DLList o NULL si no hay más memoria.
+ */
+DLList* DLList_new(void);
+
+/**
+ * Libera la memoria ocupada por una lista.

  *
  *

- * \param   list DLList a inicializar.
+ * \param   list DLList a liberar.

  *
  *

- * \return  TRUE si se inicializó bien, FALSE si hay error.
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  */
  */

-bool DLList_init(DLList* list);
+void DLList_delete(DLList* list);

 
 /**
  * Indica si la DLList está vacía.
  *
  * \param   list DLList a verificar.
  *
 
 /**
  * Indica si la DLList está vacía.
  *
  * \param   list DLList a verificar.
  *

- * \return  TRUE si está vacía, FALSE si no.
- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \return  \ref TRUE si está vacía, \ref FALSE si no.
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  */
 bool DLList_empty(DLList* list);
 
  */
 bool DLList_empty(DLList* list);
 


@@ -85,7 +94,7 @@ bool DLList_empty(DLList* list);
  *
  * \return  Primer elemento o NULL si está vacía.
  * \see     DLList_have_more(), DLList_next(), DLList_end(), DLList_prev()
  *
  * \return  Primer elemento o NULL si está vacía.
  * \see     DLList_have_more(), DLList_next(), DLList_end(), DLList_prev()

- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  */
 void* DLList_begin(DLList* list);
 
  */
 void* DLList_begin(DLList* list);
 


@@ -108,7 +117,7 @@ void* DLList_begin(DLList* list);
  *
  * \return  Último elemento o NULL si está vacía.
  * \see     DLList_have_more(), DLList_prev(), DLList_begin(), DLList_next()
  *
  * \return  Último elemento o NULL si está vacía.
  * \see     DLList_have_more(), DLList_prev(), DLList_begin(), DLList_next()

- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  */
 void* DLList_end(DLList* list);
 
  */
 void* DLList_end(DLList* list);
 


@@ -117,9 +126,9 @@ void* DLList_end(DLList* list);
  *
  * \param   list DLList a verificar.
  *
  *
  * \param   list DLList a verificar.
  *

- * \return  TRUE si se puede obtener otro elemento, FALSE si no.
+ * \return  \ref TRUE si se puede obtener otro elemento, \ref FALSE si no.

  * \see     DLList_begin(), DLList_end(), DLList_prev(), DLList_next()
  * \see     DLList_begin(), DLList_end(), DLList_prev(), DLList_next()

- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  */
 bool DLList_have_more(DLList* list);
 
  */
 bool DLList_have_more(DLList* list);
 


@@ -130,7 +139,7 @@ bool DLList_have_more(DLList* list);
  *
  * \return  Elemento actual o NULL si se terminó de recorrer o está vacía.
  * \see     DLList_prev(), DLList_next(), DLList_have_more()
  *
  * \return  Elemento actual o NULL si se terminó de recorrer o está vacía.
  * \see     DLList_prev(), DLList_next(), DLList_have_more()

- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  */
 void* DLList_current(DLList* list);
 
  */
 void* DLList_current(DLList* list);
 


@@ -141,7 +150,7 @@ void* DLList_current(DLList* list);
  *
  * \return  Siguiente elemento o NULL si es el último.
  * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_prev()
  *
  * \return  Siguiente elemento o NULL si es el último.
  * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_prev()

- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  */
 void* DLList_next(DLList* list);
 
  */
 void* DLList_next(DLList* list);
 


@@ -152,7 +161,7 @@ void* DLList_next(DLList* list);
  *
  * \return  Elemento anterior o NULL si es el primero.
  * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_next()
  *
  * \return  Elemento anterior o NULL si es el primero.
  * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_next()

- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  */
 void* DLList_prev(DLList* list);
 
  */
 void* DLList_prev(DLList* list);
 


@@ -162,9 +171,9 @@ void* DLList_prev(DLList* list);
  * \param   list DLList a la cual agregar el elemento.
  * \param   data Elemento a agregar.
  *
  * \param   list DLList a la cual agregar el elemento.
  * \param   data Elemento a agregar.
  *

- * \return  TRUE si se agregó, FALSE si no hay más memoria.
+ * \return  \ref TRUE si se agregó, \ref FALSE si no hay más memoria.

  * \see     DLList_push(), DLList_pop(), DLList_unshift()
  * \see     DLList_push(), DLList_pop(), DLList_unshift()

- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  * \post    El puntero interno de la DLList apunta al nuevo elemento.
  */
 bool DLList_unshift(DLList* list, void* data);
  * \post    El puntero interno de la DLList apunta al nuevo elemento.
  */
 bool DLList_unshift(DLList* list, void* data);


@@ -175,9 +184,9 @@ bool DLList_unshift(DLList* list, void* data);
  * \param   list DLList a la cual agregar el elemento.
  * \param   data Elemento a agregar.
  *
  * \param   list DLList a la cual agregar el elemento.
  * \param   data Elemento a agregar.
  *

- * \return  TRUE si se agregó, FALSE si no hay más memoria.
+ * \return  \ref TRUE si se agregó, \ref FALSE si no hay más memoria.

  * \see     DLList_pop(), DLList_shift(), DLList_unshift()
  * \see     DLList_pop(), DLList_shift(), DLList_unshift()

- * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente.

  * \post    El puntero interno de la DLList apunta al nuevo elemento.
  */
 bool DLList_push(DLList* list, void* data);
  * \post    El puntero interno de la DLList apunta al nuevo elemento.
  */
 bool DLList_push(DLList* list, void* data);


@@ -185,13 +194,23 @@ bool DLList_push(DLList* list, void* data);
 /**
  * Saca el primer elemento de la DLList.
  * Elimina el primer elemento de la DLList devolviendo su contenido.
 /**
  * Saca el primer elemento de la DLList.
  * Elimina el primer elemento de la DLList devolviendo su contenido.

+ * Ejemplo:
+ * \code
+ * DLList* l;
+ * char*   data;
+ * ...
+ * while (!DLList_empty(l)) {
+ *      data = DLList_shift(l);
+ *      printf("El elemento actual es '%s'.\\n", data);
+ * }
+ * \endcode

  *
  * \param   list DLList de la cual sacar el elemento.
  *
  * \return  Primer elemento de la DLList.
  *
  * \param   list DLList de la cual sacar el elemento.
  *
  * \return  Primer elemento de la DLList.

- * \see     DLList_push(), DLList_shift(), DLList_unshift()
- * \pre     La DLList debe estar \ref DLList_init "inicializada" y no
- *          \ref DLList_empty "vacía".
+ * \see     DLList_empty(), DLList_pop()
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente y no
+ *          debe estar \ref DLList_empty "vacía".

  * \post    El puntero interno de la DLList apunta primer elemento.
  */
 void* DLList_shift(DLList* list);
  * \post    El puntero interno de la DLList apunta primer elemento.
  */
 void* DLList_shift(DLList* list);


@@ -199,15 +218,40 @@ void* DLList_shift(DLList* list);
 /**
  * Saca el último elemento de la DLList.
  * Elimina el último elemento de la DLList devolviendo su contenido.
 /**
  * Saca el último elemento de la DLList.
  * Elimina el último elemento de la DLList devolviendo su contenido.

+ * Ejemplo:
+ * \code
+ * DLList* l;
+ * char*   data;
+ * ...
+ * while (!DLList_empty(l)) {
+ *      data = DLList_pop(l);
+ *      printf("El elemento actual es '%s'.\\n", data);
+ * }
+ * \endcode

  *
  * \param   list DLList de la cual sacar el elemento.
  *
  *
  * \param   list DLList de la cual sacar el elemento.
  *

- * \return  último elemento de la DLList.
- * \see     DLList_push(), DLList_shift(), DLList_unshift()
- * \pre     La DLList debe estar \ref DLList_init "inicializada" y no
- *          \ref DLList_empty "vacía".
+ * \return  Último elemento de la DLList.
+ * \see     DLList_empty(), DLList_shift()
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente y no
+ *          debe estar \ref DLList_empty "vacía".

  * \post    El puntero interno de la DLList apunta último elemento.
  */
 void* DLList_pop(DLList* list);
 
  * \post    El puntero interno de la DLList apunta último elemento.
  */
 void* DLList_pop(DLList* list);
 

+/**
+ * Elimina el elemento actual de la DLList.
+ * Elimina el elemento actual de la DLList devolviendo su contenido.
+ *
+ * \param   list DLList de la cual sacar el elemento.
+ *
+ * \return  Elemento actual de la DLList o NULL si no hay más elementos.
+ * \see     DLList_empty(), DLList_current(), DLList_have_more()
+ * \pre     La DLList debe estar \ref DLList_new "creada" correctamente y
+ *          debe \ref DLList_have_more "tener un elemento actual" (por lo que
+ *          también debe estar no \ref DLList_empty "vacía").
+ * \post    El puntero interno de la DLList apunta al próximo elemento.
+ */
+void* DLList_remove_current(DLList* list);
+

 #endif /* DLLIST_H */
 #endif /* DLLIST_H */