String Manipulation Functions (DEFINE-!ENDDEFINE command)

String manipulation functions process one or more character strings and produce either a new character string or a character representation of a numeric result.

• The result of any string manipulation function is treated as a character string.
• The arguments to string manipulation functions can be strings, variables, or even other macros. A macro argument or another function can be used in place of a string.
• The strings within string manipulation functions must be either single tokens, such as ABC, or delimited by apostrophes or quotation marks, as in ‘A B C’.

!LENGTH (str). Return the length of the specified string. The result is a character representation of the string length. !LENGTH(abcdef) returns 6. If the string is specified with apostrophes around it, each apostrophe adds 1 to the length. !LENGTH (‘abcdef’) returns 8. If an argument is used in place of a string and it is set to null, this function will return 0.

!CONCAT (str1,str2 . . .). Return a string that is the concatenation of the strings. For example, !CONCAT (abc,def) returns abcdef.

!SUBSTR (str,from,[length]). Return a substring of the specified string. The substring starts at the from position and continues for the specified length. If the length is not specified, the substring ends at the end of the input string. For example, !SUBSTR (abcdef, 3, 2) returns cd.

!INDEX (haystack,needle). Return the position of the first occurrence of the needle in the haystack. If the needle is not found in the haystack, the function returns 0. !INDEX (abcdef,def) returns 4.

!HEAD (str). Return the first token within a string. The input string is not changed. !HEAD (‘a b c’) returns a.

!TAIL (str). Return all tokens except the head token. The input string is not changed. !TAIL(‘a b c’) returns b c.

!QUOTE (str). Put apostrophes around the argument. !QUOTE replicates any embedded apostrophe. !QUOTE(abc) returns ‘abc’. If !1 equals Bill’s, !QUOTE(!1) returns ‘Bill’’s’.

!UNQUOTE (str). Remove quotation marks and apostrophes from the enclosed string. If !1 equals ‘abc’, !UNQUOTE(!1) is abc. Internal paired quotation marks are unpaired; if !1 equals ‘Bill”s’, !UNQUOTE(!1) is Bill’s. The specification !UNQUOTE(!QUOTE(Bill)) returns Bill.

!UPCASE (str). Convert all lowercase characters in the argument to uppercase. !UPCASE(‘abc def’) returns ABC DEF.

!BLANKS (n). Generate a string containing the specified number of blanks. The n specification must be a positive integer. !BLANKS(5) returns a string of five blank spaces. Unless the blanks are quoted, they cannot be processed, since the macro facility compresses blanks.

!NULL. Generate a string of length 0. This can help determine whether an argument was ever assigned a value, as in !IF (!1 !EQ !NULL) !THEN. . . .

!EVAL (str). Scan the argument for macro calls. During macro definition, an argument to a function or an operand in an expression is not scanned for possible macro calls unless the !EVAL function is used. It returns a string that is the expansion of its argument. For example, if mac1 is a macro, then !EVAL(mac1) returns the expansion of mac1. If mac1 is not a macro, !EVAL(mac1) returns mac1.