libArrays
Functions to support array processing
Overview
Functions to help with arrays.
Contains the following:
ksl::arrayExists()
ksl::arraySize()
ksl::arrayHasKey()
ksl::arrayGetValue()
ksl::arraySetValue()
ksl::arrayDeleteElement()
ksl::arrayAppendValue()
ksl::arrayPrependValue()
ksl::arrayVisit()
Index
ksl::arrayExists
Returns true if the array exists.
Example
if ksl::arrayExists myArray; then echo "have it"; fi
Arguments
$1 (array): the name of the array
Exit codes
1: not an array or missing args
0: it is an array that exists
Output on stdout
no output
Output on stderr
arrayExists() missing args
ksl::arraySize
Returns the size of the array.
This is the number of elements it contains.
Example
echo "There are $(ksl::arraySize myArray) elements"
Arguments
$1 (array): the name of the array
Exit codes
1: not an array or missing args
0: success
Output on stdout
the size of the array
Output on stderr
arraySize() missing args:
arraySize() no such array:
ksl::arrayHasKey
Returns true if the array has an element with the given key
Example
if ksl::arrayHasKey acronyms CRC; then echo "have it"; fi
Arguments
$1 (array): the name of the array
$2 (string): the name of the key
Exit codes
1: not an array or missing args
0: success
Output on stdout
no output
Output on stderr
arrayHasKey() missing args
arrayHasKey() no such array:
ksl::arraySetValue
Set a value in an array.
The element is created if it does not exist. If the element already exists, then its previous value is overwritten.
Example
ksl::arraySetValue acronyms CRC "Cyclic Redundancy Check"
Arguments
$1 (array): the name of the array
$2 (string): the name of the key
$3 (string): the value to set for this element
Exit codes
1: not an array or missing args
0: success
Output on stdout
no output
Output on stderr
arraySetValue() missing args
arraySetValue() no such array:
ksl::arrayGetValue
Get a value from an array.
Example
val=$(ksl::arrayGetValue acronyms CRC)
Arguments
$1 (array): the name of the array
$2 (string): the name of the key
Exit codes
1: not an array, no such key, or missing args
0: success
Output on stdout
the value
Output on stderr
arrayGetValue() missing args
arrayGetValue() no such array:
arrayGetValue() no such key:
ksl::arrayAppendValue
Append to a value in an array.
The element must already exist, otherwise it’s an error.
Example
ksl::arrayAppend errpass DESC " on channel 12"
Arguments
$1 (array): the name of the array
$2 (string): the name of the key
$3 (string): the value to append for this element
Exit codes
1: not an array, no such key, or missing args
0: success
Output on stdout
no output
Output on stderr
arrayAppendValue() missing args
arrayAppendValue() no such array:
arrayAppendValue() no such key:
ksl::arrayPrependValue
Prepend to a value in an array.
The element must already exist, otherwise it’s an error.
Example
ksl::arrayPrepend errpass DESC "Fatal error: "
Arguments
$1 (array): the name of the array
$2 (string): the name of the key
$3 (string): the value to prepend for this element
Exit codes
1: not an array, no such key, or missing args
0: success
Output on stdout
no output
Output on stderr
arrayPrependValue() missing args
arrayPrependValue() no such array:
arrayPrependValue() no such key:
ksl::arrayDeleteElement
Deletes an array element.
It is not an error if the element doesn’t exist.
Example
ksl::arrayDeleteElement dogs SHEPPARD
Arguments
$1 (array): - the name of the array
$2 (string): - the name of the key
Exit codes
1: not an array, no such key, or missing args
0: success
Output on stdout
no output
Output on stderr
arrayDeleteElement() missing args
arrayDeleteElement() no such array:
ksl::arrayVisit
Visits each element in an array and invokes your function on it.
Your function is called with three args, plus any additional args you provide:
<value> - $1 the value from the array
<key|index> - $2 the array’s key or index where this value is found
<array name> - $3 the array name
[additonal args…] - user provided args, if any
If your function returns 10 or 11, then visit() will stop visiting remaining elements. Typically use 10 to exit early with success, and 11 to exit early with an error. But you can apply any meaning to these two values as they both exit early for whatever reason.
Returns
0 - success if all elements have been visited
1 - fail missing or bad args
10 - success if your function stopped visiting with a 10
11 - error if your function stopped visiting with an 11
Example
ksl::arrayVisit dogs findValue "Roving rover"
ret=$?
[[ $ret -eq 0 ]] && echo "Not found"
[[ $ret -eq 10 ]] && echo "Found it"
[[ $ret -eq 11 ]] && echo "Error from findValue()"
#
# Your function
findValue()
{
# $1 = element value
# $2 = element key|index
# $3 = array name
# $4 = "Roving rover"
[[ "$1" == "$4" ]] && return 10
}
Arguments
$1 (array): the name of array (required)
$2 (function): the function to call on each element (required)
$3 ([args…]): additional arguments (optional) to pass into your function
Exit codes
0: success - all elements visited
1: fail - not an array or missing args
10: success if your function stopped visiting with a 10
11: error if your function stopped visiting with an 11
Output on stdout
no output
Output on stderr
arrayVisit() missing args
arrayVisit() no such array: