Template std.utf.toUTFz
Returns a C-style zero-terminated string equivalent to str
. str
must not contain embedded '\0'
's as any C function will treat the first
'\0'
that it sees as the end of the string. If str
is
true
, then a string containing only '\0'
is returned.
template toUTFz(P)
;
toUTFz
accepts any type of string and is templated on the type of
character pointer that you wish to convert to. It will avoid allocating a
new string if it can, but there's a decent chance that it will end up having
to allocate a new string - particularly when dealing with character types
other than char
.
Warning 1: If the result of toUTFz
equals str
, then if
anything alters the character one past the end of str
(which is the
'\0'
character terminating the string), then the string won't be
zero-terminated anymore. The most likely scenarios for that are if you
append to str
and no reallocation takes place or when str
is a
slice of a larger array, and you alter the character in the larger array
which is one character past the end of str
. Another case where it could
occur would be if you had a mutable character array immediately after
str
in memory (for example, if they're member variables in a
user-defined type with one declared right after the other) and that
character array happened to start with '\0'
. Such scenarios will never
occur if you immediately use the zero-terminated string after calling
toUTFz
and the C function using it doesn't keep a reference to it.
Also, they are unlikely to occur even if you save the zero-terminated string
(the cases above would be among the few examples of where it could happen).
However, if you save the zero-terminate string and want to be absolutely
certain that the string stays zero-terminated, then simply append a
'\0'
to the string and use its ptr
property rather than calling
toUTFz
.
Warning 2: When passing a character pointer to a C function, and the C function keeps it around for any reason, make sure that you keep a reference to it in your D code. Otherwise, it may go away during a garbage collection cycle and cause a nasty bug when the C code tries to use it.
Contained Functions
Name | Description |
---|---|
toUTFz |
Example
auto p1 = toUTFz!(char*)("hello world");
auto p2 = toUTFz!(const(char)*)("hello world");
auto p3 = toUTFz!(immutable(char)*)("hello world");
auto p4 = toUTFz!(char*)("hello world"d);
auto p5 = toUTFz!(const(wchar)*)("hello world");
auto p6 = toUTFz!(immutable(dchar)*)("hello world"w);