 |
SYMSTR |
Function (Macro) |
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