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);