This function allocates and returns a pointer pointing to a structure of type SbData holding a string value. If the allocation failed the return value is NULL. If the memory allocation was successful the allocated structure will have the type SBT_STRING and will hold the initial value specified by the argument pszInitValue.
pSbData scriba_NewSbString(pSbProgram pProgram,
char *pszInitValue
){
@b{Note on ZCHAR termination:}
The init value pszInitValue should be a zchar terminated string. Note that ScriptBasic internally stores the strings as series byte and the length of the string without any terminating zchar. Therefore the length of the string that is stored should have been strlen(pszInitValue). This does not contain the terminating zchar.
In reality however we allocate an extra byte that stores the zchar, but the size of the string is one character less. Therefore ScriptBasic routines will recognize the size of the string correct and also the caller can use the string using the macro scriba_GetString as a zchar terminated C string. This requires an extra byte of storage for each string passed from the embedding C application to ScriptBasic, but saves a lot of hedeache and also memory copy when the string has to be used as a zchar terminated string.
See also @xref{scriba_NewSbLong()}, @xref{scriba_NewSbDouble()}, @xref{scriba_NewSbUndef()}, @xref{scriba_NewSbString()}, @xref{scriba_NewSbBytes()}, @xref{scriba_DestroySbData()}.