# allocate_string

Definition: | atom pString = allocate_string(sequence st, bool cleanup=false) -- or -- atom pWString = allocate_wstring(sequence st, bool cleanup=false)
Description: | Allocate space for string sequence st (ie st is either a string, or a sequence of atoms with no nested sub-sequences). Copy st into this space along with a 0 terminating character. This is the format expected for C strings. The memory address of the string will be returned. If there is not enough memory available, 0 will be returned.
pwa/p2js: | Not supported
Comments: | The allocate_string function creates an ansi (/utf8) string, 8 bits per character (possibly multibyte), whereas the allocate_wstring function creates a WideString, 16 bits per character (possibly with surrogate pairs). Note that the latter (allocate_wstring) may benefit from a call of utf8_to_utf16() or utf32_to_utf16() beforehand (and it would be most unwise for this routine to try and guess which, if either, is the most appropriate - a trivial application-specific wrapper is easy enough anyway). The comments of allocate() regarding cleanup and explicitly invoking free() or delete() apply equally here. Be advised, however, that using the automatic memory management flag is usually inappropriate for callback return values, as the memory will be freed (and the first few bytes clobbered) before the caller gets a chance to examine it (that is, unless the atom result is stored somewhere else semi-permanently outside the callback, for as long as it is required, see also IupRawStringPtr). Phix strings can be passed directly to C functions, however doing so is not compatible with Euphoria. There is, as yet, no builtin for allocating a 32-bits-per-character string, which would no doubt be trivial (see builtins\pAlloc.e) but I would rather wait until I find something that actually uses it, and hence can test it.
Example: |
    atom title = allocate_string("The Wizard of Oz")
    ...
    free(title)
For use in a complete application, see demo\arwendemo\mmsd.exw
Implementation: | See builtins\pAlloc.e (an autoinclude) for details of the actual implementation.
See Also: | allocate, free, IupRawStringPtr