diff options
Diffstat (limited to 'doc/Encoding.3')
| -rw-r--r-- | doc/Encoding.3 | 64 |
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 |