Macro Functions: %SCAN and %QSCAN Functions (2024)

Macro Functions

Search for a word that is specified by its position in a string.

%SCAN(argument, n<,charlist<,modifiers>>)

%QSCAN(argument, n<,charlist<,modifiers>>)

argument

is a character string or a text expression.If argument might contain a special character or mnemonic operator,listed below, use %QSCAN. If argument contains a comma, enclose argument in a quoting function such as%BQUOTE(argument).

n

is an integer or a text expression thatyields an integer, which specifies the position of the word to return. (Animplied %EVAL gives n numeric properties.) If nis greater than the number of words in argument, the functionsreturn a null string.

Note:When you are using Version 8 or greater, if n isnegative, %SCAN examines the character string and selects the word that startsat the end of the string and searches backward.

charlist

specifies an optional character expression that initializesa list of characters. This list determines which characters are used as thedelimiters that separate words. The following rules apply:

• By default, all characters in charlistare used as delimiters.

• If you specify the K modifier in the modifierargument, then all characters that are not in charlist are used as delimiters.

Tip:	You can add more characters to charlist by using othermodifiers.

modifier

specifies a character constant, a variable, or an expressionin which each non-blank character modifies the action of the %SCAN function.Blanks are ignored. You can use the following characters as modifiers:

a or A	adds alphabetic characters to the list of characters.
b or B	scans backward from right to left instead of fromleft to right, regardless of the sign of the countargument.
c or C	adds control characters to the list of characters.
d or D	adds digits to the list of characters.
f or F	adds an underscore and English letters (that is,valid first characters in a SAS variable name using VALIDVARNAME=V7) to thelist of characters.
g or G	adds graphic characters to the list of characters.Graphic characters are characters that, when printed, produce an image onpaper.
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 ofcharacters to be treated as delimiters. That is, if K is specified, then charactersthat are in the list of characters are kept in the returned value rather thanbeing omitted because they are delimiters. If K is not specified, then allcharacters 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, anddelimiters at the beginning or end of the stringargument, refer to words that have a length of zero. If the M modifier isnot specified, then multiple consecutive delimiters are treated as one delimiter,and delimiters at the beginning or end of the stringargument are ignored.
n or N	adds digits, an underscore, and English letters (thatis, the characters that can appear in a SAS variable name using VALIDVARNAME=V7)to the list of characters.
o or O	processes the charlistand modifier arguments only once, rather thanevery time the %SCAN function is called. Tip: Using the O modifier in the DATA step (excludingWHERE clauses), or in the SQL procedure can make %SCAN run faster when youcall it in a loop where the charlist and modifier arguments do not change. The O modifier applies separatelyto each instance of the %SCAN function in your SAS code, and does not cause all instances of the %SCAN function to use the same delimitersand modifiers.
p or P	adds punctuation marks to the list of characters.
q or Q	ignores delimiters that are inside of substringsthat are enclosed in quotation marks. If the value of the string argument contains unmatched quotation marks, then scanningfrom left to right will produce different words than scanning from right toleft.
r or R	removes leading and trailing blanks from the wordthat %SCAN returns. Tip: If you specify both the Q and R modifiers,then the %SCAN function first removes leading and trailing blanks from theword. Then, if the word begins with a quotation mark, %SCAN also removes onelayer of quotation marks from the word.
s or S	adds space characters to the list of characters (blank,horizontal tab, vertical tab, carriage return, line feed, and form feed).
t or T	trims trailing blanks from the string and charlist arguments. Tip: If you want to remove trailing blanks fromonly one character argument instead of both character arguments, then usethe TRIM function instead of the %SCAN function with the T modifier.
u or U	adds uppercase letters to the list of characters.
w or W	adds printable (writable) characters to the listof characters.
x or X	adds hexadecimal characters to the list of characters.

Tip:	If the modifierargument is a character constant, then enclose it in quotation marks. Specifymultiple modifiers in a single set of quotation marks. A modifier argument can also be expressed as a character variable orexpression.

The %SCAN and %QSCAN functions search argument and return the nth word.A word is one or more characters separated by one or more delimiters.

%SCAN does not mask special characters or mnemonic operatorsin its result, even when the argument was previously masked by a macro quotingfunction. %QSCAN masks the following special characters and mnemonic operatorsin its result:

& % ' " ( ) + - * / < > = ¬ ^ ~ ; , # blankAND OR NOT EQ NE LE LT GE GT IN

A delimiter is any of several characters that are usedto separate words. You can specify the delimiters in the charlist and modifier arguments.

If you specify the Q modifier, thendelimiters inside of substringsthat are enclosed in quotation marks are ignored.

In the %SCAN function, "word" refers to a substring thathas all of the following characteristics:

• is bounded on the left by a delimiter or the beginning of thestring

• is bounded on the right by a delimiter or the end of the string

• contains no delimiters

A word canhave a length of zero if there are delimiters at the beginningor end of the string, or if the string contains two or more consecutive delimiters.However, the %SCAN function ignores words that have a length of zero unlessyou specify the M modifier.

If you use the %SCAN function with only two arguments,then the default delimiters depend on whether your computer uses ASCII orEBCDIC characters.

• If your computer uses ASCII characters, then the default delimitersare as follows:

  blank ! $ % & ( ) * + , - . / ; < ^¦

  In ASCII environments that do not contain the ^ character, the %SCANfunction uses the ~ character instead.

• If your computer uses EBCDIC characters, then the default delimitersare as follows:

  blank ! $ % & ( ) * + , - . / ; < ¬ | ¢¦

If you use the modifier argumentwithoutspecifying any characters as delimiters, then the only delimiters that willbe used are delimiters that are defined by the modifierargument. In this case, the lists of default delimiters for ASCII and EBCDICenvironments are not used. In other words, modifiers add to the list of delimitersthat are specified by the charlist argument.Modifiers do not add to the list of default modifiers.

If you specify the M modifier, then the number of wordsin a string is defined as one plus the number of delimiters in the string.However, if you specify the Q modifier, delimiters that are inside quotationmarks are ignored.

If you specify the M modifier, then the %SCAN function returns a wordwith a length of zero if one of the following conditions is true:

• The string begins with a delimiter and you request the first word.

• The string endswith a delimiter and you request the last word.

• The string contains two consecutive delimiters and you requestthe word that is between the two delimiters.

If you do not specify the M modifier, then the numberof words in a string is defined as the number of maximal substrings of consecutivenon-delimiters. However, if you specify the Q modifier, delimiters that areinside quotation marks are ignored.

If you do not specify the M modifier, then the %SCAN function does thefollowing:

• ignores delimiters at the beginning or end of the string

• treats two or more consecutive delimiters as if they were a singledelimiter

If the string contains no characters other than delimiters, or if youspecify a count that is greater in absolute value than the number of wordsin the string, then the %SCAN function returns one of the following:

• a single blank when you call the %SCAN function from a DATA step

• a stringwith a length of zero when you call the %SCAN functionfrom the macro processor

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

%QSCAN masks the same characters as the%NRBQUOTE function.

Example 1: Comparing the Actions of %SCAN and %QSCAN

This example illustrates the actions of %SCAN and %QSCAN.

%macro a; aaaaaa%mend a;%macro b; bbbbbb%mend b;%macro c; cccccc%mend c;%let x=%nrstr(%a*%b*%c);%put X: &x;%put The third word in X, with SCAN: %scan(&x,3,*);%put The third word in X, with QSCAN: %qscan(&x,3,*);

The %PUT statement writes these lines to the log:

X: %a*%b*%cThe third word in X, with SCAN: ccccccThe third word in X, with QSCAN: %c

Copyright © 2009 by SAS Institute Inc., Cary, NC, USA. All rights reserved.