X-Git-Url: https://git.llucax.com/z.facultad/75.42/calculadora.git/blobdiff_plain/f74ef52ac13755f7680dbad22168b8d8e8b98e63..5fc156b9719666605c58ee239a6d0a2c16843d09:/dllist.h diff --git a/dllist.h b/dllist.h index dc26214..10edb6c 100644 --- a/dllist.h +++ b/dllist.h @@ -17,7 +17,6 @@ #ifndef DLLIST_H #define DLLIST_H - /** Tipo de dato booleano. */ typedef enum { FALSE, /**< Falso. */ @@ -37,62 +36,105 @@ struct DLNodeStruct { 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. @@ -100,9 +142,8 @@ void* DLList_reset(DLList* list); * \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); @@ -111,24 +152,33 @@ 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); @@ -138,42 +188,74 @@ 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 */