INSTR: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
(Created page with "The INSTR function searches for the first occurence of a search STRING within a base string and returns the position it was found. {{PageSyntax}} : {{Parameter|position%}} = INSTR([{{Parameter|start%}},] {{Parameter|baseString$}}, {{Parameter|searchString$}}) {{Parameters}} * The optional literal or variable INTEGER {{Parameter|start%}} indicates where in the {{Parameter|baseString$}} the search must start. * The {{Parameter|baseString$}} is a litera...")
 
m (Add _INSTRREV in "see also")
 
(4 intermediate revisions by one other user not shown)
Line 6: Line 6:




{{Parameters}}
{{PageParameters}}
* The optional literal or variable [[INTEGER]] {{Parameter|start%}} indicates where in the {{Parameter|baseString$}} the search must start.  
* The optional literal or variable [[INTEGER]] {{Parameter|start%}} indicates where in the {{Parameter|baseString$}} the search must start.
* The {{Parameter|baseString$}} is a literal or variable [[STRING]] value to be searched for an exact match including [[UCASE$|letter cases]].  
* The {{Parameter|baseString$}} is a literal or variable [[STRING]] value to be searched for an exact match including [[UCASE$|letter cases]].
* The {{Parameter|searchString$}} is a literal or variable [[STRING]] value being searched.
* The {{Parameter|searchString$}} is a literal or variable [[STRING]] value being searched.


Line 14: Line 14:
{{PageDescription}}
{{PageDescription}}
* The function returns the {{Parameter|position%}} in the {{Parameter|baseString$}} where the {{Parameter|searchString$}} was found.
* The function returns the {{Parameter|position%}} in the {{Parameter|baseString$}} where the {{Parameter|searchString$}} was found.
* {{Parameter|position%}} will be 0 if the search found no matches in the base string.  
* {{Parameter|position%}} will be 0 if the search found no matches in the base string.
* [[INSTR]] returns 0 if an empty {{Parameter|baseString$}} is passed, and returns 1 with an empty {{Parameter|searchString$}}.
* [[INSTR]] returns 0 if an empty {{Parameter|baseString$}} is passed, and returns 1 with an empty {{Parameter|searchString$}}.
* The {{Parameter|start%}} position is useful when making multiple searches in the same string. See the example below.
* The {{Parameter|start%}} position is useful when making multiple searches in the same string. See the example below.
* The {{Parameter|searchString$}} should be smaller or equal in [[LEN|length]] to the {{Parameter|baseString$}}, or 0 is returned.
* The {{Parameter|searchString$}} should be smaller or equal in [[LEN|length]] to the {{Parameter|baseString$}}, or 0 is returned.
* Non-zero {{Parameter|position%}} return values can be used as a new start position by adding 1 to re-search the base string. See the example below.
* Non-zero {{Parameter|position%}} return values can be used as a new start position by adding 1 to re-search the base string. See the example below.
* In a loop, INSTR can search an entire file for occurences of certain words. See the [[MID$ (statement)|MID$]] statement example.
* In a loop, INSTR can search an entire file for occurences of certain words. See the [[MID$]] statement example.


 
=== QBasic/QuickBASIC ===
==QBasic/QuickBASIC==
* The {{Parameter|start%}} position had to be at least 1 or greater when used or there will be an [[ERROR Codes|Illegal function call]] error. In '''QB64''', a {{Parameter|start%}} value of 0 or negative is interpreted as 1 and doesn't generate an error.
* The {{Parameter|start%}} position had to be at least 1 or greater when used or there will be an [[ERROR Codes|Illegal function call]] error. In '''QB64''', a {{Parameter|start%}} value of 0 or negative is interpreted as 1 and doesn't generate an error.


Line 28: Line 27:
{{PageExamples}}
{{PageExamples}}
''Example:'' Reading more than one instance of a word in a string using the INSTR return value as the start value plus 1.
''Example:'' Reading more than one instance of a word in a string using the INSTR return value as the start value plus 1.
{{CodeStart}} '' ''
{{CodeStart}}
text$ = "The cats and dogs where playing, even though dogs don't like cats."
text$ = "The cats and dogs where playing, even though dogs don't like cats."
{{Cl|DO...LOOP|DO}}
{{Cl|DO...LOOP|DO}}
Line 36: Line 35:


findmonkey% = {{Cl|INSTR}}(text$, "monkeys")  ' find any occurance?
findmonkey% = {{Cl|INSTR}}(text$, "monkeys")  ' find any occurance?
PRINT findmonkey%; "'monkeys' were found so it returned:"; findmonkey% '' ''
PRINT findmonkey%; "'monkeys' were found so it returned:"; findmonkey%
{{CodeEnd}}
{{CodeEnd}}
{{OutputStart}}There is 'cats' in the string at position: 5
{{OutputStart}}There is 'cats' in the string at position: 5
Line 46: Line 45:


{{PageSeeAlso}}
{{PageSeeAlso}}
* [[MID$]], [[MID$ (statement)]]
* [[_INSTRREV]], [[MID$ (function)]]
* [[LEFT$]], [[RIGHT$]]
* [[LEFT$]], [[RIGHT$]]
* [[LCASE$]], [[UCASE$]]
* [[LCASE$]], [[UCASE$]]

Latest revision as of 07:06, 1 May 2023

The INSTR function searches for the first occurence of a search STRING within a base string and returns the position it was found.


Syntax

position% = INSTR([start%,] baseString$, searchString$)


Parameters

  • The optional literal or variable INTEGER start% indicates where in the baseString$ the search must start.
  • The baseString$ is a literal or variable STRING value to be searched for an exact match including letter cases.
  • The searchString$ is a literal or variable STRING value being searched.


Description

  • The function returns the position% in the baseString$ where the searchString$ was found.
  • position% will be 0 if the search found no matches in the base string.
  • INSTR returns 0 if an empty baseString$ is passed, and returns 1 with an empty searchString$.
  • The start% position is useful when making multiple searches in the same string. See the example below.
  • The searchString$ should be smaller or equal in length to the baseString$, or 0 is returned.
  • Non-zero position% return values can be used as a new start position by adding 1 to re-search the base string. See the example below.
  • In a loop, INSTR can search an entire file for occurences of certain words. See the MID$ statement example.

QBasic/QuickBASIC

  • The start% position had to be at least 1 or greater when used or there will be an Illegal function call error. In QB64, a start% value of 0 or negative is interpreted as 1 and doesn't generate an error.


Examples

Example: Reading more than one instance of a word in a string using the INSTR return value as the start value plus 1. 

text$ = "The cats and dogs where playing, even though dogs don't like cats."
DO
  findcats% = INSTR(findcats% + 1, text$, "cats") ' find another occurance after
  IF findcats% THEN PRINT "There is 'cats' in the string at position:"; findcats%
LOOP UNTIL findcats% = 0

findmonkey% = INSTR(text$, "monkeys")  ' find any occurance?
PRINT findmonkey%; "'monkeys' were found so it returned:"; findmonkey%

There is 'cats' in the string at position: 5
There is 'cats' in the string at position: 62
 0 'monkeys' were found so INSTR returned: 0
Explanation: When the INSTR return value is 0 there are no more instances of a string in a string so the search loop is exited.


See also


Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=INSTR&oldid=8386"