allocate_string

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