Synopsis: 

       result=array_search(array_name,search_order,value)

Arguments:

       array_name - The array name as previouslydefined by a call to array_dim()

       search_order - Search order (-1 for bottom up, -3 for search next)

       value - The value to search for in the array

Description:   This function allows for a one-dimensional array to be searched for a particular value.       Note that only one-dimensional arrays are supported by this function.      The search order defines how the array is to be searched and can be set to one of the following values:

       -1 -  Search for the first entry from the bottom up that matches the value

       -2 - Top down search (NOT CURRENTLY SUPPORTED)

       -3 - Search for then next match starting from the last match found

       -4 - search for the previous value (NOT CURRENTLY SUPPORTED)

       

If -1 is specified then the search will always begin at element 0 of  the index of the array and then cycle through the last index of the array until the end of the array is reached looking for a match for the specified value.    

IF -2 is specified then the last position where a match was found will be remembered and the next time the function is call the search will continue from that position and then wrap around to the beginning again.

The function will return the index number of the element that matches the value specified by the value argument.  otherwise it will return -1

For example:

       // Create a one dimensional array

       x=array_dim("RESOURCE",100,1);

            // Set some elements of the array to 1.

       array_set("RESOURCE",10,"1");

       array_set("RESOURCE",20,"1");

       array_set("RESOURCE",30,"1");

   

       // Search the RESOURCE array for the first element set to 1

       // This will return 10

       index=array_search("RESOURCE",-1,"1");

       // This will return 10 since as well since we specified -1 for the search order which always searches from 0 upwards

       index=array_search("RESOURCE",-1,"1");

       // This will return 20 since we are now specifying to search for the next entry that matches after the last match (ie. search order -3)

       index=array_search("RESOURCE",-3,"1");

       // This will return 30 since we are now specifying to search for the next entry that matches after the last match (ie. search order -3)

       index=array_search("RESOURCE",-3,"1");

Returns:     Returns the index where a match was found or -1 is no match was found