* Merged changes from 8.1.0 branch

1 files changed, 54 insertions, 3 deletions

diff --git a/doc/Utf.3 b/doc/Utf.3
index f68a6cb..12756bc 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -4,13 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Utf.3,v 1.2 1999/04/16 00:46:34 stanton Exp $
+'\" RCS: @(#) $Id: Utf.3,v 1.3 1999/04/30 22:45:01 stanton Exp $
 '\" 
 .so man.macros
 .TH Utf 3 "8.1" Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings.
+Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -23,6 +23,18 @@ int
 int
 \fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR)
 .sp
+char *
+\fBTcl_UniCharToUtfDString\fR(\fIuniStr, numChars, dstPtr\fR)
+.sp
+Tcl_UniChar *
+\fBTcl_UtfToUniCharDString\fR(\fIsrc, len, dstPtr\fR)
+.sp
+int
+\fBTcl_UniCharLen\fR(\fIuniStr\fR)
+.sp
+int
+\fBTcl_UniCharNcmp\fR(\fIuniStr, uniStr, num\fR)
+.sp
 int
 \fBTcl_UtfCharComplete\fR(\fIsrc, len\fR)
 .sp
@@ -50,7 +62,7 @@ char *
 int
 \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR)
 .SH ARGUMENTS
-.AS "CONST char" *chPtr out
+.AS "CONST Tcl_UniChar" numChars in/out
 .AP char *buf out
 Buffer in which the UTF-8 representation of the Tcl_UniChar is stored.  At most
 TCL_UTF_MAX bytes are stored in the buffer.
@@ -60,9 +72,18 @@ The Tcl_UniChar to be converted or examined.
 Filled with the Tcl_UniChar represented by the head of the UTF-8 string.
 .AP "CONST char" *src in
 Pointer to a UTF-8 string.
+.AP "CONST Tcl_UniChar" *uniStr in
+A NULL-terminated Unicode string.
 .AP int len in
 The length of the UTF-8 string in bytes (not UTF-8 characters).  If
 negative, all bytes up to the first null byte are used.
+.AP int numChars in
+The length of the Unicode string in characters.  Must be greater than or
+equal to 0.
+.AP "Tcl_DString" *dstPtr in/out
+A pointer to a previously-initialized \fBTcl_DString\fR.
+.AP size_t n in
+The number of Unicode characters to compare in \fBTcl_UniCharNcmp\fR.
 .AP "CONST char" *start in
 Pointer to the beginning of a UTF-8 string.
 .AP int index in
@@ -100,6 +121,36 @@ 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
 0x00ff and return 1.  
 .PP
+\fBTcl_UniCharToUtfDString\fR converts the given Unicode string
+to UTF-8, storing the result in a previously-initialized \fBTcl_DString\fR.
+You must specify the length of the given Unicode string.
+The return value is a pointer to the UTF-8 representation of the
+Unicode string.  Storage for the return value is appended to the
+end of the \fBTcl_DString\fR.
+.PP
+\fBTcl_UtfToUniCharDString\fR coverts the given UTF-8 string to Unicode,
+storing the result in the previously-initialized \fBTcl_Dstring\fR.
+you may either specify the length of the given UTF-8 string or "-1",
+in which case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to
+calculate the length.  The return value is a pointer to the Unicode
+representation of the UTF-8 string.  Storage for the return value
+is appended to the end of the \fBTcl_DString\fR.  The Unicode string
+is terminated with a Unicode NULL character.
+.PP
+\fBTcl_UniCharLen\fR corresponds to \fBstrlen\fR for Unicode
+characters.  It accepts a NULL-terminated Unicode string and returns
+the number of Unicode characters (not bytes) in that string.
+.PP
+\fBTcl_UniCharNcmp\fR corresponds to \fBstrncmp\fR for Unicode
+characters.  It accepts two NULL-terminated Unicode strings
+and the number of characters to compare.  (Both strings are
+assumed to be at least \fIlen\fR characters long.)
+\fBTcl_UniCharNcmp\fR compares the two strings character-by-character
+according to the Unicode character ordering.  It returns an integer
+greater than, equal to,
+or less than 0 if the first string is greater than, equal to, or
+less than the second string respectively.
+.PP
 \fBTcl_UtfCharComplete\fR returns 1 if the source UTF-8 string \fIsrc\fR
 of length \fIlen\fR bytes is long enough to be decoded by
 \fBTcl_UtfToUniChar\fR, or 0 otherwise.  This function does not guarantee