#ifndef DLLIST_H
#define DLLIST_H
-
/** Tipo de dato booleano. */
typedef enum {
FALSE, /**< Falso. */
DLNode* next;
};
-/** Lista doblemente enlazada. */
-typedef struct DLListStruct DLList;
-
-/** Lista doblemente enlazada. */
-struct DLListStruct {
+/**
+ * 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;
/** Puntero al nodo actual. */
DLNode* current;
/** Puntero al último nodo. */
DLNode* last;
-};
+} DLList;
/**
- * Inicializa la DLList.
- * Se crea (alocando memoria) e inicializa la DLList.
+ * Crea una nueva lista.
*
- * \param list DLList a inicializar.
+ * \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.
*
- * \return TRUE si se inicializó bien, FALSE si hay error.
- * \post Se crea una nueva DLList, reservando una porción de memoria.
+ * \param list DLList a liberar.
+ *
+ * \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.
*
- * \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);
/**
- * Reinicia la DLList devolviendo el primer elemento.
- * Hace que el elemento actual de la DLList vuelva a ser el primero.
- * Siempre que se quiera recorrer la DLList debería usarse esta función
- * primero. Por ejemplo:
+ * Apunta al primer elemento de la DLList devolviendolo.
+ * Hace que el elemento actual de la DLList sea el primero y devuelve su valor.
+ * Si está vacía, devuelve NULL.
+ * Siempre que se quiera recorrer la DLList de izquierda a derecha debería
+ * usarse esta función primero. Por ejemplo:
* \code
- * DLList* list;
- * NodeType* node;
+ * DLList* l;
+ * char* data;
* ...
- * for (node = DLList_reset(list); node; node = DLList_next(list)) {
- * printf("Uso el elemento actual aquí.\\n");
+ * for (data = DLList_begin(l); DLList_have_more(l); data = DLList_next(l)) {
+ * printf("El elemento actual es '%s'.\\n", data);
* }
* \endcode
*
- * \param list DLList de la cual obtener el siguiente elemento.
+ * \param list DLList de la cual obtener el primer elemento.
*
- * \return Puntero al primer elemento o NULL si está vacía.
- * \see DLList_current()
- * \see DLList_next()
- * \pre La DLList debe estar \ref DLList_init "inicializada".
+ * \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_new "creada" correctamente.
*/
-void* DLList_reset(DLList* list);
+void* DLList_begin(DLList* list);
+
+/**
+ * Apunta al último elemento de la DLList devolviendolo.
+ * Hace que el elemento actual de la DLList sea el último y devuelve su valor.
+ * Si está vacía, devuelve NULL.
+ * Siempre que se quiera recorrer la DLList de derecha a izquierda debería
+ * usarse esta función primero. Por ejemplo:
+ * \code
+ * DLList* l;
+ * char* data;
+ * ...
+ * for (data = DLList_end(l); DLList_have_more(l); data = DLList_prev(l)) {
+ * printf("El elemento actual es '%s'.\\n", data);
+ * }
+ * \endcode
+ *
+ * \param list DLList de la cual obtener el último elemento.
+ *
+ * \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_new "creada" correctamente.
+ */
+void* DLList_end(DLList* list);
+
+/**
+ * Indica si se puede obtener otro elemento de la lista en una iteración.
+ *
+ * \param list DLList a verificar.
+ *
+ * \return \ref TRUE si se puede obtener otro elemento, \ref FALSE si no.
+ * \see DLList_begin(), DLList_end(), DLList_prev(), DLList_next()
+ * \pre La DLList debe estar \ref DLList_new "creada" correctamente.
+ */
+bool DLList_have_more(DLList* list);
/**
* Obtiene el elemento actual de la DLList.
* \param list DLList de la cual obtener el elemento actual.
*
* \return Elemento actual o NULL si se terminó de recorrer o está vacía.
- * \see DLList_reset()
- * \see DLList_next()
- * \pre La DLList debe estar \ref DLList_init "inicializada".
+ * \see DLList_prev(), DLList_next(), DLList_have_more()
+ * \pre La DLList debe estar \ref DLList_new "creada" correctamente.
*/
void* DLList_current(DLList* list);
*
* \param list DLList de la cual obtener el siguiente elemento.
*
- * \return Puntero al próximo elemento o NULL si es el último.
- * \see DLList_reset()
- * \see DLList_current()
- * \pre La DLList debe estar \ref DLList_init "inicializada".
+ * \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_new "creada" correctamente.
*/
void* DLList_next(DLList* list);
+/**
+ * Obtiene el elemento anterior de la DLList.
+ *
+ * \param list DLList de la cual obtener el elemento anterior.
+ *
+ * \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_new "creada" correctamente.
+ */
+void* DLList_prev(DLList* list);
+
/**
* Agrega un elemento al inicio de la DLList.
*
* \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.
- * \see DLList_push()
- * \see DLList_pop()
- * \see DLList_unshift()
- * \pre La DLList debe estar \ref DLList_init "inicializada".
+ * \return \ref TRUE si se agregó, \ref FALSE si no hay más memoria.
+ * \see DLList_push(), DLList_pop(), DLList_unshift()
+ * \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);
* \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.
- * \see DLList_pop()
- * \see DLList_shift()
- * \see DLList_unshift()
- * \pre La DLList debe estar \ref DLList_init "inicializada".
+ * \return \ref TRUE si se agregó, \ref FALSE si no hay más memoria.
+ * \see DLList_pop(), DLList_shift(), DLList_unshift()
+ * \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);
/**
* 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.
- * \see DLList_push()
- * \see DLList_shift()
- * \see 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);
/**
* 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.
*
- * \return último elemento de la DLList.
- * \see DLList_push()
- * \see DLList_shift()
- * \see 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);
+/**
+ * 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 */
projects / z.facultad / 75.42 / calculadora.git / blobdiff