String Comparing and Searching

Description:
The COMPARE() function compares two strings and returns a numeric value from 0 (no match) to 100 (an exact match). It uses an enhanced matching algorithm that understands common typographical and keyboarding errors (for example, nearby keys on a QWERTY keyboard or hands on the wrong row), as well as certain spelling and phonetic variations (such as F vs PH).

This makes COMPARE() more "human aware" than a simple edit-distance. General guidelines for interpreting scores:

• 90–100 — Very strong match (usually the same word or name).
• 80–89 — Good match (minor typos or variants).
• 70–79 — Possible match (often needs review).
• Below 70 — Typically a weak match.

Example:

Output: Did you mean DOWN (94 percent)

Description:
CONTAINS() returns TRUE if str_expr1 contains str_expr2, otherwise FALSE. By default the comparison is case-insensitive.

Case sensitivity:
Include an optional third argument (bool_expr). Pass TRUE for a case-sensitive match; omit it or pass FALSE for case-insensitive.

Examples:

Output:
This is a text file

Notes:

• If str_expr2 is longer than str_expr1, CONTAINS() returns FALSE.
• An empty substring returns TRUE (every string contains the empty string).
• Defaulting to case-insensitive helps with filenames and user-entered text.

Description:
ENDSWITH() returns TRUE if str_expr1 ends with str_expr2, otherwise FALSE. By default the comparison is case-insensitive.

Case sensitivity:
Include an optional third argument (bool_expr). Pass TRUE for a case-sensitive match; omit it or pass FALSE for case-insensitive.

Examples:

Output:
This is a text file

Notes:

• If str_expr2 is longer than str_expr1, ENDSWITH() returns FALSE.
• An empty substring returns TRUE (every string ends with the empty string).
• Defaulting to case-insensitive helps with filenames and user-entered text.

Description:
The ITEM() function returns the number of the first item that matches the whole or partial item name given. A negative number is returned if more than one item matches.

Example:
z = item('ADD,EXIT,EXTRACT,MODIFY', 'MOD')
Output: 4
z = item('ADD,EXIT,EXTRACT,MODIFY', 'EX')
Output: -2

Description:
The MATCH() function compares str_expr2 with each of the elements in str_expr1 and returns the number of the element that matches. The TRUE parameter is used if the match is to be case-exact. The default is case-insensitive.

Example:
a$ = 'BLUE'
b$ = 'Blue'
c$ = a$
do
x = match('Red,White,Blue', c$, true)
print c$;
if x > 0 then
print ' is a match.'
else
print ' is not a match.'
c$ = b$
repeat do
end if
end do
Output: Blue is a match.

Description:
The MATCHWORD() function searches str_expr1 for the word or phrase given in str_expr2 and returns the 1-based character position of the first match. The search is case-insensitive ("case-regardless"). Words are made up of letters and/or numbers; non-alphanumeric characters act as separators.

Multiple spaces between words are ignored. If the word or phrase is not found, MATCHWORD() returns 0.
After a successful call, the special variable _integer contains the 1-based word index of the match within str_expr1.

The optional num_expr argument specifies the starting character position for the search within str_expr1. If omitted, the default starting position is 1.

Example:
text$ = 'list of words or 11111 numbers'
print matchword(text$, 'Words')
print _integer
end
Output:
14
3

In this example, MATCHWORD() returns 14, the starting character position of the word "words" in text$. The variable _integer is set to 3, because "words" is the third word in the string.

Description:
The PATTERN() function matches characters in str_expr1 against a pattern specified by str_expr2. It returns the position of the first character in str_expr1 that matches the pattern. If no match is found, it returns zero.

Pattern Options:

• ? - Matches any single character. Example:
  if pattern('The quick brown fox', 'f?x') > 0 then print 'Found' end if
  Output: Found
• * - Matches one or more of the preceding character, or zero or more with double asterisks. Example:
  if pattern('aaa 01/26/99', 'a* *01/26/99') > 0 then print 'The date is found' end if
  Output: The date is found
• {} - Defines a group of characters. Can include ranges (e.g., {a-z}) or individual characters. Example:
  text$ = 'A1N5V7N0' rule_str$ = '{A-Z}{0-9}{A-Z}{0-9}{A-Z}{0-9}{A-Z}{0-9}' if pattern(text$, rule_str$) > 0 then print "Driver's license is correct." end if
  Output: Driver's license is correct
• {^} - Matches characters that are NOT in the specified set. Example:
  print pattern('Mary J. Smith', '{^Mar}') print pattern('Mary J. Smith', 'J. {^S}') print pattern('Mary J. Smith', 'J. S?')
  Output: 4 0 6
• ~ - Matches a character pattern that stands for itself. Example:
  text$ = '$4,670.00' if pattern(text$, '$~4,670.00') > 0 then print 'Your text is correct.' end if
  Output: Your text is correct
• {|nnn,nnn,nnn|} - Matches binary data. Useful for detecting non-printable text characters. Example:
  text$ = 'Help yourself to some ' + chr$(13) + 'food' if pattern(text$, '{|13|}') > 0 then print 'Carriage return found.' end if
  Output: Carriage return found
• {} - Matches text in str_expr1 against enclosed groups. Example:
  text$ = 'The area code is 619' if pattern(text$, 'is {<619|714|916>}') > 0 then print 'Your area code is on the list.' end if
  Output: Your area code is on the list
• {(word_text)} - Matches a word or phrase. Example:
  a$ = 'There are dogs and cats in the house.' b$ = 'Everyone would like to make big$bucks!' if pattern(a$, '{(cats)}') > 0 then print 'The word was found.' end if if pattern(b$, '{(big$bucks)}') > 0 then print 'The $ word was found.' end if
  Output: The word was found. The $ word was found.
• {|directive|} - Directives can be used to modify the search behavior (e.g., case-insensitive, beginning or end of a line). Example:
  a$ = 'ElEpHaNtS have trunks' b$ = 'water goes splash' if pattern(a$, '{|bol|}{|nocase|}elephants') > 0 then print 'elephants was found.' end if if pattern(b$, 'splash{|eol|}') > 0 then print 'splash was found.' end if
  Output: elephants was found. splash was found.

Description:

The POS() function searches for a substring within a string and returns the position of the first character of the substring. If the substring is not found, the function returns zero.

Example:
If int_expr is provided and is positive, the search starts at the int_expr position from the left. If int_expr is negative, the search is performed from right to left, beginning at the -int_expr position.

Description:
For a detailed description, see: Regular Expression Text Search

Arguments:
text_str (required): The text to operate on.

Example:
print regexsearch('The rain in Spain', 'rain')
Output: 5

Description:
The SCAN() function scans str_expr1 for the characters in str_expr2 and returns the position at which str_expr2 begins. The characters in str_expr2 need not appear contiguously in str_expr1.

Example:
a$ = 'Cameron Whitehorn'
b$ = 'amr Wtor'
position = scan(a$, b$)
Output: 2

Description:
The SKIP() function returns the position of the character following the last skipped character.

Example:
a$ = '31415 hello'
z = skip(a$, '1234567890 ')
print mid(a$, z)
Output: hello

Description:
The STARTSWITH() function tests whether one string begins with another. It returns TRUE if the starting characters match, or FALSE if not.

By default, the comparison is not case-sensitive. To perform a case-sensitive comparison, include an optional third argument and set it to TRUE.

Examples:

Output:
Starts with 'report'

Notes:

• If str_expr2 is longer than str_expr1, STARTSWITH() returns FALSE.
• Empty substrings always return TRUE (every string begins with an empty string).
• String comparison is case-insensitive by default for convenience when working with file names and user input.