1. Introduction

ds_ext is a set of scripts that extend the functionalities provided by the Game Maker: Studio data structures.
The scripts range from really simple utility scripts, like cloning, to more complex functionalities, like sorting grid by multiple columns, and should prove useful for almost every project requiring data structures.

It is important to keep in mind that to keep things consistent with the default Game Maker: Studio behavior, all functionalities that modify or alter in any way the data structure contents, do so directly, without creating a copy (unless stated otherwise).

Jump to:

ds_grid ds_list ds_map ds_priority ds_queue ds_stack
ds_grid_cloneds_list_cloneds_map_cloneds_priority_cloneds_queue_cloneds_stack_clone
ds_grid_multisortds_list_compareds_map_invertds_priority_printds_queue_printds_stack_print
ds_grid_printds_list_concatds_map_keys
ds_grid_remove_colds_list_fillds_map_merge
ds_grid_remove_rowds_list_getds_map_print
ds_list_joinds_map_values
ds_list_paginate
ds_list_parse
ds_list_pop
ds_list_print
ds_list_reverse
ds_list_rotate
ds_list_sample
ds_list_shift
ds_list_slice
ds_list_uniq

 

2. Reference

2.1. ds_grid

ds_grid_clone(grid)

Returns a new ds_grid that's a copy of the provided grid.

Arguments
grid ds_grid ds_grid to clone
ds_grid_multisort(grid,col_1,col_1_asc,[col_2,col_2_asc]...)

Sorts a ds_grid based on multiple columns. Column order determines the priority (hight to low).
Important: due to how GM comparison works, this function can only be used if all the values in a specific sort column belongs to the same type (e.g: string, real, etc.)

Arguments
grid ds_grid ds_grid sort
col_N int column to sort by
col_N_asc boolean whether to sort the column in ascending (true) or descending (false) order
... ... ...
Example 
							ds_grid_multisort(inventory,0,true,2,false);
ds_grid_print(grid)

Prints the contents of the specified ds_grid to the console.

Arguments
grid ds_grid ds_grid to print
ds_grid_remove_col(grid,col)

Removes the specified column from the grid, shifting all the next columns to col-1, and reducing the width of the grid by 1.

Arguments
grid ds_grid ds_grid to clone
col int column index to remove
ds_grid_remove_row(grid,row)

Removes the specified row from the grid, shifting all the next columns to row-1, and reducing the height of the grid by 1.

Arguments
grid ds_grid ds_grid to clone
row int row index to remove

2.2. ds_list

ds_list_clone(list)

Returns a new ds_list that's a copy of the provided list.

Arguments
list ds_list ds_list to clone
ds_list_compare(list1, list2)

Returns whether if list1 and list2 hold the same extact contents.

Arguments
list1 ds_list first list to compare
list2 ds_list second list to compare
Returns
boolean true if the two lists hold the same values, false otherwise
ds_list_concat(dest,list1,[list2],...)

Adds the contents of one or more lists to the first list specified in the arguments as dest.

Arguments
dest ds_list destination list
list_N ds_list list to concatenate to dest
... ... ...
ds_list_fill(list,n,value,[pos])

Fills n positions in the list with a value, starting from position pos.

Arguments
list ds_list ds_list to fill
n int amount of positions to fill
value any value to insert
[pos] int starting position (index). Defaults to 0
ds_list_get(list,pos)

A smarter version of ds_list_find_value. Returns the value at index pos, but wraps pos to the list size. Pos can be a negative number, in which case, the value at the end of the list minus pos is returned.

Arguments
list ds_list ds_list to to get the value from
pos int index of the value to get
Returns
any the value at position pos
Example 
							var last_element = ds_list_get(my_list,-1);
ds_list_join(list,sep)

Returns a string representation the list contents, separated by the provided sep character(s)

Arguments
list ds_list ds_list to to join
sep string separator character(s)
Returns
string string representation of the list
ds_list_paginate(list,page,per_page)

Returns a subset of values from the provided list as a new ds_list. Page acts as an offset for the returned subset.

Arguments
list ds_list source ds_list
page int current page (with 1 being the first page)
per_page int amount of values to return
Returns
ds_list a page subset of the provided list, as a new ds_list
ds_list_parse(string,sep,[ignore_empty],[convert_real])

Divides a string into substrings based on a separator, returning a ds_list of these substrings.

Arguments
string string string to parse
sep string separator character(s)
[ignore_empty] boolean if true, discards empty substring. Defaults to true
[convert_real] boolean if true, applies real() to the substrings. Defaults to false
Returns
ds_list parsed ds_list
ds_list_pop(list)

Removes and returns the last value in a list

Arguments
list ds_list ds_list to pop
Returns
any the value at the end of the list
ds_list_print(list,[show_index])

Prints the contents of the specified ds_list to the console

Arguments
list ds_list ds_list to print
[show_index] boolean if true, shows the list index next to every value. Defaults to false.
ds_list_reverse(list)

Reverses the order of the values in a list.

Arguments
list ds_list ds_list to reverse
ds_list_rotate(list,n)

Shifts the values in a list by n positions, wrapping them at the other end of the list.

Arguments
list ds_list ds_list to rotate
n int amount of the rotation
ds_list_sample(list,n)

Returns a random element from the list, or a ds_list of n random unique elements (if n > 1).

Arguments
list ds_list ds_list to sample from
n int number of elements to return. Defaults to 1.
Returns
ds_list or value a random value if n == 1, a ds_list if n > 1
ds_list_shift(list)

Removes and returns the first element in the list

Arguments
list ds_list ds_list to shift
Returns
any the first element in the list
ds_list_slice(list,from,to)

Returns a subset of a list, as specified by the from and to parameters, as a new ds_list.

Arguments
list ds_list ds_list to slice
from int from index (inclusive)
to int to index (inclusive)
Returns
ds_list a slice of the provided list (as a copy)
ds_list_uniq(list)

Removes all duplicate values from a list, keeping only one copy

Arguments
list ds_list ds_list to check

2.3. ds_map

ds_map_clone(map)

Returns a new ds_map that's a copy of the provided list.

Arguments
map ds_map ds_map to clone
ds_map_invert(map)

Inverts keys and values in the provided ds_map. Multiple copies of the same value will be discarded.

Arguments
map ds_map ds_map to invert
ds_map_keys(map)

Returns a ds_list containing all the keys in the ds_map.

Arguments
map ds_map ds_map to get the keys from
Returns
ds_list a ds_list of the map keys
ds_map_merge(dest_map,other_map)

Tries to merge other_map into dest_map, adding keys/values present in other_map to dest_map if they do not exist.

Arguments
dest_map ds_map destination ds_map
other_map ds_map ds_map to merge into dest_map
ds_map_print(map)

Prints the contents of the specified ds_map to the console

Arguments
map ds_map ds_map to print
ds_map_values(map)

Returns a ds_list containing all the values in the ds_map.

Arguments
map ds_map ds_map to get the values from
Returns
ds_list a ds_list of the map values

2.4. ds_queue

ds_queue_clone(queue)

Returns a new ds_queue that's a copy of the provided queue.

Arguments
queue ds_queue ds_queue to clone
ds_queue_print(queue)

Prints the contents of the specified ds_queue to the console

Arguments
queue ds_queue ds_queue to print

2.5. ds_priority

ds_priority_clone(priority)

Returns a new ds_priority that's a copy of the provided priority.

Arguments
priority ds_priority ds_priority to clone
ds_priority_print(priority)

Prints the contents of the specified ds_priority to the console

Arguments
priority ds_priority ds_priority to print

2.6. ds_stack

ds_stack_clone(stack)

Returns a new ds_stack that's a copy of the provided stack.

Arguments
stack ds_stack ds_stack to clone
ds_stack_print(stack)

Prints the contents of the specified ds_stack to the console

Arguments
stack ds_stack ds_stack to print

5. Credits

Contact me on the Community forums or by email at simoneguerra<at>ekalia.com