summaryrefslogtreecommitdiffstats
path: root/doc/Encoding.3
diff options
context:
space:
mode:
authorstanton <stanton>1999-04-30 22:44:59 (GMT)
committerstanton <stanton>1999-04-30 22:44:59 (GMT)
commitfe45fa11e3df7cd37954c0f8051d9948114951b6 (patch)
treea193f27eb18d04a30f8b4f663611d5957c2f5f6a /doc/Encoding.3
parentb81b15c0f284194a10d17be0a8daa622ec578d94 (diff)
downloadtcl-fe45fa11e3df7cd37954c0f8051d9948114951b6.zip
tcl-fe45fa11e3df7cd37954c0f8051d9948114951b6.tar.gz
tcl-fe45fa11e3df7cd37954c0f8051d9948114951b6.tar.bz2
* Merged changes from 8.1.0 branch
Diffstat (limited to 'doc/Encoding.3')
-rw-r--r--doc/Encoding.364
1 files changed, 53 insertions, 11 deletions
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index e9329dd..8d1262b 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -4,17 +4,18 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: Encoding.3,v 1.2 1999/04/16 00:46:31 stanton Exp $
+'\" RCS: @(#) $Id: Encoding.3,v 1.3 1999/04/30 22:45:00 stanton Exp $
'\"
.so man.macros
.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings.
-
-
-
-
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString,
+Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal,
+Tcl_WinTCharToUtf, Tcl_WinUtfToTChar,
+Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames,
+Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir,
+Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -40,6 +41,12 @@ int
dstCharsPtr\fR)
.sp
char *
+\fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR)
+.sp
+TCHAR *
+\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR)
+.sp
+char *
\fBTcl_GetEncodingName\fR(\fIencoding\fR)
.sp
int
@@ -50,7 +57,6 @@ void
.sp
Tcl_Encoding
\fBTcl_CreateEncoding\fR(\fItypePtr\fR)
-
.sp
char *
\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
@@ -72,10 +78,12 @@ NULL, the current system encoding is used.
.AP "CONST char" *src in
For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
specified encoding that are to be converted to UTF-8. For the
-\fBTcl_UtfToExternal\fR functions, an array of UTF-8 characters to be
-converted to the specified encoding.
+\fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of
+UTF-8 characters to be converted to the specified encoding.
+.AP "CONST TCHAR" *tsrc in
+An array of Windows TCHAR characters to convert to UTF-8.
.AP int srcLen in
-Length of \fIsrc\fR in bytes. If the length is negative, the
+Length of \fIsrc\fR or \fItsrc\fR in bytes. If the length is negative, the
encoding-specific length of the string is used.
.AP Tcl_DString *dstPtr out
Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
@@ -223,7 +231,41 @@ is filled with the corresponding number of bytes that were stored in
\fIdst\fR. The return values are the same as the return values for
\fBTcl_ExternalToUtf\fR.
.PP
-\fBTcl_GetEncodingName\fR is roughly the inverse of \fBTk_GetEncoding\fR.
+\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are
+Windows-only convenience
+functions for converting between UTF-8 and Windows strings. On Windows 95
+(as with the Macintosh and Unix operating systems),
+all strings exchanged between Tcl and the operating system are "char"
+based. On Windows NT, some strings exchanged between Tcl and the
+operating system are "char" oriented while others are in Unicode. By
+convention, in Windows a TCHAR is a character in the ANSI code page
+on Windows 95 and a Unicode character on Windows NT.
+.PP
+If you planned to use the same "char" based interfaces on both Windows
+95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and
+\fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an
+encoding of NULL (the current system encoding). On the other hand,
+if you planned to use the Unicode interface when running on Windows NT
+and the "char" interfaces when running on Windows 95, you would have
+to perform the following type of test over and over in your program
+(as represented in psuedo-code):
+.CS
+if (running NT) {
+ encoding <- Tcl_GetEncoding("unicode");
+ nativeBuffer <- Tcl_UtfToExternal(encoding, utfBuffer);
+ Tcl_FreeEncoding(encoding);
+} else {
+ nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer);
+.CE
+\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically
+handle this test and use the proper encoding based on the current
+operating system. \fBTcl_WinUtfToTChar\fR returns a pointer to
+a TCHAR string, and \fBTcl_WinTCharToUtf\fR expects a TCHAR string
+pointer as the \fIsrc\fR string. Otherwise, these functions
+behave identically to \fBTcl_UtfToExternalDString\fR and
+\fBTcl_ExternalToUtfDString\fR.
+.PP
+\fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR.
Given an \fIencoding\fR, the return value is the \fIname\fR argument that
was used to create the encoding. The string returned by
\fBTcl_GetEncodingName\fR is only guaranteed to persist until the