X-Git-Url: https://git.llucax.com/z.facultad/75.42/calculadora.git/blobdiff_plain/f74ef52ac13755f7680dbad22168b8d8e8b98e63..f7547b1b03c5f2554012658ef7aeafee91c7227c:/dllist.h diff --git a/dllist.h b/dllist.h index dc26214..4a44446 100644 --- a/dllist.h +++ b/dllist.h @@ -37,27 +37,28 @@ struct DLNodeStruct { DLNode* next; }; -/** Lista doblemente enlazada. */ -typedef struct DLListStruct DLList; - -/** Lista doblemente enlazada. */ -struct DLListStruct { +/** + * Lista doblemente enlazada. + * + * \see DLList_init(), 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. * * \param list DLList a inicializar. * - * \return TRUE si se inicializó bien, FALSE si hay error. - * \post Se crea una nueva DLList, reservando una porción de memoria. + * \return \ref TRUE si se inicializó bien, \ref FALSE si hay error. */ bool DLList_init(DLList* list); @@ -66,33 +67,67 @@ bool DLList_init(DLList* list); * * \param list DLList a verificar. * - * \return TRUE si está vacía, FALSE si no. + * \return \ref TRUE si está vacía, \ref FALSE si no. * \pre La DLList debe estar \ref DLList_init "inicializada". */ 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() + * \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". */ -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_init "inicializada". + */ +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_init "inicializada". + */ +bool DLList_have_more(DLList* list); /** * Obtiene el elemento actual de la DLList. @@ -100,8 +135,7 @@ 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() + * \see DLList_prev(), DLList_next(), DLList_have_more() * \pre La DLList debe estar \ref DLList_init "inicializada". */ void* DLList_current(DLList* list); @@ -111,24 +145,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() + * \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". */ 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_init "inicializada". + */ +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() + * \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_init "inicializada". + * \post El puntero interno de la DLList apunta al nuevo elemento. */ bool DLList_unshift(DLList* list, void* data); @@ -138,41 +181,58 @@ 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() + * \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_init "inicializada". + * \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() + * \see DLList_empty(), DLList_pop() * \pre La DLList debe estar \ref DLList_init "inicializada" y no - * \ref DLList_empty "vacía". + * \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() + * \return Último elemento de la DLList. + * \see DLList_empty(), DLList_shift() * \pre La DLList debe estar \ref DLList_init "inicializada" y no - * \ref DLList_empty "vacía". + * \ref DLList_empty "vacía. + * \post El puntero interno de la DLList apunta último elemento. */ void* DLList_pop(DLList* list);