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
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 

Example 6-123 ITEM Function

  z = item('ADD,EXIT,EXTRACT,MODIFY', 'EX') 
  print z 

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$ 
    x = match('Red,White,Blue', c$, true) 
    print c$; 
    if  x > 0  then
      print ' is a match.' 
      print ' is not a match.' 
      c$ = b$ 
      repeat do
    end if
  end do
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


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 
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
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?') 


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 
Your text is correct. 


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
Carriage return found. 


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 
Your area code is on the list. 


(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 
The word was found. 
The $ word was found. 


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
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 
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 

Previous Next Contents Index