EQWatcher Evolution > Scripting  > Arrays (EQWatcher Evolution 2.12+)


EQWatcher arrays are not a built-in type, but rather use integer "handles", similar to those that the SQL functionality uses.  Each array function will use this handle to determine which array you are accessing.  Arrays are global-scope, so the handle is valid for every script.  Using an invalid handle will not break anything (in fact, it will auto-create an array with that handle if necessary).

To create an array using an unused handle, use the NewArray function.  Some functions will create the array passed as a parameter if it does not already exist, using the given handle if possible (this means if the array is deleted, and then later re-used, it is automatically re-created with the same handle.  If the handle passed is 0, a new handle is created and used, this is the recommended method if you choose not to use NewArray).  These functions are: ArrayReset, ArrayAddElement, ArrayInsertElement, ArrayAppend.   

There are many functions available for accessing and manipulating these arrays.  The first element of these arrays is number 1.

List of functions


ArrayAddElement, ArrayAppend, ArrayCount, ArrayDelete, ArrayElement, ArrayFindElement, ArrayInsertElement, ArrayRemoveElement, ArrayReset, ArraySetElement, FromDynarray, NewArray, ToDynarray



The "ArrayAddElement" Function

This function adds an element to the end of an array, creating the array if necessary.

Syntax:

ArrayAddElement([handle],[data])


handle: An integer variable representing the array handle (MUST be a variable because of auto-creation, this variable will be modified if necessary with the new handle)

data: A string containing the element data to add to the array


Return Value:

none


The "ArrayAppend" Function

This function copies all of one array onto the end of another (the first will store the entire merged contents, the second remains untouched and still valid)

Syntax:

ArrayAppend([main],[secondary])


main: An integer variable representing the array handle of the array to add to (MUST be a variable because of auto-creation, this variable will be modified if necessary with the new handle)

secondary: An integer variable representing the array handle of the array to add from.  The secondary array is not auto-created and does not need to exist (the main array will still be auto-created).


Return Value:

none


The "ArrayCount" Function

This function retrieves the number of elements in an array

Syntax:

ArrayCount([handle])


handle: An integer variable representing the array handle (does not auto-create, will return 0 for invalid handles)


Return Value:

0 if failed, otherwise the integer count of elements in the array.


The "ArrayDelete" Function

This function deletes an array, making the handle eligible for reuse

Syntax:

ArrayDelete([handle])


handle: An integer variable representing the array handle (does not auto-create just to delete)


Return Value:

none


The "ArrayElement" Function

This function retrieves a specified element from an array

Syntax:

ArrayElement([handle],[number])


handle: An integer variable representing the array handle (does not auto-create, will return "" for invalid handles)

number: The number of the element to retrieve


Return Value:

A string containing the data from the element number of the array specified.  Will return an empty string for invalid arrays or out-of-bounds.


The "ArrayFindElement" Function

This function finds the number of the first element with specific data (case insensitive, complete string search) in an array, starting from a specific position (inclusive).

Syntax:

ArrayFindElement([handle],[start],[data])


handle: An integer variable representing the array handle (does not auto-create, will return 0 for invalid handles)

start: The element number to begin the search at

data: The string data to find within this array.  The element must match exactly, except not case sensitive.


Return Value:

0 for failure (which includes out of bounds, invalid handle, etc) or the number of the element equal to the data


The "ArrayInsertElement" Function

This function inserts a new element at a specified position of an array.  The array is auto-created if necessary, and the array is padded to this length if not already that large.  The data becomes the element at this position, all others are pushed toward the end of the array.

Syntax:

ArrayInsertElement([handle],[data],[position])


handle: An integer variable representing the array handle (MUST be a variable because of auto-creation)

data: The string data to insert into the array

position: The element number for this data to become


Return Value:

none


The "ArrayRemoveElement" Function

This function removes a specified element from an array, pushing all elements after it toward the first element.

Syntax:

ArrayRemoveElement([handle],[number])


handle: An integer variable representing the array handle (does not auto-create, will return "" for invalid handles)

number: The number of the element to remove


Return Value:

none


The "ArrayReset" Function

This function resets an array to its empty state, creating if necessary.

Syntax:

ArrayReset([handle])


handle: An integer variable representing the array handle (MUST be a variable because of auto-creation)


Return Value:

none


The "ArraySetElement" Function

This function sets an element in an array to new data

Syntax:

ArraySetElement([handle],[position],[data])


handle: An integer variable representing the array handle (does not auto-create, operation will fail for invalid handles)

position: The element number for this data to become

data: The string data to replace the old element


Return Value:

none


The "FromDynarray" Function

This function sets an array's contents equal to a dynarray, creating the array if necessary.

Syntax:

FromDynarray([handle],[dynarray])


handle: An integer variable representing the array handle of the array to set (MUST be a variable because of auto-creation, this variable will be modified if necessary with the new handle)

dynarray: A dynarray-formatted string to convert


Return Value:

none


The "NewArray" Function

This function creates and initializes a new array, returning the handle.

Syntax:

NewArray()

Return Value:

An integer representing the newly created array's handle


The "ToDynarray" Function

This function creates a dynarray-formatted string equal to the contents of the array

Syntax:

ToDynarray([handle])


handle: An integer variable representing the array handle of the array  (does not auto-create, will return "0;" for invalid handles)


Return Value:

A dynarray-formatted string equivalent to this array, or "0;" for invalid handles