Encode Utf8 up to a maximum of 4 bytes long (five & six byte
variations are not supported).
If the output is provided off the stack, it should be large
enough to encompass the entire transcoding; failing to do
so will cause the output to be moved onto the heap instead.
Returns a slice of the output buffer, corresponding to the
converted characters. For optimum performance, the returned
buffer should be specified as 'output' on subsequent calls.
For example:
char[] output;
char[] result = toString (input, output);
// reset output after a realloc
if (result.length > output.length)
output = result;
Where 'ate' is provided, it will be set to the number of
elements consumed from the input, and the output buffer
will not be resized (or allocated). This represents a
streaming mode, where slices of the input are processed
in sequence rather than all at one time (should use 'ate'
as an index for slicing into unconsumed input).