Array Header (UseFunc Example) Readme
=====================================

This header is an example of usage of an advanced header with
UseFunc. This header is totally different from the Afrow UK's
header for his plugin. This header manipulates arrays, as
being NSIS strings separated by a separator string.

1. How to use the Array header
------------------------------

  1.1 For Users
  -------------

    1.1.1 Using the header functions
    --------------------------------

      1.1.1.1 Use ${ArrayDef} "myArrayName"
      -------------------------------------

        First, to start using the header in your scripts,
        you should define your array variables, which can
        be done by using ${ArrayDef} outside sections and
        functions. Example:

          ${ArrayDef} "myFirstArray"
          ${ArrayDef} "mySecondArray"
          ...

        This macro creates 2 variables which you can use
        for whatever you want:

          $a_myArrayName
          $a_myArrayName_sep

        The first variable is used for storing every
        array item separated by a separator. The second
        defines the separator used by all the array
        functions.

      1.1.1.2 Put ${Array} in the start of a section or function
      ----------------------------------------------------------

        To use all the features of the Math plug-in + the Array
        header, you must do this. This function defines every
        function required by the other functions of the header.

      1.1.1.3 Fill the $a_*_sep variable with a separator
      ---------------------------------------------------

        You must fill the $a_myArrayName_sep with something.
        All functions use 2 internal functions to convert
        string to array and back.

        (Bug: Function should support the blank: it has to treat
              every character as an array item in this case.)

      1.1.1.4 Using the header functions
      ----------------------------------

        All the header functions have the first parameter "Name":

          This parameter specifies the array to be used,
          along with its separator.

        All functions that have an output parameter have the
        parameter "ResultVar" after the "Name" parameter:

          This parameter outputs the function return value.
          This has to be a variable or a run-time error will
          occur.

        All functions that have an output parameter can output
        the string "error" which means that an error happened
        in the function.

        The variable $a_*_sep will never be used as output by
        functions, but $a_* will.

        1.1.1.4.1 ${ArrayCrop} "Name" "StartIndex" "EndIndex"
        -----------------------------------------------------

          Crops an amount of items at the starting index of
          an array.

          StartIndex

            The starting index from where the items will
            start to be deleted. Default is 0.

          EndIndex

            The ending index of the deletion, excluding
            the item with this index.

          Example:
            $a_myArray = ABC|DEF|GHI
            $a_myArray_sep = |

            ${ArrayCrop} myArray 1 3

            $a_myArray = ABC
          
        1.1.1.4.2 ${ArrayExpand} "Name" "Name2"
        ---------------------------------------

          Expands the array with items from another array.
          The new items will be added to the end of the
          array "Name".

          Name2

            Another array name.

          Example:
            $a_myArray = ABC|DEF|GHI
            $a_myArray_sep = |
            $a_myArray2 = JKL,MNO,PQR
            $a_myArray2_sep = ,

            ${ArrayExpand} myArray 1 3

            $a_myArray = ABC|DEF|GHI|JKL|MNO|PQR

        1.1.1.4.3 ${ArrayRange} "Name" "StartNumber" "StopNumber"
        ---------------------------------------------------------

          Creates an array with a range of numbers. Until
          the stop number is reached, every item will contain
          previous item + 1.

          StartNumber

            The number which will be the first item in the array.

          EndNumber

            The number which the loop ends. This number is not
            the last number in the array. It is the previous
            number.

          Example:
            $a_myArray = ABC|DEF|GHI ;contents will be overwritten
            $a_myArray_sep = |

            ${ArrayRange} myArray 1 10

            $a_myArray = 1|2|3|4|5|6|7|8|9

        1.1.1.4.4 ${ArrayReverse} "Name"
        --------------------------------

          Reverses the order of items in the array.

          Example:
            $a_myArray = ABC|DEF|GHI
            $a_myArray_sep = |

            ${ArrayReverse} myArray

            $a_myArray = GHI|DEF|ABC

        1.1.1.4.5 ${ArraySort} "Name"
        -----------------------------

          Sorts the items in alphabetical order. It uses the
          string algorithm called "Bubble Sort".

          Example:
            $a_myArray = test|ad|task|step|abc|a
            $a_myArray_sep = |

            ${ArrayReverse} myArray

            $a_myArray = a|abc|ad|step|task|test

        1.1.1.4.6 ${ArrayUpdate} "Name" "Name2"
        ---------------------------------------

          Verifies if there are new items in the second array and
          adds them to the first array.

          Name2

            Another array name.

          Example:
            $a_myArray = ABC|DEF|GHI
            $a_myArray_sep = |
            $a_myArray2 = ABC|GHI|JKL
            $a_myArray2_sep = |

            ${ArrayUpdate} myArray myArray2

            $a_myArray = ABC|DEF|GHI|JKL

        1.1.1.4.7 ${ArrayItemAppend} "Name" "String"
        --------------------------------------------

          Appends an item to the end of the array.

          String

            String to be appended to the end of the array.

          Example:
            $a_myArray = ABC|DEF|GHI
            $a_myArray_sep = |

            ${ArrayItemAppend} myArray STU

            $a_myArray = ABC|DEF|GHI|STU

          Error values:

            Same as ${ArrayItemInsert}.

        1.1.1.4.8 ${ArrayItemCount} "Name" "ResultVar" "String"
        -------------------------------------------------------

          Counts how many items there are in the array, or if specifying
          a the string, how many items there are with the string.

          String

            String to be used for counting how many items there are.
            If empty, the function counts all items that are in the array.
            Default is to count all items.

          Example:
            $a_myArray = ABC|DEF|GHI|DEF|PQR|DEF|JKL|STU
            $a_myArray_sep = |

            ${ArrayItemCount} myArray $0 DEF
            $0 = 2

            ${ArrayItemCount} myArray $0 ""
            $0 = 8

        1.1.1.4.9 ${ArrayItemGet} "Name" "ResultVar" "Index"
        ----------------------------------------------------

          Gets the string of one item by using the item index.

          Index

            Item index used to retrieve the item's string.

          Example:
            $a_myArray = ABC|DEF|GHI
            $a_myArray_sep = |

            ${ArrayItemGet} myArray $0 1
            $0 = DEF

        1.1.1.4.10 ${ArrayItemIndex} "Name" "ResultVar" "String" "Reference"
        --------------------------------------------------------------------

          Retrieves the index of an item with the string specified.

          String

            String to be used to retrieve the item's index.

          Reference

            Represents which item the function should return. 1 means the
            next, 2 means the second item with the string... This can also be
            negative for the search to start from the end. Default is 1.

          Example:
            $a_myArray = ABC|DEF|GHI|DEF|PQR|DEF|JKL|STU
            $a_myArray_sep = |

            ${ArrayItemIndex} myArray $0 "DEF" "2"
            $0 = 5

          Error values:

            ValueError

              Happens when the string is empty and an the item could not be found.

            IndexError

              Happens when the string is not found.

        1.1.1.4.11 ${ArrayItemInsert} "Name" "Index" "String"
        -----------------------------------------------------

          Inserts an item anywhere in the array.

          Index

            Index where to insert the item.

          String

            String used by the item.

          Example:
            $a_myArray = ABC|DEF|JKL
            $a_myArray_sep = |

            ${ArrayItemInsert} myArray "GHI" "2"
            $a_myArray = ABC|DEF|GHI|JKL

          Error values:

            ValueError

              Happens when the item cannot be inserted. (probably never)

        1.1.1.4.12 ${ArrayItemMove} "Name" "Index" "Index2"
        ---------------------------------------------------

          Moves an item from the array to another location in the array.

          Index

            Source index of the item.

          Index2

            Destination index for the item.

          Example:
            $a_myArray = ABC|DEF|JKL
            $a_myArray_sep = |

            ${ArrayItemMove} myArray "GHI" "2"
            $a_myArray = ABC|DEF|GHI|JKL

          Error values:

            IndexError

              Happens when the first index is past the array.

        1.1.1.4.13 ${ArrayItemPush} "Name" "String"
        ---------------------------------------------

          Pushes an item to the start of the array.

          String

            String to be pushed to the array.

          Example:
            $a_myArray = DEF|GHI
            $a_myArray_sep = |

            ${ArrayItemPush} myArray ABC

            $a_myArray = ABC|DEF|GHI

          Error values:

            Same as ${ArrayItemInsert}.

        1.1.1.4.14 ${ArrayItemPop} "Name" "ResultVar"
        ---------------------------------------------

          Removes the first item of the array.

          Example:
            $a_myArray = ABC|DEF|JKL
            $a_myArray_sep = |

            ${ArrayItemPop} myArray $0
            $a_myArray = DEF|JKL
            $0 = ABC

          Error values:

            Same as ${ArrayItemRemove}.

        1.1.1.4.15 ${ArrayItemRemove} "Name" "ResultVar" "Index"
        --------------------------------------------------------

          Removes an item from the array.

          Index

            Index of the item to remove.

          Example:
            $a_myArray = ABC|DEF|JKL
            $a_myArray_sep = |

            ${ArrayItemRemove} myArray $0 "1"
            $a_myArray = ABC|JKL
            $0 = DEF

          Error values:

            IndexError

              Happens when the index is past the array.

        1.1.1.4.16 ${ArrayItemSet} "Name" "ResultVar" "Index" "String"
        --------------------------------------------------------------

          Sets and item with a new string and returns the previous
          item string.

          Index

            Index of the item to set.

          String

            New string to be used as the item's name.

          Example:
            $a_myArray = ABC|DEF|JKL
            $a_myArray_sep = |

            ${ArrayItemSet} myArray $0 "1" "GHI"
            $a_myArray = ABC|DEF|GHI
            $0 = JKL

        1.1.1.4.17 ${ArrayItemSwap} "Name" "Index" "Index2"
        --------------------------------------------------------------

          Swaps two items in the array

          Index

            First item index to swap.

          Index

            Second item index to swap.

          Example:
            $a_myArray = ABC|DEF|JKL
            $a_myArray_sep = |

            ${ArrayItemSwap} myArray $0 "0" "2"
            $a_myArray = JKL|DEF|ABC

          Error values:

            ValueError

              Happens when there was an error when inserting or
              removing items from the array.

      1.1.1.5 Unload Math plugin
      --------------------------

        If you don't need to use this heder anymore at the end of
        your script, you should unload Math plugin before quitting
        the program, or the $PLUGINSDIR folder will continue to
        exist after you closed the program.

    1.2.1 Using Array functions or header special features
    ------------------------------------------------------

      1.2.1.1 Internal Error handling
      -------------------------------

        Array functions have internal error handling. If you
        need to know the error of the last command, you can use
        the variable $Array_LastOpError variable and verify for:

        "IndexError": Error with index out of bounds.
        "ValueError": Error with wrong parameter values.

        If you need to find the last error that happened, use
        $UseFunc_LastError variable. There is no detection of which
        line had the problem though...

      1.2.1.2 Usage of functions using Math plug-in
      ---------------------------------------------

        This header uses functions from the Math plug-in internally.
        If you want to use one of them directly, without using this
        header, you can grab some function names inside the Array
        main function (same as the header name). You are still
        required to include this main function first, except if you
        define the functions yourself, which is not recommended if
        you want mixed use of the header.

      1.2.1.3 Arrays can be used directly anywhere
      --------------------------------------------

        Arrays created by this header can be used anywhere.
        StrCpy's, plug-ins, part of other arrays... There is no
        need for functions to extract the contents of the array.
        Also, this is useful for InstallOptions, because it uses
        this type of array when using controls that support
        multiple items. Just use stick the $a_* variable.

        For InstallOptions support, you need to change the
        separator to "|" and call a dummie array function
        for the convertion to take place.

        (FR: There should be a function to convert separator
             characters inside arrays)

2. Versions History
-------------------

1.0 - 10/Aug/2005

- First version.

3. Credits
----------

  - Array header for UseFunc created by deguix.
  - Math plug-in and internal functions StrLoc and
    Sort_Bubble created by brainsucker.

4. License
----------

  This header file is provided 'as-is', without any express or implied
  warranty. In no event will the author be held liable for any damages
  arising from the use of this header file.

  Permission is granted to anyone to use this header file for any purpose,
  including commercial applications, and to alter it and redistribute
  it freely, subject to the following restrictions:

  1. The origin of this header file must not be misrepresented;
     you must not claim that you wrote the original header file.
     If you use this header file in a product, an acknowledgment in the
     product documentation would be appreciated but is not required.
  2. Altered versions must be plainly marked as such,
     and must not be misrepresented as being the original header file.
  3. This notice may not be removed or altered from any distribution.