diff options
Diffstat (limited to 'block_list.h')
| -rw-r--r-- | block_list.h | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/block_list.h b/block_list.h new file mode 100644 index 0000000..cd87f1d --- /dev/null +++ b/block_list.h @@ -0,0 +1,146 @@ +/* + * block_list.h -- Implementa las listas de bloques. + * Copyright (C) 2018 Juan Marín Noguera + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <https://www.gnu.org/licenses/>. + */ + +/** + * \file block_list.h Implementa las listas de bloques. + */ + +#ifndef __BLOCK_LIST_H +#define __BLOCK_LIST_H +#include "block.h" +#include "screen.h" + +/** Representa un nodo de la lista de bloques. Usado para iterar sobre esta. */ +typedef struct BlockNode *BlockNode; + +/** Representa una lista de bloques. */ +typedef struct BlockList *BlockList; + +/** + * \brief Crea una lista vacía de bloques. + * \return Una nueva lista vacía de bloques. + */ +BlockList block_list_create(); + +/** + * \brief Libera una lista de bloques, junto con todos sus elementos. + * \param bl La lista de bloques a liberar. + * \remarks Si la lista es liberada, todo iterador sobre ella dejará de + * ser válido (ver block_list_begin). + */ +void block_list_free(BlockList bl); + +/** + * \brief Devuelve un iterador para la lista, que apunta al primer elemento de + * esta (si existe). + * \param bl La lista sobre la que iterar. + * \return Iterador de la lista apuntando al primer elemento. Si la lista + * está vacía, el iterador apunta al final (ver block_list_isend). + */ +BlockNode block_list_begin(BlockList bl); + +/** + * \brief Devuelve el bloque apuntado por un iterador de lista de bloques. + * \param bn El iterador. + * \return El elemento actual al que apunta el iterador. + */ +Block block_list_current(BlockNode bn); + +/** + * \brief Devuelve un iterador que apunta al elemento siguiente al que apunta + * este. + * \param bn El iterador. + * \return Un iterador al siguiente elemento. + * \remarks No se debe liberar el apuntador anterior al reemplazarlo por el + * nuevo (ni en ningún otro caso). Si bn apunta al último + * elemento, el iterador devuelto apuntará al final (ver + * block_list_isend). + */ +BlockNode block_list_next(BlockNode bn); + +/** + * \brief Elimina de la lista el elemento actual al que apunta el iterador (el + * devuelto por block_list_current), liberándolo. + * \param bn El iterador. + * \remarks Tras llamar a esta función, el iterador apuntará al + * elemento siguiente al que apuntaba. + */ +void block_list_delete(BlockNode bn); + +/** + * \brief Elimina de la lista el elemento actual al que apunta el iterador (el + * devuelto por block_list_current), pero sin liberar la memoria ocupada por + * el bloque en sí. + * \param bn El iterador. + * \remarks Tras llamar a esta función, el iterador apuntará al + * elemento siguiente al que apuntaba. + */ +void block_list_delete_preserving(BlockNode bn); + +/** + * \brief Comprueba si el apuntador pasado como parámetro apunta al + * final. + * \param bn El iterador. + * \return Un valor distinto de 0 si el elemento es el final, o 0 si no lo es. + * \remarks Es un error llamar a block_list_current, block_list_next o + * block_list_delete con un iterador que apunta al final, pues es como si + * apuntase al elemento posterior al último. + */ +int block_list_isend(BlockNode bn); + +/** + * \brief Comprueba si la lista de bloques es vacía. + * \param bl La lista a comprobar. + * \return Un valor distinto de 0 si la lista es vacía, o 0 si no lo es. + */ +int block_list_isempty(BlockList bl); + +/** + * \brief Añade un elemento al final de la lista. + * \param bl La lista en la que añadir el elemento. + * \param e El elemento a añadir. + */ +void block_list_append(BlockList bl, Block e); + +/** + * \brief Ordena una lista de bloques según la coordenada horizontal de + * los bloques. + * \param bl La lista de bloques a ordenar. + * \return La lista de bloques ordenada. + * \remarks Esta función libera la memoria ocupada por la lista de + * bloques que se le pasa como parámetro, salvo la correspondiente a los + * bloques en sí, que pasa a ser accesible desde la lista de bloques + * devuelta. La función asume que la coordenada horizontal de todos los + * bloques es mayor o igual a cero; de lo contrario la lista devuelta + * podrí no estar bien ordenada. + */ +BlockList block_list_sort(BlockList bl); + +/** + * \brief Dibuja todos los elementos de la lista de bloques, suponiendo que + * están ordenados por posición en el mundo de izquierda y derecha + * y eliminando los elementos que quedan a la izquierda del área visible + * del mundo. + * \param bl La lista de bloques. + * \param scr La ventana sobre la que dibujar los bloques. + * \param scroll La distnacia en píxeles desde la parte izquierda del + * mundo hasta la parte izquierda de la ventana. + */ +void block_list_render(Screen scr, BlockList bl, int scroll); + +#endif // __BLOCK_LIST_H |