FINDW Function

Returns the character position of a word in a string, or returns the number of the word in a string.

Category: Character

Syntax

FINDW(string, word <, chars> )
FINDW(string, word, chars, modifiers <, startpos> )
FINDW(string, word, chars, startpos <, modifiers> )
FINDW(string, word, startpos <, chars <, modifiers> > )

Required Arguments

string

is a character constant, variable, or expression that specifies the character string to be searched.

word

is a character constant, variable, or expression that specifies the word to be searched.

chars

is an optional character constant, variable, or expression that initializes a list of characters.

The characters in this list are the delimiters that separate words, provided that you do not specify the K modifier in the modifier argument. If you specify the K modifier, then all characters that are not in this list are delimiters. You can add more characters to this list by using other modifiers.

startpos

is an optional numeric constant, variable, or expression with an integer value that specifies the position at which the search should begin and the direction in which to search.

modifier

specifies a character constant, variable, or expression in which each non-blank character modifies the action of the FINDW function.

Tip
If you use the modifier argument, then it must be positioned after the chars argument.
You can use the following characters as modifiers:

blank

is ignored.

a

A

adds alphabetic characters to the list of characters.

b

B

scans from right to left instead of from left to right, regardless of the sign of the startpos argument.

c

C

adds control characters to the list of characters.

d

D

adds digits to the list of characters.

e

E

counts the words that are scanned until the specified word is found, instead of determining the character position of the specified word in the string. Fragments of a word are not counted.

f

F

adds an underscore and English letters (that is, the characters that can begin a SAS variable name using VALIDVARNAME=V7) to the list of characters.

g

G

adds graphic characters to the list of characters.

h

H

adds a horizontal tab to the list of characters.

I

I

ignores the case of the characters.

k

K

causes all characters that are not in the list of characters to be treated as delimiters. If K is not specified, then all characters that are in the list of characters are treated as delimiters.

l

L

adds lowercase letters to the list of characters.

m

M

specifies that multiple consecutive delimiters, and delimiters at the beginning or end of the string argument, refer to words that have a length of zero.

n

N

adds digits, an underscore, and English letters (that is, the characters that can appear after the first character in a SAS variable name using VALIDVARNAME=V7) to the list of characters.

o

O

processes the chars and modifier arguments only once, rather than every time the FINDW function is called. Using the O modifier in the DATA step (excluding WHERE clauses), or in the SQL procedure, can make FINDW run faster when you call it in a loop where the chars and modifier arguments do not change.

p

P

adds punctuation marks to the list of characters.

q

Q

ignores delimiters that are inside of substrings that are enclosed in quotation marks. If the value of the string argument contains unmatched quotation marks, then scanning from left to right will produce different words than scanning from right to left.

r

R

removes leading and trailing delimiters from the word argument.

s

S

adds space characters (blank, horizontal tab, vertical tab, carriage return, line feed, and form feed) to the list of characters.

t

T

trims trailing blanks from the string, word, and chars arguments.

u

U

adds uppercase letters to the list of characters.

w

W

adds printable characters to the list of characters.

x

X

adds hexadecimal characters to the list of characters.

Details

Definition of “Delimiter”

“Delimiter” refers to any of several characters that are used to separate words. You can specify the delimiters by using the chars argument, the modifier argument, or both. If you specify the Q modifier, then the characters inside of substrings that are enclosed in quotation marks are not treated as delimiters.

Definition of “Word”

“Word” refers to a substring that has both of the following characteristics:
  • bounded on the left by a delimiter or the beginning of the string
  • bounded on the right by a delimiter or the end of the string
Note: A word can contain delimiters. In this case, the FINDW function differs from the SCAN function, in which words are defined as not containing delimiters.

Searching for a String

If the FINDW function fails to find a substring that both matches the specified word and satisfies the definition of a word, then FINDW returns a value of 0.
If the FINDW function finds a substring that both matches the specified word and satisfies the definition of a word, the value that is returned by FINDW depends on whether the E modifier is specified:
  • If you specify the E modifier, then FINDW returns the number of complete words that were scanned while searching for the specified word. If startpos specifies a position in the middle of a word, then that word is not counted.
  • If you do not specify the E modifier, then FINDW returns the character position of the substring that is found.
If you specify the startpos argument, then the absolute value of startpos specifies the position at which to begin the search. The sign of startpos specifies the direction in which to search:
Value of startpos
Action
greater than 0
search begins at position startpos and proceeds to the right. If startpos is greater than the length of the string, then FINDW returns a value of 0.
less than 0
search begins at position –startpos and proceeds to the left. If startpos is less than the negative of the length of the string, then the search begins at the end of the string.
equal to 0
FINDW returns a value of 0.
If you do not specify the startpos argument or the B modifier, then FINDW searches from left to right starting at the beginning of the string. If you specify the B modifier, but do not use the startpos argument, then FINDW searches from right to left starting at the end of the string.

Using the FINDW Function in ASCII and EBCDIC Environments

If you use the FINDW function with only two arguments, the default delimiters depend on whether your computer uses ASCII or EBCDIC characters.
  • If your computer uses ASCII characters, then the default delimiters are as follows:
    blank ! $ % & ( ) * + , - . / ; < ^ |
    In ASCII environments that do not contain the ^ character, the FINDW function uses the ~ character instead.
  • If your computer uses EBCDIC characters, then the default delimiters are as follows:
    blank ! $ % & ( ) * + , - . / ; < ¬ | ¢

Using Null Arguments

The FINDW function allows character arguments to be null. Null arguments are treated as character strings with a length of zero. Numeric arguments cannot be null.

Examples

Example 1: Searching a Character String for a Word

The following example searches a character string for the word “she”, and returns the position of the beginning of the word.
data _null_;    
   whereisshe=findw('She sells sea shells? Yes, she does.','she');    
   put whereisshe=; 
run;
SAS writes the following output to the log:
whereisshe=28

Example 2: Searching a Character String and Using the Chars and Startpos Arguments

The following example contains two occurrences of the word “rain.” Only the second occurrence is found by FINDW because the search begins in position 25. The chars argument specifies a space as the delimiter.
data _null_;
   result = findw('At least 2.5 meters of rain falls in a rain forest.', 
                   'rain', ' ', 25);
   put result=;
run;
SAS writes the following output to the log:
result=40

Example 3: Searching a Character String and Using the I Modifier and the Startpos Argument

The following example uses the I modifier and returns the position of the beginning of the word. The I modifier disregards case, and the startpos argument identifies the starting position from which to search. 
data _null_;
   string='Artists from around the country display their art at 
           an art festival.';
   result=findw(string, 'Art',' ', 'i', 10);
   put result=;
run;
SAS writes the following output to the log: 
result=47

Example 4: Searching a Character String and Using the E Modifier

The following example uses the E modifier and returns the number of complete words that are scanned while searching for the word “art.”
data _null_;
   string='Artists from around the country display their art at 
           an art festival.';
   result=findw(string,'art',' ','E');
   put result=;
run;
SAS writes the following output to the log: 
result=8

Example 5: Searching a Character String and Using the E Modifier and the Startpos Argument

The following example uses the E modifier to count words in a character string. The word count begins at position 50 in the string. The result is 3 because “art” is the third word after the 50th character position.
data _null_;
   string='Artists from around the country display their art at 
           an art festival.';
   result=findw(string, 'art',' ','E',50);
   put result=;
run;
SAS writes the following output to the log: 
result=3

Example 6: Searching a Character String and Using Two Modifiers

The following example uses the I and the E modifiers to find a word in a string. 
data _null_;
   string='The Great Himalayan National Park was created in 1984. Because
           of its terrain and altitude, the park supports a diversity 
           of wildlife and vegetation.';
   result=findw(string,'park',' ','I E');
   put result=;
run;
SAS writes the following output to the log: 
result=5

Example 7: Searching a Character String and Using the R Modifier

The following example uses the R modifier to remove leading and trailing delimiters from a word. 
data _null_; 
    string='Artists from around the country display their art at 
               an art festival.'; 
    word='  art  ';
    result=findw(string, word, ' ', 'R'); 
    put result=; 
run;
SAS writes the following output to the log:
result=47

See Also

Functions:
COUNTW Function
FIND Function
FINDC Function
INDEXW Function
SCAN Function
CALL Routines:
CALL SCAN Routine
Copyright © SAS Institute Inc. All rights reserved.