code/__HELPERS/_lists.dm
| LIST_VALUE_WRAP_LISTS | If value is a list, wrap it in a list so it can be used with list add/remove operations |
|---|---|
| UNTYPED_LIST_ADD | Add an untyped item to a list, taking care to handle list items by wrapping them in a list to remove the footgun |
| UNTYPED_LIST_REMOVE | Remove an untyped item to a list, taking care to handle list items by wrapping them in a list to remove the footgun |
| LAZYINITLIST | Initialize the lazylist |
| UNSETEMPTY | If the provided list is empty, set it to null |
| ASSOC_UNSETEMPTY | If the provided key -> list is empty, remove it from the list |
| LAZYLISTDUPLICATE | Like LAZYCOPY - copies an input list if the list has entries, If it doesn't the assigned list is nulled |
| LAZYREMOVE | Remove an item from the list, set the list to null if empty |
| LAZYADD | Add an item to the list, if the list is null it will initialize it |
| LAZYOR | Add an item to the list if not already present, if the list is null it will initialize it |
| LAZYFIND | Returns the key of the submitted item in the list |
| LAZYACCESS | returns L[I] if L exists and I is a valid index of L, runtimes if L is not a list |
| LAZYSET | Sets the item K to the value V, if the list is null it will initialize it |
| LAZYSETLEN | Sets the length of a lazylist |
| LAZYLEN | Returns the length of the list |
| LAZYNULL | Sets a list to null |
| LAZYADDASSOC | Adds to the item K the value V, if the list is null it will initialize it |
| LAZYADDASSOCLIST | This is used to add onto lazy assoc list when the value you're adding is a /list/. This one has extra safety over lazyaddassoc because the value could be null (and thus cant be used to += objects) |
| LAZYREMOVEASSOC | Removes the value V from the item K, if the item K is empty will remove it from the list, if the list is empty will set the list to null |
| LAZYACCESSASSOC | Accesses an associative list, returns null if nothing is found |
| QDEL_LAZYLIST | Qdel every item in the list before setting the list to null |
| LAZYCOPY | Use LAZYLISTDUPLICATE instead if you want it to null with no entries |
| LAZYCLEARLIST | Consider LAZYNULL instead |
| SANITIZE_LIST | Returns the list if it's actually a valid list, otherwise will initialize it |
| LAZYORASSOCLIST | Performs an insertion on the given lazy list with the given key and value. If the value already exists, a new one will not be made. |
| LISTASSERTLEN | Ensures the length of a list is at least I, prefilling it with V if needed. if V is a proc call, it is repeated for each new index so that list() can just make a new list for each item. |
| COMPARE_KEY | Passed into BINARY_INSERT to compare keys |
| COMPARE_VALUE | Passed into BINARY_INSERT to compare values |
| BINARY_INSERT | Binary search sorted insert INPUT: Object to be inserted LIST: List to insert object into TYPECONT: The typepath of the contents of the list COMPARE: The object to compare against, usualy the same as INPUT COMPARISON: The variable on the objects to compare COMPTYPE: How should the values be compared? Either COMPARE_KEY or COMPARE_VALUE. |
| BINARY_INSERT_PROC_COMPARE | Custom binary search sorted insert utilising comparison procs instead of vars. INPUT: Object to be inserted LIST: List to insert object into TYPECONT: The typepath of the contents of the list COMPARE: The object to compare against, usualy the same as INPUT COMPARISON: The plaintext name of a proc on INPUT that takes a single argument to accept a single element from LIST and returns a positive, negative or zero number to perform a comparison. COMPTYPE: How should the values be compared? Either COMPARE_KEY or COMPARE_VALUE. |
| BINARY_INSERT_DEFINE | Even more custom binary search sorted insert, using defines instead of vars INPUT: Item to be inserted LIST: List to insert INPUT into TYPECONT: A define setting the var to the typepath of the contents of the list COMPARE: The item to compare against, usualy the same as INPUT COMPARISON: A define that takes an item to compare as input, and returns their comparable value COMPTYPE: How should the list be compared? Either COMPARE_KEY or COMPARE_VALUE. |
| /proc/english_list | Returns a list in plain english as a string |
| /proc/is_type_in_list | Checks for specific types in a list. |
| /proc/is_path_in_list | Checks for specific paths in a list. |
| is_type_in_typecache | Checks for specific types in specifically structured (Assoc "type" = TRUE|FALSE) lists ('typecaches') |
| /proc/typecache_filter_list | returns a new list with only atoms that are in the typecache list |
| /proc/typecache_filter_list_reverse | return a new list with atoms that are not in the typecache list |
| /proc/typecache_filter_multi_list_exclusion | similar to typecache_filter_list and typecache_filter_list_reverse but it supports an inclusion list and and exclusion list |
| /proc/typecacheof | Like typesof() or subtypesof(), but returns a typecache instead of a list. |
| /proc/zebra_typecacheof | Like typesof() or subtypesof(), but returns a typecache instead of a list. This time it also uses the associated values given by the input list for the values of the subtypes. |
| /proc/list_clear_nulls | Removes any null entries from the list Returns TRUE if the list had nulls, FALSE otherwise |
| /proc/list_clear_empty_weakrefs | Removes any empty weakrefs from the list Returns TRUE if the list had empty refs, FALSE otherwise |
| /proc/pick_weight | Picks a random element from a list based on a weighting system. For example, given the following list: A = 6, B = 3, C = 1, D = 0 A would have a 60% chance of being picked, B would have a 30% chance of being picked, C would have a 10% chance of being picked, and D would have a 0% chance of being picked. You should only pass integers in. |
| /proc/pick_weight_recursive | Like pick_weight, but allowing for nested lists. |
| /proc/fill_with_ones | Given a list, return a copy where values without defined weights are given weight 1. For example, fill_with_ones(list(A, B=2, C)) = list(A=1, B=2, C=1) Useful for weighted random choices (loot tables, syllables in languages, etc.) |
| /proc/expand_weights | Takes a weighted list (see above) and expands it into raw entries This eats more memory, but saves time when actually picking from it |
| /proc/greatest_common_factor | Takes a list of numbers as input, returns the highest value that is cleanly divides them all Note: this implementation is expensive as heck for large numbers, I only use it because most of my usecase Is < 10 ints |
| /proc/pick_n_take | Pick a random element from the list and remove it from the list. |
| /proc/pop | Returns the top(last) element from the list and removes it from the list (typical stack function) |
| /proc/peek | Returns the top (last) element from the list, does not remove it from the list. Stack functionality. |
| /proc/next_list_item | Returns the next item in a list |
| /proc/previous_list_item | Returns the previous item in a list |
| /proc/shuffle | Randomize: Return the list in a random order |
| /proc/shuffle_inplace | same as shuffle, but returns nothing and acts on list in place |
| /proc/unique_list | Return a list with no duplicate entries |
| /proc/unique_list_in_place | same as unique_list, but returns nothing and acts on list in place (also handles associated values properly) |
| /proc/sort_key | for sorting clients or mobs by ckey |
| /proc/sort_record | Specifically for record datums in a list. |
| /proc/sort_list | sort any value in a list |
| /proc/sort_names | uses sort_list() but uses the var's name specifically. This should probably be using mergeAtom() instead |
| /proc/bitfield_to_list | Converts a bitfield to a list of numbers (or words if a wordlist is provided) |
| KEYBYINDEX | Returns the key based on the index |
| /proc/count_by_type | return the amount of items of the same type inside a list |
| /proc/find_record | Returns the first record in the list that matches the name |
| /proc/move_element | Move a single element from position from_index within a list, to position to_index All elements in the range [1,to_index) before the move will be before the pivot afterwards All elements in the range [to_index, L.len+1) before the move will be after the pivot afterwards In other words, it's as if the range [from_index,to_index) have been rotated using a <<< operation common to other languages. from_index and to_index must be in the range [1,L.len+1] This will preserve associations ~Carnie |
| /proc/move_range | Move elements [from_index,from_index+len) to [to_index-len, to_index) Same as moveElement but for ranges of elements This will preserve associations ~Carnie |
| /proc/swap_range | Move elements from [from_index, from_index+len) to [to_index, to_index+len) Move any elements being overwritten by the move to the now-empty elements, preserving order Note: if the two ranges overlap, only the destination order will be preserved fully, since some elements will be within both ranges ~Carnie |
| /proc/reverse_range | replaces reverseList ~Carnie |
| /proc/get_element_by_var | return first thing in L which has var/varname == value this is typecaste as list/L, but you could actually feed it an atom instead. completely safe to use |
| /proc/deep_copy_list | Copies a list, and all lists inside it recusively Does not copy any other reference type |
| /proc/avoid_assoc_duplicate_keys | takes an input_key, as text, and the list of keys already used, outputting a replacement key in the format of "[input_key] ([number_of_duplicates])" if it finds a duplicate use this for lists of things that might have the same name, like mobs or objects, that you plan on giving to a player as input |
| /proc/flatten_list | Flattens a keyed list into a list of it's contents |
| /proc/make_associative | Make a normal list an associative one |
| DEFAULTPICK | Picks from the list, with some safeties, and returns the "default" arg if it fails |
| /proc/assoc_to_keys | Turns an associative list into a flat list of keys |
| /proc/assoc_to_keys_features | Turns an associative list into a flat list of keys, but for sprite accessories, respecting the locked variable |
| /proc/assoc_value_sum | Gets the total amount of everything in the associative list. |
| /proc/compare_list | compare two lists, returns TRUE if they are the same |
| /proc/special_list_filter | Returns a list with items filtered from a list that can call callback |
| /proc/recursive_list_resolve | Returns a list with all weakrefs resolved |
| /proc/recursive_list_resolve_element | Helper for recursive_list_resolve() |
| /proc/refify_list | Returns a copy of the list where any element that is a datum or the world is converted into a ref |
| /proc/kvpify_list | Converts a list into a list of assoc lists of the form ("key" = key, "value" = value) so that list keys that are themselves lists can be fully json-encoded |
| /proc/deep_compare_list | Compares 2 lists, returns TRUE if they are the same |
| /proc/weakrefify_list | Returns a copy of the list where any element that is a datum is converted into a weakref |
| /proc/encode_text_and_nulls | Returns a copy of a list where text values (except assoc-keys and string representations of lua-only values) are wrapped in quotes and existing quote marks are escaped, and nulls are replaced with the string "null" |
| /proc/assert_sorted | Runtimes if the passed in list is not sorted |
| /proc/coords2turf | Converts a list of coordinates, or an assosciative list if passed, into a turf by calling locate(x, y, z) based on the values in the list |
Define Details
ASSOC_UNSETEMPTY
If the provided key -> list is empty, remove it from the list
BINARY_INSERT
Binary search sorted insert INPUT: Object to be inserted LIST: List to insert object into TYPECONT: The typepath of the contents of the list COMPARE: The object to compare against, usualy the same as INPUT COMPARISON: The variable on the objects to compare COMPTYPE: How should the values be compared? Either COMPARE_KEY or COMPARE_VALUE.
BINARY_INSERT_DEFINE
Even more custom binary search sorted insert, using defines instead of vars INPUT: Item to be inserted LIST: List to insert INPUT into TYPECONT: A define setting the var to the typepath of the contents of the list COMPARE: The item to compare against, usualy the same as INPUT COMPARISON: A define that takes an item to compare as input, and returns their comparable value COMPTYPE: How should the list be compared? Either COMPARE_KEY or COMPARE_VALUE.
BINARY_INSERT_PROC_COMPARE
Custom binary search sorted insert utilising comparison procs instead of vars. INPUT: Object to be inserted LIST: List to insert object into TYPECONT: The typepath of the contents of the list COMPARE: The object to compare against, usualy the same as INPUT COMPARISON: The plaintext name of a proc on INPUT that takes a single argument to accept a single element from LIST and returns a positive, negative or zero number to perform a comparison. COMPTYPE: How should the values be compared? Either COMPARE_KEY or COMPARE_VALUE.
COMPARE_KEY
Passed into BINARY_INSERT to compare keys
COMPARE_VALUE
Passed into BINARY_INSERT to compare values
DEFAULTPICK
Picks from the list, with some safeties, and returns the "default" arg if it fails
KEYBYINDEX
Returns the key based on the index
LAZYACCESS
returns L[I] if L exists and I is a valid index of L, runtimes if L is not a list
LAZYACCESSASSOC
Accesses an associative list, returns null if nothing is found
LAZYADD
Add an item to the list, if the list is null it will initialize it
LAZYADDASSOC
Adds to the item K the value V, if the list is null it will initialize it
LAZYADDASSOCLIST
This is used to add onto lazy assoc list when the value you're adding is a /list/. This one has extra safety over lazyaddassoc because the value could be null (and thus cant be used to += objects)
LAZYCLEARLIST
Consider LAZYNULL instead
LAZYCOPY
Use LAZYLISTDUPLICATE instead if you want it to null with no entries
LAZYFIND
Returns the key of the submitted item in the list
LAZYINITLIST
Initialize the lazylist
LAZYLEN
Returns the length of the list
LAZYLISTDUPLICATE
Like LAZYCOPY - copies an input list if the list has entries, If it doesn't the assigned list is nulled
LAZYNULL
Sets a list to null
LAZYOR
Add an item to the list if not already present, if the list is null it will initialize it
LAZYORASSOCLIST
Performs an insertion on the given lazy list with the given key and value. If the value already exists, a new one will not be made.
LAZYREMOVE
Remove an item from the list, set the list to null if empty
LAZYREMOVEASSOC
Removes the value V from the item K, if the item K is empty will remove it from the list, if the list is empty will set the list to null
LAZYSET
Sets the item K to the value V, if the list is null it will initialize it
LAZYSETLEN
Sets the length of a lazylist
LISTASSERTLEN
Ensures the length of a list is at least I, prefilling it with V if needed. if V is a proc call, it is repeated for each new index so that list() can just make a new list for each item.
LIST_VALUE_WRAP_LISTS
If value is a list, wrap it in a list so it can be used with list add/remove operations
QDEL_LAZYLIST
Qdel every item in the list before setting the list to null
SANITIZE_LIST
Returns the list if it's actually a valid list, otherwise will initialize it
UNSETEMPTY
If the provided list is empty, set it to null
UNTYPED_LIST_ADD
Add an untyped item to a list, taking care to handle list items by wrapping them in a list to remove the footgun
UNTYPED_LIST_REMOVE
Remove an untyped item to a list, taking care to handle list items by wrapping them in a list to remove the footgun
is_type_in_typecache
Checks for specific types in specifically structured (Assoc "type" = TRUE|FALSE) lists ('typecaches')