Add documentation. Do a better job of counting exactly which byte/character caused the encoding/decoding error

1 files changed, 19 insertions, 1 deletions

diff --git a/doc/Encoding.3 b/doc/Encoding.3
index 2d2461e..c33878a 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -26,8 +26,14 @@ char *
 \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
 char *
+\fBTcl_ExternalToUtfDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR)
+.sp
+char *
 \fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
+char *
+\fBTcl_UtfToExternalDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR)
+.sp
 int
 \fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
                   dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
@@ -108,7 +114,9 @@ byte is converted and then to reset to an initial state.
 \fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should
 return immediately upon reading a source character that does not exist in
 the target encoding; otherwise a default fallback character will
-automatically be substituted.
+automatically be substituted. The flag \fBTCL_ENCODING_MODIFIED\fR makes
+\fBTcl_UtfToExternalDStringEx\fR and \fBTcl_UtfToExternal\fR produce the
+byte sequence \exC0\ex80 in stead of \ex00, for the utf-8/wtf-8/cesu-8 encoders.
 .AP Tcl_EncodingState *statePtr in/out
 Used when converting a (generally long or indefinite length) byte stream
 in a piece-by-piece fashion.  The conversion routine stores its current
@@ -208,6 +216,11 @@ When converting, if any of the characters in the source buffer cannot be
 represented in the target encoding, a default fallback character will be
 used.  The return value is a pointer to the value stored in the DString.
 .PP
+\fBTcl_ExternalToUtfDStringEx\fR is the same as \fBTcl_ExternalToUtfDString\fR,
+but it has an additional flags parameter.  The return value is the index of
+the first byte in the input string causing a conversion error.
+Or (size_t)-1 if all is OK.
+.PP
 \fBTcl_ExternalToUtf\fR converts a source buffer \fIsrc\fR from the specified
 \fIencoding\fR into UTF-8.  Up to \fIsrcLen\fR bytes are converted from the
 source buffer and up to \fIdstLen\fR converted bytes are stored in \fIdst\fR.
@@ -246,6 +259,11 @@ characters in the source buffer cannot be represented in the target
 encoding, a default fallback character will be used.  The return value is
 a pointer to the value stored in the DString.
 .PP
+\fBTcl_UtfToExternalDStringEx\fR is the same as \fBTcl_UtfToExternalDString\fR,
+but it has an additional flags parameter.  The return value is the index of
+the first byte in the input string causing a conversion error.
+Or (size_t)-1 if all is OK.
+.PP
 \fBTcl_UtfToExternal\fR converts a source buffer \fIsrc\fR from UTF-8 into
 the specified \fIencoding\fR.  Up to \fIsrcLen\fR bytes are converted from
 the source buffer and up to \fIdstLen\fR converted bytes are stored in