SRCH
====

Function
--------

**SRCH** function enables an array to be searched for the occurrence of
a specified element within that array.

Syntax
~~~~~~

SRCH(array element,numerical expression)

The array element specified is used as the reference to be searched for
in the remaining array.

Examples
--------

::

   PRINT SRCH(A$)
   A=SRCH(A(5),3)
   IF SRCH(A!(0), 1)<>5 THEN OPCHR7

Remarks
-------

Consider the following program.

::

   10 DIM A$(10,20)
   20 A$(0)="ABCDE"
   30 A$(1)="AB"
   40 A$(2)="ABCDE"
   50 A$(3)="ABCDE"
   60 A$(4)="ZXYZ"
   70 A$(5)="ABCDE"
   100 INPUT X,Y
   110 PRINT SRCH(A$(X),Y)
   120 GOT0100

When found the element number is returned. If not found then zero is
returned.

The function searches from the specified element to the end of the
array. As an option, up to 255 occurrences can be checked for by
specifying in the argument the number of repeat occurrences.

If this value is 256 or larger a syntax error will occur.

The result of SRCH is a numeric value which can be used in arithmetic
expressions etc.

The search function can also be used on simple or double precision
arrays.

The following are the results of search on the above array:

::

   SRCH(A$)

gives 2 ; as element (2) is the first occurrence of element (0).

::

   SRCH(A$(2), 1)

gives 3 : as element 3 is the first occurrence of element (2).

::

   SRCH(A$(4))

gives 0 : as element (4) is not found elsewhere.

when search is applied to numeric arrays the comparison must be exact
for equality.

For string arrays the rules apply as if in the :doc:`if` statement,
i.e. the comparison is equal if the reference string is equal to or a
subset of, the searched string.

Example:

::

   PRINT SRCH(A$(1))

would return 2 as A$(1) is a subset of A$(2).