# lib_array function library

Dependencies: lib_2da, lib_anon, lib_fn, lib_ini, lib_sfo, lib_sugar, lib_tools, lib_ui

## Description

Functions to manipulate WEIDU arrays. Functions in this library should be pure (no side effects) except insofar as they're explicitly writing array data into a file. They shouldn't interact with IE resources at all. Most functions here assume a simple (i.e. not multidimensional) array.

## Public functions

array_2d_to_list(sort:b=1, array:a, separator:s=" ", require_value:s)=(list:a) dimorphic

Take a 2d array (k1,k2)->v. Return a 1d array with the k1 as keys and a list of the k2 as values. Optionally, require that v=require_value. If sort=1, sort entries lexicographically.

array_contains(array:a, key:s, val:s)=(value:s) dimorphic

Depending on which of 'key' and 'val' are set, return true if (i) array 'array' contains 'key' as a key; (ii) array 'array' contains 'val' as a value; (iii) array 'array' contains the pair 'key'=>'val', or I suppose (iv) array 'array' is non-empty.

This is intentionally case-sensitive (since a common use-case is going to be pulling an array element out by its key if it's in the array).

array_copy(array:a)=(array:a) dimorphic

Copy an array.

array_echo(single_line:i, array:a)=() dimorphic

Print an array to the screen (good for debugging). If single_line=1, returns a single string with comma-separated entries; otherwise returns one k=>v per line.

array_fill(array:a, fill:s="*")=(array:a) dimorphic

Given an array of keys, set each to the value 'fill'.

array_from_string(string:s)=(array:a) dimorphic

Take a string of k=>v pairs separated by spaces. Read them into an array.

array_invert(array:a)=(array:a) dimorphic

Input an array of k->v; output an array of v->k.

array_join(array1:a, array2:a)=(array:a) dimorphic

Take two arrays and combine them, so that key k is in the new array iff it is in one or other of the old arrays. If there's a clash of key allocations, array2 gets priority.

array_keys(silent:i, array:a)=(is_empty:s, keys1:a, keys2:a, keys3:a, keys4:a, keys5:a) dimorphic

Given an array, return arrays k=>_ of the first five levels of its keys.

WEIDU limitations mean that if the array is empty, the return value is unpredictable and may equal an already-defined array. Empty arrays lead to a WARNing, which you can suppress with silent=1. In applications where the array might be empty, make sure you explicitly CLEAR_ARRAY it before calling array_keys.

array_keys_from_string(separator:s=" ", string:s)=(array:a) dimorphic

Take a string of strings separated by 'separator' (a character). Read them in as the keys of an array. (Values are blank.)

array_length(array:a)=(value:s, length:s) dimorphic

Returns the number of elements in the array. ('value' and 'length' are synonyms.)

array_map(array:a, map:f, keymap:f)=(array:a) dimorphic

Take a k->v array is input; return keymap(k)->map(v). (Either function can be absent, in which case it's treated as the identity.) You can use the anonymous function construct.

array_read(firstrow:i, backwards:b, case:[u=mixedpper|lower|mixed])=(array:a) patch
array_read(firstrow:i, silent:i, backwards:b, inline:b, file:s, path:s, location:s, locbase:s, case:[u=mixedpper|lower|mixed])=(value:s, array:a) action

Take a file (or, for the patch version, the current file), which should be a table, (not necessarily a 2da) and read in the first two columns into a k->v array. (If there's only one column, read it into a k->_ array.)

Start at row firstrow.

In action context, return value=1 if the file exists, value=0 if it doesn't, and whine if it doesn't unless silent=1.

If backwards=1, swap the order of key and value.

array_sort(depth:i=1, array:a, function:f)=(array:a) dimorphic

Given a patch function (of argument->value type) with domain the keys of an array, sort that array alphabetically by the values of the function. The function doesn't have to be 1:1. You can use the anonymous function construct.

array_split(array:a, match_key:f, match_value:f)=(split:a, rest:a) dimorphic

Take a k->v array as input, along with functions 'match_key' and/or 'match_value'; return an array 'split' of all elements with keys that match 'kmatch' and values that match 'vmatch', and an array 'match' of all that don't. You can use the anonymous function construct.

array_values_from_string(quick:i, string:s, separator:s=" ")=(array_length:s, array:a) dimorphic

Given a string of strings separated by 'separator' (a character), return an [int]=>v array of those strings, labelled by sequential integers. If 'quick' is set, assume no entries are quoted. 'quick' only works for a ' ' or tab separator.

array_write(new:b, permanent:b, path:s="weidu_external/data/MOD_FOLDER", file:s, array:a)=() dimorphic

Output an array as a 2-column table. If 'new' is set, overwrite any existing file by the same name; if not, append. If 'permanent' is set, the table will persist even if the component is uninstalled. (This automatically sets 'new'.)