Version 4.0.0
gdash is a functional utility library for GML, inspired by lodash. It aims to add useful, broad-purposed functions to help aid in game development. If you are doing any kind of data manipulation in your game, gdash can help out.
- Install
- API
_and(valueA, valueB)_array_of(values...)_clone_array(array)_collect(object)_concat(arrayA, arrayB)_contains(collection, target [, fromIndex, dsType])_destroy(object)_error(message [, fatal])_filter(collection, script)_find(array, findScript)_free(id [, ds_type])_get(map, locationString)_index_of(collection, value)_is_equal(valueA, valueB [, dsType])_join(array, joinChar)_keys(map)_length(collectionOrString)_list_of(values...)_log(values...)_map_of(values...)_map(collection, script [, ds_type])_nth(collection, index)_or(valueA, valueB)_partial(script, partialArgs...)_push(array, value)_reduce(collection, reducer)_reverse(array)_run(scriptOrPartial, arguments...)_set(map, locationString, value)_slice(array, start [, end])_split(string, splitChar)_spread(script, argsArray)_times(script)_to_array(list)_to_list(array)_type_of(value)_uniq(array)
Download the latest release and import the gml files into your project's scripts. For GameMaker: Studio 2, you can just drag and drop the files into the editor.
Returns the value of the provided arguments after a boolean and
@param {*} valueA Some first input
@param {*} valueB A value to && the first input with
@returns {Boolean} The value of the provided arguments after an &&
@example
_and(true, true);
// => true
_and(false, true);
// => false
Returns an array of the given arguments.
@param {*) values... Values to put into an array
@returns {Array} An array of the given parameters
@example
_arrayOf(1, 2, 3);
// => [1, 2, 3];
_arrayOf('hello', 'world', 'i', 'am', 'an', 'array');
// => ['hello', 'world', 'i', 'am', 'an', 'array'];Clones a given input array, returning a deep copy.
@param {Array} array The array to clone
@returns {Array} A copy of the input array
@example
var myArray = [1, 2, 3];
var copyArray = _clone_array(myArray);
_is_equal(myArray, copyArray)
// => trueReturns an array of all objects of the provided type
@param {ObjectType} objectType The object type to collect
@returns {Array} An array of all object IDs of the provided type in the room
@example
_collect(obj_character);
// => [10001, 10002, 10005]Appends the values of one array to another.
@param {Array} baseArray The array to append to
@param {Array} arrayToAppend The array to append
@returns {Array} The concatenated array
@example
_concat([0, 1, 2], [3, 4, 5]);
// => [0, 1, 2, 3, 4, 5]
Returns true if the given array contains the given value, otherwise returns false
@param {String|Array|DS_Map|DS_List} collection The collection to search
@param {*} value The value to look for
@param {Real} optionalFromIndex [0] The index to begin looking from
@param {ds_type} optionalDSType [ds_type_list] The type of the ds, if this is a ds.
@returns {Boolean} True if the collection contains the target, otherwise false
@example
_contains([1, 2, 3], 1);
// => true
_contains([1, 2, 3], 1, 1);
// => false
_contains("hello", "ello");
// => trueDestroys the passed in instance
@param {Instance} instance The instance to destroy
@example
_destroy(obj_enemy);
// Destroy all obj_enemy with no health (hasNoHealth is a script)
_map(_filter(_collect(obj_enemy)), hasNoHealth), _destroy);When running with the debugger, displays an error window. Otherwise, logs an error using _log.
Note: Only mark an error as
fatalif you are okay with it ending your game
@param {String} message The message to error with
@param {Boolean} fatal [Optional] If true, will force a show_error() call with `abort` set to true
@example
_error("This is an error that will let the game continue");
_error("This is an error that will let the game continue", false);
_error("This is an error that will kill the game", true);Returns a collection where values of the input collection are truthy when run through the provided function.
@param {Array|ds_list} collection The collection to filter
@param {Script} filterScript The script to filter with
@returns {Array|ds_list} The filtered collection
@example
_filter([0, 1, 2, 3], lessThanTwo)
// => [0, 1]
Iterates over an array, returning the first element that the given script returns true for.
@param {Array} array The array to iterate over
@param {Script} findScript The script to run on the given element
@returns {*} The first element that returns truthy from the script
@example
_find([0, 1, 2, 3], __equalsThree);
// => 3Frees a partial function from memory
@param {Real} resource The partial ID to free
@param {DS_TYPE} optionalType The type of resource to free
@example
var __something = _partial(someScript, 1);
__something(2);
_free(__something);
Gets a nested value following a dot notation
@param {DS_Map} map The map to get data from
@param {String} locationString The location of the data to get
@returns {Mixed} The data found at the given location
@example
// someMap looks like:
// { nested: {three: {deep: 1}}}
_.get(someMap, 'nested.three.deep');
// => 1
Returns the index of the given item in the given array, or -1
@param {Array|DS_List} collection The collection to search
@param {*} value The value to look for
@returns {Real} The index of the value, or -1
Checks if two values are equal, being safe about type and checking first-level children of ds_lists and ds_maps. Returns false on type inequality rather than throwing an error.
@param {*} firstValue First value to compare
@param {*} secondValue Second value to compare
@param {ds_type} dsType [Optional] If specified, assumes this type instead of inferring the type. Only specify this if using _is_equal for a ds
@returns {Boolean} true if the values are equal, false otherwise
@example
_is_equal([1, 2, 3], [1, 2, 3]);
// => true
_is_equal("hello", 1);
// => false
var map = ds_map_create();
ds_map_add(map, 'hello', 6);
ds_map_add(map, 'world', 10);
var map2 = ds_map_create();
ds_map_add(map2, 'hello', 6);
ds_map_add(map2, 'world', 10);
_is_equal(map, map2, ds_type_map);
// => trueReturns a string of the given array combined with the given joiner
@param {Array} array The array to join
@param {String} joinChar The character to join by
@returns {String} The joined array
@example
var arr = ['hello', 'world'];
_join(arr, ' ');
// => 'hello world'
var arr = ['Peter', 'Paul', 'Mary'];
_join(arr, ', ');
// => 'Peter, Paul, Mary';Returns an array contains all keys in a ds_map. Order is not guaranteed due to how ds_maps are stored.
@param {DS_Map} map The map to get the keys from
@returns {Array} An array of all keys in the map
@example
var map = ds_map_create();
ds_map_add(map, 'hello', 'world');
ds_map_add(map, 'health', 100);
_keys(map);
// => ['hello', 'health']
Returns the length of the given array or ds_list
@param {Array|DS_List} collection The collection to determine the length of
@returns {Real} The length of the collection
@example
_length([1, 2, 3, 4]);
// => 4
_length(some_list_id_of_size_5);
// => 5Returns a DS_List containing the provided values. This DS_List should be destroyed as you would any other DS.
@param {*} values... As many starting values for the list as desired
@returns {DS_List} A new DS_List containing the provided values
@example
var list = _list_of(1, 2, 3, 4);
_log(list[| 2]) // logs 3Convenience method for show_debug_message(). Automatically convetrs arguments to strings.
@param {Mixed} Messages... The message or value to log
Returns a DS_Map containing the provided values. Arguments are split into key/value pairs in the order they are provided.
Note: This script must take an even number of arguments. Keys can only be integers or strings.
@param {*} values... As many starting values for the map as desired
@returns {DS_Map} A new DS_Map containing the provided key/value pairs
@example
var map = _map_of(
"health", 100,
"mana", 20,
"level", 1
);
map[? "health"] // = 100
map[? "mana"] // = 20
map[? "level"] // = 1
Iterates over a given collection, running the provided function for each value in the collection. Returns an array of all function results at each index.
@param {Array|DS_Map|DS_List} collection The collection to map
@param {Script} script The script to map over the collection
@param {ds_type|String} optionalType ["array"] The type of collection. Only provide when using a DS
@returns {Array} An array of all mapped results
@example
var arr;
arr[0] = 1; arr[1] = 2;
_map(arr, doubleValue);
// => [2, 4];
var map = ds_map_create();
ds_map_add(map, 'hello', 6);
ds_map_add(map, 'world', 10);
_map(map, divideByTwo, ds_type_map);
// => [3, 5]Returns the nth index of the given array or ds_list. If n is negative, the nth element from the end is returned.
@param collection
@param n
Returns the value of the provided arguments after a boolean OR
@param {*} valueA Some first input
@param {*} valueB A value to || the first input with
@returns {Boolean} The value of the provided arguments after an ||
@example
_or(true, true);
// => true
_or(false, true);
// => true
_or(false, false);
// => false
Creates a partial function identifier for use in place of raw scripts in gdash functions, or with the use of _run.
Note: Partials are to be treated as a data structure, and must be cleaned up with _free() when they are no longer of use.
@param {Script} script The script to create a partial of
@param {*} partialArguments... Arguments to bind to the partial
@returns {Real} The partial ID (a ds_map, internally)
@example
// Script: lessThan
return argument1 < argument0
// Meanwhile...
var lessThanTwo = _partial(lessThan, 2);
_run(lessThanTwo, 1);
// => true
_run(lessThanTwo, 10);
// => false
Adds a value to the end of an array
@param {Array} array The array to add the value to
@param {*} value The value to add
@returns {Array} The array with the value added
@example
_push([1, 2], 3);
// => [1, 2, 3]Reduces a collection by iterating over it with a function. Provided script should take 2 arguments: total, value.
@param {Array|ds_list} collection The collection to reduce
@param {Script} recuderScript The script to reduce with
@param {*} value [Optional] The default value to begin reducing with. If not provided, the default is `undefined`
@returns {*} The reduced value from the given script
@example
var arr = [1, 2, 3, 4, 5];
_reduce(arr, sum);
// => 15
var arr = ['hello', 'world'];
_reduce(arr, concat);
// => 'helloworld';Reverses a given input array
@param {Array} array The array to reverse
@returns {Array} The reversed array
@example
var myArray = [1, 2, 3];
var reverseArray = _reverse(myArray);
// => [3, 2, 1]Executes a script or partial with the provided arguments
@param {Script|Real} scriptOrPartial The script to run or the ID of the partial to run
@param {*} arguments... Arguments to pass the script
@returns {*} The return value of the script
@example
_run(_add, 1, 2);
// => 3
var addTwo = _partial(_add, 2);
_run(addTwo, 1);
// => 3Sets a nested value following a dot notation. Creates along the way if its not set.
@param {DS_Map} map The map to set data in
@param {String} locationString The location of the data to set
@param {Mixed} value The data to set
@param {ds_type_map|ds_type_list} optionalType Optional argument, pass in ds_type_map or ds_type_list to denote this value as a map or list
@example
// someMap looks like:
// { nested: {three: {deep: 1}}}
_set(someMap, 'nested.three.deep', 2);
// => someMap now looks like:
// => {nested: {three: {deep: 2}}}
// some map looks like:
// { someKey: "someValue" }
_set(someMap, "newKey", ds_list_create(), ds_type_list);
// => someMap now looks like:
// => { someKey: "someValue"], newKey: [] }
Creates a slice of array from start up to, but not including, end.
@param {Array} array The array to slice
@param {Integer} start Index to start the slice
@param {Integer} end(optional) Index up to which to make the slice, defaults to end of array.
@returns {Array} The sliced array
@example
var myArray = [1, 2, 3, 4];
var slicedArray = _slice(myArray, 1, 3);
_is_equal([2, 3], slicedArray)
// => trueReturns an array of strings represnting the given string separated by a given substring
@param {String} string The string to split
@param {String} splitChar The character to split by
@returns {Array} The split string
@example
_split('Hello, world', ',');
// => ['Hello', ' world']
_split('Dogs and cats and mice', ' and ');
// => ['Dogs', 'cats', 'mice']Runs a script with the provided array as arguments
@param {Script} script The script to run
@param {Array} arrayOfArguments An array to provide as individual arguments
@return {*} The return value of the script
@example
_spread(add_to_list, [listId, 1, 2, 3, 4]);
// => List now contains 1, 2, 3, 4Returns an array of the result of a function run the given number of times
@param {Real} executeCount The number of times to execute the function
@param {Script} script The script to execute
@returns {Array} An array of the script results
@example
_times(3, returnTheValue5);
// => [5, 5, 5];
Converts the given ds_list to an array
Note: If the given list is of size 0, this will return undefined.
@param list
Converts the given array to a new ds_list
@param array
@example
var input = ["hello", "world", 10];
var list = _to_list(input);
list[| 0]; // "hello"
list[| 1]; // "world"
list[| 2]; // 10Returns the variable type of the given argument as a string.
Note: Works exactly as the native typeof(), though refers to
numberasrealto be more consistent with GM:S terminology
@param {*} value A variable to check the type of
@returns {String} The type of the variable as a human readable string
@example
_type_of(1);
// => "real"
_type_of("hello");
// => "string"
var arr;
arr[0] = 1; arr[1] = 2;
_type_of(arr);
// => "array"
_type_of(undefined);
// => "undefined";
_type_of(sprite_get_texture(spr_player, 1));
// => "ptr";Returns an array with all duplicate values removed
@param {Array} array An array with duplicate values
@returns {Array} An array with the duplicate values removed
@example
_uniq([1, 1, 2, 3]);
// => [1, 2, 3]