mirror of
https://github.com/QB64Official/qb64.git
synced 2024-09-01 18:40:17 +00:00
54 lines
No EOL
2.9 KiB
Text
54 lines
No EOL
2.9 KiB
Text
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 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.
|
|
|
|
|
|
{{PageDescription}}
|
|
* 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.
|
|
* [[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|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.
|
|
* In a loop, INSTR can search an entire file for occurences of certain words. See the [[MID$ (statement)|MID$]] statement example.
|
|
|
|
|
|
==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.
|
|
|
|
|
|
{{PageExamples}}
|
|
''Example:'' Reading more than one instance of a word in a string using the INSTR return value as the start value plus 1.
|
|
{{CodeStart}} '' ''
|
|
text$ = "The cats and dogs where playing, even though dogs don't like cats."
|
|
{{Cl|DO...LOOP|DO}}
|
|
findcats% = {{Cl|INSTR}}(findcats% + 1, text$, "cats") ' find another occurance after
|
|
{{Cl|IF...THEN|IF}} findcats% {{Cl|THEN}} {{Cl|PRINT}} "There is 'cats' in the string at position:"; findcats%
|
|
{{Cl|LOOP}} {{Cl|UNTIL}} findcats% = 0
|
|
|
|
findmonkey% = {{Cl|INSTR}}(text$, "monkeys") ' find any occurance?
|
|
PRINT findmonkey%; "'monkeys' were found so it returned:"; findmonkey% '' ''
|
|
{{CodeEnd}}
|
|
{{OutputStart}}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
|
|
{{OutputEnd}}
|
|
: ''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.
|
|
|
|
|
|
{{PageSeeAlso}}
|
|
* [[MID$]], [[MID$ (statement)]]
|
|
* [[LEFT$]], [[RIGHT$]]
|
|
* [[LCASE$]], [[UCASE$]]
|
|
* [[STRING]], [[INTEGER]]
|
|
|
|
|
|
{{PageNavigation}} |