Como usar DS List

A Lista de Dados Estruturados serve para armazenar dados em listas como se fossem vetores (arrays) de uma dimensão. A diferença entra usar vetores e DS Lists (Data Structure Lists) é a facilidade em manipular as informações armazenadas e não ser necessário inicializar cada posição, apenas a lista que será usada. Explicarei neste tutorial como criar ds_lists e algumas dicas e exemplos de como utilizá-las.

Apesar de não ser essencial, entender como funcionam arrays ajudará a compreender melhor este tutorial. Veja o tutorial sobre arrays. Para utilizarmos uma lista primeiro é necessário criá-la e armazenar sua id em uma variável:

lista = ds_list_create()

Listas possuem diversas aplicações como: criar inventário, armazenar instâncias, guardar coordenadas, entre outras. Com a função ds_list_add podemos adicionar valores à lista, por exemplo:

ds_list_add(lista, 10, 5, 3)

É possível adicionar até 15 valores cada vez que chamarmos essa função. É importante lembrar que com essa função os valores vão diretamente para o final da lista. Porém, se utilizarmos a função ds_list_insert, podemos fazer com que o valor seja inserido na posição 0 e, se houverem outros valores, todos subirão uma posição, por exemplo:

ds_list_insert(lista, 0, 4)

Como já temos 3 valores na nossa lista, o valor 4 será inserido na posição 0, fazendo com que as novas posições de 3, 5 e 10 sejam respectivamente 1, 2 e 3. Lembre-se que a primeira posição é na verdade a 0 e não a 1. Se quisermos excluir um dos valores, que nestes exemplos será o 5, podemos fazer das seguintes maneiras:

ds_list_delete(lista, 1)

Possível apenas se soubermos exatamente a posição do item que queremos eliminar, ou:

pos = ds_list_find_index(lista, 5)

ds_list_delete(lista, pos)

Neste caso, se não soubermos a posição em que se encontra o 5, basta usar ds_list_find_index para encontrá-la, como feito no exemplo. Quando deletamos uma informação da lista, todas posteriores passam a ocupar uma posição a menos. Se deletarmos o conteúdo da posição 3, o que estava na posição 4 passará a ocupar a 3, o que estava na 5 irá ocupar a 4, e assim por diante.

Para acessar informações em uma posição específica na lista é necessário utilizar um acessor.

xx = lista[ | 2]

Neste exemplo armazenei o valor que está na posição 2 na variável "xx".

Quando uma lista não é mais necessária é preciso destruí-la utilizando ds_list_destroy(lista). Caso não seja feito, haverá perda de desempenho do seu jogo.

Como podem ver, é extremamente fácil utilizar DS Lists e estas podem ser aplicadas nas mais diversas situações. Seguem outras funções importantes para o uso das listas:

ds_list_clear(lista) - Limpa uma lista.

ds_list_copy(lista_destino, lista_fonte) - Faz uma cópia idêntica da "lista_fonte" para a "lista_destino". Toda informação que já estava na "lista_destino" é perdida.

ds_list_empty(lista) - Verifica se uma lista está vazia e retorna true ou false.

ds_list_size(lista) - Retorna o tamanho da lista.

ds_list_find_value(lista, pos) - Retorna a informação armazenada na posição informada.

ds_list_replace(lista, pos, valor) - Substitui a informação da posição escolhida pelo valor indicado.

ds_list_shuffle(lista) - Embaralha a lista.

ds_list_sort(lista, true/false) - Organiza a lista em ordem crescete(true) ou decrescente(false).

ds_list_read(lista, arquivo) - Recupera uma lista salva em arquivo.

ds_list_write(lista) - Salva a lista em um arquivo.