Summary: Predefined macro string functions are new to MASM 6.0.
The assembler provides the following directives for manipulating text: SUBSTR, INSTR, SIZESTR, and CATSTR. Each of these has a corresponding predefined macro function version: @SubStr, @InStr, @SizeStr, and @CatStr.
You use the directive versions to assign a processed value to a text macro or numeric equate. For example, CATSTR, which concatenates a list of text values, can be used like this:
num = 7
newstr CATSTR <3 + >, %num, < = > , %3 + num ; "3 + 7 = 10"
Assignment with CATSTR and SUBSTR works like assignment with the TEXTEQU directive. Assignment with SIZESTR and INSTR works like assignment with the = operator.
The arguments to directives must be text values. Use the expansion operator to make sure that constants and numeric equates are expanded to text.
The macro function versions are similar, but their arguments must be enclosed in parentheses. Macro functions return text values and can be used in any context where text is expected. Section 9.6 tells how to write your own macro functions. An equivalent statement to the previous example using CATSTR is
num = 7
newstr TEXTEQU @CatStr( <3 + >, %num, < = > , %3 + num )
Although the directive version is simpler in the example above, the function versions are often convenient because they can be used as arguments to string directives or to other macro functions.
Unlike the string directives, predefined macro function names are case sensitive. Since MASM is not case sensitive by default, the case doesn't matter unless you use the /Cp command-line option.
The following sections summarize the syntax for each of the string directives and functions. The explanations focus on the directives, but the functions work the same except where noted.
SUBSTR
name SUBSTR string, start[[, length]]
@SubStr( string, start[[, length]] )
The SUBSTR directive assigns a substring from a given string to a new symbol, specified by name. Start specifies the position (1-based) in string to start the substring. Length specifies the length of the substring. If length is not given, it is assumed to be the remainder of the string including the start character. The stringin the SUBSTR syntax, as well as in the syntax for the other string directives and predefined functions, can be any textItem where textItem can be text enclosed in angle brackets (<>), the name of a macro, or a constant expression preceded by % (%constExpr).
INSTR
nameINSTR [[start,]]string,substring
@InStr( [[start]],string,substring )
The INSTR directive searches a specified string for an occurrence of a given substring and assigns its position (1-based) to name. The search is case sensitive. Start is the position in string to start the search for substring. If start is not given, it is assumed to be 1 (the start of the string). If substring is not found, the position assigned to name is 0.
If the INSTR directive is used, the position value is assigned to a name as if it were a numeric equate. If the @InStr function is used, the value is returned as a string of digits in the current radix.
The @InStr function has a slightly different syntax than the INSTR directive. You can omit the first argument and its associated comma from the directive. You can leave the first argument blank with the function, but a blank function argument must still have a comma. For example,
pos INSTR <person>, <son>
is the same as
pos = @InStr( , <person>, <son> )
The return value could also be assigned to a text macro:
strpos TEXTEQU @InStr( , <person>, <son> )
SIZESTR
name SIZESTR string
@SizeStr( string )
The SIZESTR directive assigns the number of characters in string to name. An empty string assigns a length of zero. Although the length is always a positive number, it is assigned as a string of digits in the current radix rather than as a numeric value.
If the SIZESTR directive is used, the size value is assigned to a name as if it were a numeric equate. If the @SizeStr function is used, the value is returned as a string of digits in the current radix.
CATSTR
nameCATSTRstring[[, string]]...
@CatStr(string[[, string]]... )
The CATSTR directive concatenates a list of text values specified by string into a single text value and assigns it to name. TEXTEQU is technically a synonym for CATSTR. TEXTEQU is normally used for single-string assignments, while CATSTR is used for multistring concatenations.
The following example that pushes and pops one set of registers illustrates several uses of string directives and functions:
; SaveRegs - Macro to generate a push instruction for each
; register in argument list. Saves each register name in the
; regpushed text macro.
regpushed TEXTEQU <> ;; Initialize empty string
SaveRegs MACRO regs:VARARG
FOR reg, <regs> ;; Push each register
push reg ;; and add it to the list
regpushed CATSTR <reg>, <,>, regpushed
ENDM ;; Strip off last comma
regpushed CATSTR <!<>, regpushed ;; Mark start of list with <
regpushed SUBSTR regpushed, 1, @SizeStr( regpushed )
regpushed CATSTR regpushed, <!>> ;; Mark end with >
ENDM
; RestoreRegs - Macro to generate a pop instruction for registers
; saved by the SaveRegs macro. Restores one group of registers.
RestoreRegs MACRO
LOCAL regs
%FOR reg, regpushed ;; Pop each register pop reg
ENDM
ENDM
Notice how the SaveRegs macro saves its result in the regpushed text macro for later use by the RestoreRegs macro. In this case, a text macro is used as a global variable. By contrast, the regs text macro is used only in RestoreRegs. It is declared LOCAL so that it won't take the name regs from the global name space. The MACROS.INC file provided with MASM 6.0 includes expanded versions of these same two macros.