DOCUMENTATION
Sign In

Get access to My SAS, trials, communities and more.

 

FINDW Function

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

Categories:Character
CAS
Restriction:This function is assigned an I18N Level 1 status and is designed for SBCS data. However, if the first argument, string, has multi-byte characters, then the FINDW function processes the DBCS data. For more information, see Internationalization Compatibility.
Table of Contents
Syntax
Required Arguments
Details
Definition of “Delimiter”
Definition of “Word”
Searching for a String
Using the FINDW Function in ASCII and EBCDIC Environments
Using Null Arguments
Processing SBCS and DBCS Data
Examples
Example 1: Searching a Character String for a Word
Example 2: Searching a Character String and Using the Character and Start-position Arguments
Example 3: Searching a Character String and Using the I Modifier and the Start-position Argument
Example 4: Searching a Character String and Using the E Modifier
Example 5: Searching a Character String and Using the E Modifier and the Start-position Argument
Example 6: Searching a Character String and Using Two Modifiers
Example 7: Searching a Character String and Using the R Modifier
See Also

Syntax

FINDW(string, word <, character(s)>)
FINDW(string, word, character(s), modifier(s) <, start-position>)
FINDW(string, word, character(s), start-position <, modifier(s)>)
FINDW(string, word, start-position <, character(s) <, modifier(s)>>)

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 search for in string.

character

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.

start-position

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 character argument.
You can use the following characters as modifiers:

blank

is ignored.

a or A

adds alphabetic characters to the list of characters.

b or B

scans from right to left instead of from left to right, regardless of the sign of the start-position argument.

c or C

adds control characters to the list of characters.

d or D

adds digits to the list of characters.

e or 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 or 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 or G

adds graphic characters to the list of characters.

h or H

adds a horizontal tab to the list of characters.

i or I

ignores the case of the characters.

k or 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 or L

adds lowercase letters to the list of characters.

m or 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 or 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 or O

processes the character 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 character and modifier arguments do not change.

p or P

adds punctuation marks to the list of characters.

q or Q

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

r or R

removes leading and trailing delimiters from the word argument.

s or S

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

t or T

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

u or U

adds uppercase letters to the list of characters.

w or W

adds printable characters to the list of characters.

x or X

adds hexadecimal characters to the list of characters.

Details

Definition of “Delimiter”
Definition of “Word”
Searching for a String
Using the FINDW Function in ASCII and EBCDIC Environments
Using Null Arguments
Processing SBCS and DBCS Data

Definition of “Delimiter”

Delimiter refers to any of several characters that are used to separate words. You can specify the delimiters by using the character argument, the modifier argument, or both. If you specify the Q modifier, then the characters inside 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 start-position 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 start-position argument, then the absolute value of start-position specifies the position at which to begin the search. The sign of start-position specifies the direction in which to search:
Value of startpos
Action
greater than 0
search begins at position start-position and proceeds to the right. If start-position is greater than the length of the string, then FINDW returns a value of 0.
less than 0
search begins at position –start-position and proceeds to the left. If start-position 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 start-position 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 start-position 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.

Processing SBCS and DBCS Data

The FINDW function is designed to process SBCS data, but it can process DBCS data with certain conditions. Here are the criteria for SBCS and DBCS processing:
  • If string is not declared as varchar or you are processing single-byte data, then FINDW processes SBCS.
  • If string is declared as varchar and you are processing multi-byte data, then FINDW processes DBCS.

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 Character and Start-position 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 character 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 Start-position 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 start-position 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 Start-position 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.
Last updated: March 16, 2017