DS Lists

A ds_list stores a collection of values in a particular order.

A ds_list is a data-structure that stores information sequentially as it is added (much like a 1D array). Ds lists are very flexible data structures that permit you to add values at the end or insert them somewhere in the middle of the list, as well as giving you the ability to shuffle the order (to randomize the values) or sort them in an ascending or descending order.

When accessing DS list data structures, you should always try to use integer values for the list position, and all non-integer indices will be floored by GameMaker: Studio if you do not. If that is not what you require, then you will need to do the rounding yourself previously before passing the index that you wish to check.

NOTE: As with all dynamic resources, data structures take up memory and so should always be destroyed when no longer needed to prevent memory leaks which will slow down and eventually crash your game.

The following functions exist that deal with DS lists.

1. ds_list_create
   
2. ds_list_destroy
   
3. ds_list_clear
   
4. ds_list_empty
   
5. ds_list_size
   
6. ds_list_add
   
7. ds_list_set
   
8. ds_list_delete
   
9. ds_list_find_index
   
10. ds_list_find_value
    
11. ds_list_insert
    
12. ds_list_replace
    
13. ds_list_shuffle
    
14. ds_list_sort
    
15. ds_list_copy
    
16. ds_list_read
    
17. ds_list_write
    

Ds_lists can be used hold ds_maps and other ds_lists too, but only for use in conjunction with the json_encode function. This requires that you "flag" or "mark" the entry within the list so that it can be encoded correctly using the following special functions:

1. ds_list_mark_as_list
   
2. ds_list_mark_as_map
   

Apart from these specific functions you can all use an expression (called an accessor) to add or modify the contents of your ds_list. This accessor looks similar to a 1D array with the following syntax:

list_index[| index]

You can find more information, plus examples, from from the GML Overview page on Accessors.

NOTE: if you need to check if a data structure exists, you can use the ds_exists() function.

© Copyright YoYo Games Ltd. 2018 All Rights Reserved