# Sheerpower® A Guide to the Sheerpower Language

 Previous Contents Index

# 6.5 String Searching and Comparing Functions

The following are string searching and comparing functions that Sheerpower performs:

## 6.5.1 COMPARE(str_expr1, str_expr2)

The COMPARE function compares two strings and returns a numeric value ranging from 0 (no match) to 100 (an exact match).

Example 6-121 COMPARE Function
 ``` options\$ = 'LEFT,RIGHT,UP,DOWN' best = 0 best\$ = '' input 'Enter an option': usr_opt\$ for idx = 1 to elements(options\$) opt\$ = element\$(options\$, idx) score = compare(opt\$, usr_opt\$) if score > best then best = score best\$ = opt\$ end if next idx select case best case 0 print 'Unknown option: '; usr_opt\$ case 100 print 'Option okay, it was: '; usr_opt\$ case else print 'Misspelled option: '; usr_opt\$ print using 'Did you mean ? (## percent)': best\$, best end select end Enter an option? dwn Misspelled option: dwn Did you mean DOWN (92 percent) ```

## 6.5.2 ITEM(str_expr1, str_expr2)

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.

Quoted data is treated as one element; the quotes are not removed.

Example 6-122 ITEM Function
 ``` z = item('ADD,EXIT,EXTRACT,MODIFY', 'MOD') print z end 4 ```

Example 6-123 ITEM Function
 ``` z = item('ADD,EXIT,EXTRACT,MODIFY', 'EX') print z end -2 ```

## 6.5.3 MATCH(str_expr1, str_expr2 [, TRUE])

str_expr1 contains a list of elements separated by commas. str_expr2 contains a string. MATCH compares str_expr2 with each of the elements in str_expr1 and gives 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 6-124 MATCH Function
 ``` 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 end BLUE is not a match. Blue is a match. ```

## 6.5.4 PATTERN(str_expr1, str_expr2)

This function matches any characters in text (str_expr1) with the pattern (str_expr2). str_expr1 is the text to search and str_expr2 is the pattern being searched for. It returns the location of the first character in the text that contains the pattern. If the characters cannot be found, it returns zero.

PATTERN Options and Examples

Pattern options can be mixed and matched with unlimited complexity.

## ?

The "?" matches any character in the text.

Example 6-125 PATTERN Function - ?
 ``` if pattern('The quick brown fox', & 'f?x') > 0 then print 'Found' end if end Found ```

## *

The "*" matches one or more of a character that precedes the single asterisk (*).
It matches zero or more of a character that precedes the double asterisk (**).

Example 6-126 PATTERN Function -*
 ``` if pattern('aaa 01/26/99', 'a* *01/26/99') > 0 then print 'The date is found' end if end The date is found ```

## {}

The {} is used to define a group of characters. The characters in the enclosed group can be ranges such as {a-z} or individual characters such as {AQX}.

Example 6-127 PATTERN Function - { }
 ``` 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 end Driver's license is correct ```

## {^}

The {^} looks for characters that are NOT {^A-Z}. The result below shows the difference between using '?' and {^}.

Example 6-128 PATTERN Function - {^ }
 ``` print pattern('Mary J. Smith','{^Mar}') print pattern('Mary J. Smith','J. {^S}') print pattern('Mary J. Smith','J. S?') end 4 0 6 ```

## ~

The '~' (quote) character looks for a pattern of text that IS an * (stands for itself).

Example 6-129 PATTERN Function - ~
 ``` text\$ = '\$4,670.00' if pattern(text\$, '\$~4,670.00') > 0 then print 'Your text is correct.' end if end Your text is correct. ```

## {|nnn,nnn,nnn|}

This feature lets you designate binary data for detecting patterns that are not printable text characters. The characters in the enclosed group can be individual byte values such as {|13|} or groups such as {|0,13,200|}. Since {A-Z} is the range of A through Z, the proper syntax for this same range using byte values would be {{|65|}-{|90|}}.

Example 6-130 PATTERN Function - { |nnn,nnn,nnn | }
 ``` text\$ = 'Help yourself to some ' + chr\$(13) + 'food' if pattern(text\$, '{|13|}') > 0 then print 'Carriage return found.' end if end Carriage return found. ```

## {<cc|ccc|c>}

The {<cc|ccc|c>} looks for text in str_expr1 that matches the enclosed groups.

Example 6-131 PATTERN Function - { <cc |ccc |c > }
 ``` 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 end Your area code is on the list. ```

## {(word_text)}

(word_text) looks for a match on a word. The word text can contain an embedded "\$".

Example 6-132 PATTERN Function - {(word_text) }
 ``` 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 end The word was found. The \$ word was found. ```

## {|directive|}

Directives can be used with the PATTERN function. Multiple directives can be used. Directives are processed from left to right. The valid directives are:

 nocase can be uppercase, lowercase or a combination of the two case unless NOCASE specified, default is CASE (i.e. case-exact) bol beginning of a line eol end of a line

Example 6-133 PATTERN Function - { |directive | }
 ``` 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 end elephants was found. splash was found. ```

## 6.5.5 POS(str_expr1, str_expr2[, int_expr])

POS searches for a substring within a string. It returns the substring's starting character position. str_expr1 is the string to be searched, str_expr2 is the substring to locate, and int_expr is the OPTIONAL character position at which to begin the search. The default character position is the start of the string. If the substring is not found, zero is returned.

Example 6-134 POS Function
 ``` text\$ = "Hello and goodbye" andpos = pos(text\$, 'and') if andpos > 0 then print 'AND found at position'; andpos end AND found at position 7 ```

POS can also scan for a substring starting from the last character of the string. This is done by entering a negative int_expr.

Example 6-135 POS Function
 ``` print pos('Hello and goodbye', 'o') //scan from the front print pos('Hello and goodbye', 'o',-1) // scan from the back end 5 13 ```

 Previous Next Contents Index