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 <#kslarrayexists>`__
- `ksl::arraySize <#kslarraysize>`__
- `ksl::arrayHasKey <#kslarrayhaskey>`__
- `ksl::arraySetValue <#kslarraysetvalue>`__
- `ksl::arrayGetValue <#kslarraygetvalue>`__
- `ksl::arrayAppendValue <#kslarrayappendvalue>`__
- `ksl::arrayPrependValue <#kslarrayprependvalue>`__
- `ksl::arrayDeleteElement <#kslarraydeleteelement>`__
- `ksl::arrayVisit <#kslarrayvisit>`__

ksl::arrayExists
~~~~~~~~~~~~~~~~

Returns true if the array exists.

Example
^^^^^^^

.. code:: bash

   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

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image1|

ksl::arraySize
~~~~~~~~~~~~~~

Returns the size of the array.

This is the number of elements it contains.

.. _example-1:

Example
^^^^^^^

.. code:: bash

   echo "There are $(ksl::arraySize myArray) elements"

.. _arguments-1:

Arguments
^^^^^^^^^

- **$1** (array): the name of the array

.. _exit-codes-1:

Exit codes
^^^^^^^^^^

- **1**: not an array or missing args
- **0**: success

.. _output-on-stdout-1:

Output on stdout
^^^^^^^^^^^^^^^^

- the size of the array

.. _output-on-stderr-1:

Output on stderr
^^^^^^^^^^^^^^^^

- arraySize() missing args:
- arraySize() no such array:

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image2|

ksl::arrayHasKey
~~~~~~~~~~~~~~~~

Returns true if the array has an element with the given key

.. _example-2:

Example
^^^^^^^

.. code:: bash

   if ksl::arrayHasKey acronyms CRC; then echo "have it"; fi

.. _arguments-2:

Arguments
^^^^^^^^^

- **$1** (array): the name of the array
- **$2** (string): the name of the key

.. _exit-codes-2:

Exit codes
^^^^^^^^^^

- **1**: not an array or missing args
- **0**: success

.. _output-on-stdout-2:

Output on stdout
^^^^^^^^^^^^^^^^

- no output

.. _output-on-stderr-2:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayHasKey() missing args
- arrayHasKey() no such array:

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image3|

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-3:

Example
^^^^^^^

.. code:: bash

   ksl::arraySetValue acronyms CRC "Cyclic Redundancy Check"

.. _arguments-3:

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-3:

Exit codes
^^^^^^^^^^

- **1**: not an array or missing args
- **0**: success

.. _output-on-stdout-3:

Output on stdout
^^^^^^^^^^^^^^^^

- no output

.. _output-on-stderr-3:

Output on stderr
^^^^^^^^^^^^^^^^

- arraySetValue() missing args
- arraySetValue() no such array:

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image4|

ksl::arrayGetValue
~~~~~~~~~~~~~~~~~~

Get a value from an array.

.. _example-4:

Example
^^^^^^^

.. code:: bash

   val=$(ksl::arrayGetValue acronyms CRC)

.. _arguments-4:

Arguments
^^^^^^^^^

- **$1** (array): the name of the array
- **$2** (string): the name of the key

.. _exit-codes-4:

Exit codes
^^^^^^^^^^

- **1**: not an array, no such key, or missing args
- **0**: success

.. _output-on-stdout-4:

Output on stdout
^^^^^^^^^^^^^^^^

- the value

.. _output-on-stderr-4:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() missing args
- arrayGetValue() no such array:
- arrayGetValue() no such key:

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image5|

ksl::arrayAppendValue
~~~~~~~~~~~~~~~~~~~~~

Append to a value in an array.

The element must already exist, otherwise it’s an error.

.. _example-5:

Example
^^^^^^^

.. code:: bash

   ksl::arrayAppend errpass DESC " on channel 12"

.. _arguments-5:

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-5:

Exit codes
^^^^^^^^^^

- **1**: not an array, no such key, or missing args
- **0**: success

.. _output-on-stdout-5:

Output on stdout
^^^^^^^^^^^^^^^^

- no output

.. _output-on-stderr-5:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayAppendValue() missing args
- arrayAppendValue() no such array:
- arrayAppendValue() no such key:

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image6|

ksl::arrayPrependValue
~~~~~~~~~~~~~~~~~~~~~~

Prepend to a value in an array.

The element must already exist, otherwise it’s an error.

.. _example-6:

Example
^^^^^^^

.. code:: bash

   ksl::arrayPrepend errpass DESC "Fatal error: "

.. _arguments-6:

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-6:

Exit codes
^^^^^^^^^^

- **1**: not an array, no such key, or missing args
- **0**: success

.. _output-on-stdout-6:

Output on stdout
^^^^^^^^^^^^^^^^

- no output

.. _output-on-stderr-6:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayPrependValue() missing args
- arrayPrependValue() no such array:
- arrayPrependValue() no such key:

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image7|

ksl::arrayDeleteElement
~~~~~~~~~~~~~~~~~~~~~~~

Deletes an array element.

It is not an error if the element doesn’t exist.

.. _example-7:

Example
^^^^^^^

.. code:: bash

   ksl::arrayDeleteElement dogs SHEPPARD

.. _arguments-7:

Arguments
^^^^^^^^^

- **$1** (array): - the name of the array
- **$2** (string): - the name of the key

.. _exit-codes-7:

Exit codes
^^^^^^^^^^

- **1**: not an array, no such key, or missing args
- **0**: success

.. _output-on-stdout-7:

Output on stdout
^^^^^^^^^^^^^^^^

- no output

.. _output-on-stderr-7:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayDeleteElement() missing args
- arrayDeleteElement() no such array:

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image8|

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-8:

Example
^^^^^^^

.. code:: bash

   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-8:

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-8:

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-8:

Output on stdout
^^^^^^^^^^^^^^^^

- no output

.. _output-on-stderr-8:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayVisit() missing args
- arrayVisit() no such array:

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image9|

.. |image1| image:: ../images/pub/divider-line.png
.. |image2| image:: ../images/pub/divider-line.png
.. |image3| image:: ../images/pub/divider-line.png
.. |image4| image:: ../images/pub/divider-line.png
.. |image5| image:: ../images/pub/divider-line.png
.. |image6| image:: ../images/pub/divider-line.png
.. |image7| image:: ../images/pub/divider-line.png
.. |image8| image:: ../images/pub/divider-line.png
.. |image9| image:: ../images/pub/divider-line.png