Definition: |
atom a = allocate_string(sequence st, bool cleanup=false)
-- or -- atom a = 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.
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). |
Comments: |
To free the string, use free(). If the optional cleanup parameter is non-zero, you must never manually call free, instead it
will be performed automatically when the reference count of the result drops to zero, which typically occurs on exit from a
routine. 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 OpenEuphoria. 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 find something that actually uses it, so that I can actually test it. |
Example: |
atom title title = allocate_string("The Wizard of Oz") ... free(title) |
Example Program: | demo\arwendemo\mmsd.exw |
See Also: | allocate, free, IupRawStringPtr |