| SYMSTR | Function (Macro)

vat.h

SYM_STR SYMSTR (const char *s);

Defines a VAT string.

Most of the TIOS functions which take symbol names as parameters do not accept ordinary C strings. Instead, the symbol name is either a variable tag or a sequence of characters which starts with the zero character (`'\0'`) and terminates with the zero character as well, and the TIOS routines for VAT handling need a pointer to the terminating zero byte as the input argument, which is a little twisty. For example, to search for a symbol named "tetris", instead of

    hsym = SymFind ("tetris");

you have to do the following:

    hsym = SymFind ("\0tetris"+7);

To make this job easier, the SYMSTR macro is implemented, so you may simply do

    hsym = SymFind (SYMSTR ("tetris"));

If the argument passed to SYMSTR is a string literal as in this case, SYMSTR simply expands to the sequence in the second example. This is an optimization done by the preprocessor. In all other cases, space for a temporary string is allocated on the stack using alloca, and the string is copied to this location on the stack. Strictly speaking, SYMSTR does not return a pointer of type SYM_STR in this case, but rather a pointer to non-constant data. This means that you may write to it if you wish.
Note that this macro doesn't check whether s is valid or not. If you need to tokenize a variable string and want to be sure that s is valid, you can use the TokenizeSymName routine.
Note: You cannot create tokens for system variables using this macro. See EXT_SYSTEM_TAG for more information. And if you want to use a single-character variable name, you can usually use one of the variable tags from the enum Tags. Note also that all legal TIOS symbol names must be in lowercase.

Uses: alloca, memcpy, strlen

See also: TokenizeSymName