#4435 Tcl_ExternalToUtf(...dst, dstLen,...) writes to dst[dstLen]

[Don Porter]

The docs of Tcl_ExternalToUtf() are unclear on the
boundaries of the write buffer. They say "... and up
to dstLen converted bytes are stored in dst." which
suggests bytes will be written in dst[0] up
to dst[dstLen-1]. And that appears to be an accurate
description of what the underlying ToUtfProc() does.
However, then Tcl_ExternalToUtf() appends a terminating
NUL character, and if the ToUtfProc has used all dstLen
bytes, T_ETU writes to dst[dstLen].

[Don Porter]

It should also be noted that no bytes (except that
terminating NUL) will be written unless dstLen is
at least TCL_UTF_MAX.

[Don Porter]

Sorry, I missed a line in Tcl_ExternalToUtf().
It decrements dstLen before passing to the
ToUtfProc to account for the byte it needs to
write NUL into.

[Don Porter]

no matter what the value of dstLen, writing
to the byte *dst must work. That is, don't expect
dstLen==0 to work.

To get at least one actual character in the output
buffer, dstLen must have a minimum value of
TCL_UTF_MAX + 1.

[Donal K. Fellows]

Maybe this just needs to be documented.