(cherry-pick): Update documentation of Tcl_UtfPrev/Tcl_UtfNext back to how it was. Will be updated later, when implementation is ready and agreed upon.

1 files changed, 6 insertions, 15 deletions

diff --git a/doc/Utf.3 b/doc/Utf.3
index 55ef80d..e9bfaa7 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -141,7 +141,7 @@ source buffer is long enough such that this routine does not run off the
 end and dereference non-existent or random memory; if the source buffer
 is known to be null-terminated, this will not happen.  If the input is
 not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first
-byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0000 and
+byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0080 and
 0x00FF and return 1.
 .PP
 \fBTcl_UniCharToUtfDString\fR converts the given Unicode string
@@ -217,20 +217,11 @@ returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR
 in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
 considered part of the UTF-8 string.
 .PP
-\fBTcl_UtfNext\fR is used to step forward through a UTF-8 string.
-If the UTF-8 string is made up entirely of complete, well-formed, and
-valid character byte sequences, and \fIsrc\fR points to the lead byte
-of one of those sequences, then repeated calls of \fBTcl_UtfNext\fR will
-return pointers to the lead bytes of each character in the string, one
-character at a time. In any other circumstance, \fBTcl_UtfNext\fR
-returns \fIsrc\fR+1.  \fBTcl_UtfNext\fR will always read \fIsrc[0]\fR
-and may read as many following bytes (up to a total of \fBTCL_UTF_MAX\fR)
-as needed to find the end of the byte sequence. If the string is
-\fBNUL\fR-terminated, \fBTcl_UtfNext\fR will not read beyond the terminating
-\fBNUL\fR byte. If not, the caller must use the companion routine
-\fBTcl_UtfCharComplete\fR to determine whether there is any risk
-\fBTcl_UtfNext\fR might read beyond the readable memory occupied
-by the string.
+Given \fIsrc\fR, a pointer to some location in a UTF-8 string,
+\fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the
+string.  The caller must not ask for the next character after the last
+character in the string if the string is not terminated by a null
+character.
 .PP
 \fBTcl_UtfPrev\fR is used to step backward through but not beyond the
 UTF-8 string that begins at \fIstart\fR.  If the UTF-8 string is made