INSTR.md 10 KB

INSTR function

Purpose: INSTR searches through a string to locate a substring. If the substring is found, the function returns an integer indicating the position of the beginning of the substring. The search begins by default from the beginning of the string to be searched or, optionally, from a specified start postion.


 Syntax:

 Position% = INSTR(MainStr$, Match$ [,Start%] [,CaseSensitivity%])

 Parameters:

  • Position% Returned position where Match$ is located in MainStr$. 0 is returned if Match$ is not found. 0 is also returned if MainStr$ or Match$ string is zero length.
  • MainStr$ String which is to be searched for Match$.
  • Match$ Substring to be located in MainStr$.
  • Start% [OPTIONAL] Position in MainStr$ where to begin search. Default is position zero.
  • CaseSensitivity% [OPTIONAL] Set to 1 for case insensitive search. Default is 0 which is case sensitive.

Example 1 :


 Position% = INSTR("12345abc67890", "abc")

Result:

Position% will equal 6

Example 2 :


 DIM Position%
 Position% = INSTR("12345abc67890", "AbC", 5, 1)
 PRINT Position%

Result:

Position% will equal 6

BCX Console Sample Programs using INSTR function.

S14.bas   S39.bas   S84.bas   S87.bas  

INSTRREV function

Purpose: INSTRREV searches backwards through a string to locate a substring. If the substring is found, the function returns an integer indicating the position of the beginning of the substring. The search begins by default from the end of the string to be searched or, optionally, from a specified start position.


 Syntax:

 Position% = INSTRREV(MainStr$, Match$ [,Start%] [,CaseSensitivity%])

 Parameters:

  • Position% Returned position where Match$ is located in MainStr$. 0 is returned if Match$ is not found. 0 is also returned if MainStr$ or Match$ string is zero length. The return value, Position%, is measured from the beginning of the string.
  • MainStr$ String which is to be searched for Match$.
  • Match$ Substring to be located in MainStr$.
  • Start% [OPTIONAL] Position in MainStr$ where to begin search. Default is the string length of MainStr$. When a Start% position is specified, text to the right of the Start% position will not be considered in the search.
  • CaseSensitivity% [OPTIONAL] Set to 1 for case insensitive search. Default is 0 which is case sensitive.

Example:


 Position% = INSTRREV("12345abc67890", "abc")

Result:

Position% will equal 6

The example below demonstrates INSTRREV.


 DIM int1%
 DIM str1$, str2$
  
 PRINT ""
 PRINT "Example 1 demonstrates two parameter INSTRREV"
 PRINT "looks for last backslash "
 str1$ = "I:\like\this\one\better\bob.exe"
 PRINT str1$
 str2$ = MID$(str1$, 1, INSTRREV(str1$, "\"))
 PRINT str2$
 PRINT ""
  
 PRINT "Example 2 demonstrates three parameter INSTRREV"
 str1$ = "12345678XXX23456XXX0"
 PRINT ""
 PRINT "Start looking backwards from position 12 for XXX"
 PRINT "in string 12345678XXX23456XXX0"
 int1% = INSTRREV(str1$, "XXX", 12)
 PRINT int1%; " result should be 9"
 PRINT ""
  
 PRINT "Start looking backwards from position 20 for XXX"
 PRINT "in string 12345678XXX23456XXX0"
 int1% = INSTRREV(str1$, "XXX", 20)
 PRINT int1%; " result should be 17"
 PRINT ""
 '             XXX changed to XYY.
 str1$ = "12345678XYY23456XXX0"
 PRINT ""
 PRINT "Start looking backwards from position 12 for XXX"
 PRINT "in string 12345678XYY23456XXX0"
 int1% = INSTRREV(str1$, "XXX", 12)
 PRINT int1; " result should be 0"

INCHR function

Purpose: INCHR returns the position where the single character Matchar$ is located in MainStr$. INCHR is approximately four times faster than INSTR.


 Syntax:

 Position% = INCHR(MainStr$,Matchar$)

 Parameters:

  • Position% Returned position where Match$ is located in MainStr$.
  • MainStr$ String which is to be searched for Matchar$ character.
  • Matchar$ Character to be located in MainStr$. Matchar$ must be a single character.

CONTAINEDIN function


 Syntax:
 
 RetVal% = CONTAINEDIN(Match$, MainArray [,Comparison%])

 Parameters:

  • RetVal% by default returns 0 if found -1 if not found. See table below in Comparison% parameter description for other return values.
  • Match$ String to be located in MainArray.
  • MainArray Array of strings where the last string must be set to "". The example below shows how to SET the array.
  • Comparison% [OPTIONAL] method of comparison used during search. The default method is 0 which is case sensitive. The following table describes the options for the Comparison argument and the expected value returned in RetVal%

     
     0 - case sensitive   returns 0 if found -1 if not found
     1 - case insensitive returns 0 if found -1 if not found
     2 - case sensitive   returns i if found -1 if not found
     3 - case insensitive returns i if found -1 if not found
    

    When the Comparison% argument is either 2 or 3 and the string to be located is found then the return value of i will represent the number of the MainArray element in which the string was located.

Example:


 SET CN[] AS CHAR PTR
   "&",
   ",",
   ":",
   "+",
   "-",
   "*",
   "/",
   "^",
   ";",
   "=",
   "<",
   ">",
   "THEN",
   ""
 END SET
  
 DIM c1, c2
 DIM i
 DIM x
 DIM y
 DIM Stk$[128]
 DIM Ndx
 DIM A$
  
 A$ = "if x = 1 then y = y + 1 : if y > 10 THEN y = 0"
 PRINT A$
 CALL TinyParse(A$, " ")
  
 c1 = 0
 c2 = 0
 FOR i = 0 TO Ndx
   x = CONTAINEDIN(Stk$[i], CN, 1)
   IF x <> -1 THEN
     PRINT "Token "; i; " in A$ "; Stk$[i]; " ";
     y = CONTAINEDIN(Stk$[i], CN)
     IF y <> -1 THEN
       PRINT " exact match"
       c2++
     ELSE
       PRINT " match with case difference"
     END IF
     c1++
   END IF
 NEXT
 PRINT "A total of"; c1; " tokens, regardless of case, in CN[] where found in A$,"; c2; " were exact matches"
 getchar()
 c1 = 0
 c2 = 0
 FOR i = 0 TO Ndx
   x = CONTAINEDIN(Stk$[i], CN, 3)
   IF x <> -1 THEN
     PRINT "the"; i; "th token in A$ "; Stk$[i]; " ";
     y = CONTAINEDIN(Stk$[i], CN, 2)
     IF y <> -1 THEN
       PRINT " exact match of the"; y; "th token in CN[] "; CN$[y]
       c2++
     ELSE
       PRINT " match with case difference of the"; x; "th token in CN[] "; CN$[x]
     END IF
     c1++
   END IF
 NEXT
  
 getchar()
  
 SUB TinyParse(A$, Delim$)
   DIM RAW TB$
   DIM RAW Sep
   DIM STATIC ii
   Ndx = 0
   TB$ = ""
   Sep = INCHR(A$, Delim$)
   IF Sep > 0 THEN
     IF Sep > 1 THEN
       TB$ = LEFT$(A$, Sep - 1)
       Stk$[ii] = TB$
       ii++
     END IF
     A$ = MID$(A$, Sep + 1)
     TinyParse(A$, Delim$)
   ELSE
     Stk$[ii] = A$
     Stk$[ii+1] = ""
     Ndx = ii
     ii = 0
   END IF
 END SUB

FINDINTYPE function

Purpose: FINDINTYPE is modeled after the CONTAINEDIN function. The main differences between CONTAINEDIN and FINDINTYPE are:

  • Instead of a string array you supply a type array
  • A range of records can be specified to search
  • An optional index array can be given to return the position of the string found in relation to the index.

 Syntax:

 RetVal% = FINDINTYPE(Match$, _
                 Type.element, _
                   RangeFrom%, _
                     RangeTo%  _
               [, Comparison%] _
                    [, Index%])

 Parameters:

  • RetVal% by default returns 0 if found -1 if not found. See table below in Comparison% parameter description for other return values.
  • Match$ String to be located in Type.element of array.
  • Type.element Type array element to be searched.
  • RangeFrom% Beginning of range of records to be searched.
  • RangeTo% End of range of records to be searched.
  • Comparison% [OPTIONAL] method of comparison used during search. The default method is 0 which is case sensitive. The following table describes the options for the Comparison argument and the expected value returned in RetVal%

    
     0 - case sensitive   returns 0 if found -1 if not found
     1 - case insensitive returns 0 if found -1 if not found
     2 - case sensitive   returns i if found -1 if not found
     3 - case insensitive returns i if found -1 if not found
    

    When the Comparison% argument is either 2 or 3 and the string to be located is found then the return value of i will represent the number of the Type array element in which the string was located.

  • Index%> [OPTIONAL] An index array can be given to return the string position found in relation to the index.