util/src/TclTk/tcl8.6.12/doc/Utf.3

   1 '\"
   2 '\" Copyright (c) 1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Utf 3 "8.1" Tcl "Tcl Library Procedures"
   8 .so man.macros
   9 .BS
  10 .SH NAME
  11 Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings
  12 .SH SYNOPSIS
  13 .nf
  14 \fB#include <tcl.h>\fR
  15 .sp
  16 typedef ... \fBTcl_UniChar\fR;
  17 .sp
  18 int
  19 \fBTcl_UniCharToUtf\fR(\fIch, buf\fR)
  20 .sp
  21 int
  22 \fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR)
  23 .sp
  24 char *
  25 \fBTcl_UniCharToUtfDString\fR(\fIuniStr, uniLength, dsPtr\fR)
  26 .sp
  27 Tcl_UniChar *
  28 \fBTcl_UtfToUniCharDString\fR(\fIsrc, length, dsPtr\fR)
  29 .sp
  30 int
  31 \fBTcl_UniCharLen\fR(\fIuniStr\fR)
  32 .sp
  33 int
  34 \fBTcl_UniCharNcmp\fR(\fIucs, uct, numChars\fR)
  35 .sp
  36 int
  37 \fBTcl_UniCharNcasecmp\fR(\fIucs, uct, numChars\fR)
  38 .sp
  39 int
  40 \fBTcl_UniCharCaseMatch\fR(\fIuniStr, uniPattern, nocase\fR)
  41 .sp
  42 int
  43 \fBTcl_UtfNcmp\fR(\fIcs, ct, numChars\fR)
  44 .sp
  45 int
  46 \fBTcl_UtfNcasecmp\fR(\fIcs, ct, numChars\fR)
  47 .sp
  48 int
  49 \fBTcl_UtfCharComplete\fR(\fIsrc, length\fR)
  50 .sp
  51 int
  52 \fBTcl_NumUtfChars\fR(\fIsrc, length\fR)
  53 .sp
  54 const char *
  55 \fBTcl_UtfFindFirst\fR(\fIsrc, ch\fR)
  56 .sp
  57 const char *
  58 \fBTcl_UtfFindLast\fR(\fIsrc, ch\fR)
  59 .sp
  60 const char *
  61 \fBTcl_UtfNext\fR(\fIsrc\fR)
  62 .sp
  63 const char *
  64 \fBTcl_UtfPrev\fR(\fIsrc, start\fR)
  65 .sp
  66 Tcl_UniChar
  67 \fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR)
  68 .sp
  69 const char *
  70 \fBTcl_UtfAtIndex\fR(\fIsrc, index\fR)
  71 .sp
  72 int
  73 \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR)
  74 .SH ARGUMENTS
  75 .AS "const Tcl_UniChar" *uniPattern in/out
  76 .AP char *buf out
  77 Buffer in which the UTF-8 representation of the Tcl_UniChar is stored.  At most
  78 \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
  79 .AP int ch in
  80 The Unicode character to be converted or examined.
  81 .AP Tcl_UniChar *chPtr out
  82 Filled with the Tcl_UniChar represented by the head of the UTF-8 string.
  83 .AP "const char" *src in
  84 Pointer to a UTF-8 string.
  85 .AP "const char" *cs in
  86 Pointer to a UTF-8 string.
  87 .AP "const char" *ct in
  88 Pointer to a UTF-8 string.
  89 .AP "const Tcl_UniChar" *uniStr in
  90 A null-terminated Unicode string.
  91 .AP "const Tcl_UniChar" *ucs in
  92 A null-terminated Unicode string.
  93 .AP "const Tcl_UniChar" *uct in
  94 A null-terminated Unicode string.
  95 .AP "const Tcl_UniChar" *uniPattern in
  96 A null-terminated Unicode string.
  97 .AP int length in
  98 The length of the UTF-8 string in bytes (not UTF-8 characters).  If
  99 negative, all bytes up to the first null byte are used.
 100 .AP int uniLength in
 101 The length of the Unicode string in characters.  Must be greater than or
 102 equal to 0.
 103 .AP "Tcl_DString" *dsPtr in/out
 104 A pointer to a previously initialized \fBTcl_DString\fR.
 105 .AP "unsigned long" numChars in
 106 The number of characters to compare.
 107 .AP "const char" *start in
 108 Pointer to the beginning of a UTF-8 string.
 109 .AP int index in
 110 The index of a character (not byte) in the UTF-8 string.
 111 .AP int *readPtr out
 112 If non-NULL, filled with the number of bytes in the backslash sequence,
 113 including the backslash character.
 114 .AP char *dst out
 115 Buffer in which the bytes represented by the backslash sequence are stored.
 116 At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
 117 .AP int nocase in
 118 Specifies whether the match should be done case-sensitive (0) or
 119 case-insensitive (1).
 120 .BE
 121
 122 .SH DESCRIPTION
 123 .PP
 124 These routines convert between UTF-8 strings and Tcl_UniChars.  A
 125 Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size
 126 quantity.  A UTF-8 character is a Unicode character represented as
 127 a varying-length sequence of up to \fBTCL_UTF_MAX\fR bytes.  A multibyte UTF-8
 128 sequence consists of a lead byte followed by some number of trail bytes.
 129 .PP
 130 \fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to
 131 represent one Unicode character in the UTF-8 representation.
 132 .PP
 133 \fBTcl_UniCharToUtf\fR stores the Tcl_UniChar \fIch\fR as a UTF-8 string
 134 in starting at \fIbuf\fR.  The return value is the number of bytes stored
 135 in \fIbuf\fR.
 136 .PP
 137 \fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR
 138 and stores it as a Tcl_UniChar in \fI*chPtr\fR.  The return value is the
 139 number of bytes read from \fIsrc\fR.  The caller must ensure that the
 140 source buffer is long enough such that this routine does not run off the
 141 end and dereference non-existent or random memory; if the source buffer
 142 is known to be null-terminated, this will not happen.  If the input is
 143 not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first
 144 byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x80 and
 145 0xFF and return 1.
 146 .PP
 147 \fBTcl_UniCharToUtfDString\fR converts the given Unicode string
 148 to UTF-8, storing the result in a previously initialized \fBTcl_DString\fR.
 149 You must specify \fIuniLength\fR, the length of the given Unicode string.
 150 The return value is a pointer to the UTF-8 representation of the
 151 Unicode string.  Storage for the return value is appended to the
 152 end of the \fBTcl_DString\fR.
 153 .PP
 154 \fBTcl_UtfToUniCharDString\fR converts the given UTF-8 string to Unicode,
 155 storing the result in the previously initialized \fBTcl_DString\fR.
 156 In the argument \fIlength\fR, you may either specify the length of
 157 the given UTF-8 string in bytes or
 158 .QW \-1 ,
 159 in which case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to
 160 calculate the length.  The return value is a pointer to the Unicode
 161 representation of the UTF-8 string.  Storage for the return value
 162 is appended to the end of the \fBTcl_DString\fR.  The Unicode string
 163 is terminated with a Unicode null character.
 164 .PP
 165 \fBTcl_UniCharLen\fR corresponds to \fBstrlen\fR for Unicode
 166 characters.  It accepts a null-terminated Unicode string and returns
 167 the number of Unicode characters (not bytes) in that string.
 168 .PP
 169 \fBTcl_UniCharNcmp\fR and \fBTcl_UniCharNcasecmp\fR correspond to
 170 \fBstrncmp\fR and \fBstrncasecmp\fR, respectively, for Unicode characters.
 171 They accept two null-terminated Unicode strings and the number of characters
 172 to compare.  Both strings are assumed to be at least \fInumChars\fR characters
 173 long. \fBTcl_UniCharNcmp\fR  compares the two strings character-by-character
 174 according to the Unicode character ordering.  It returns an integer greater
 175 than, equal to, or less than 0 if the first string is greater than, equal
 176 to, or less than the second string respectively.  \fBTcl_UniCharNcasecmp\fR
 177 is the Unicode case insensitive version.
 178 .PP
 179 \fBTcl_UniCharCaseMatch\fR is the Unicode equivalent to
 180 \fBTcl_StringCaseMatch\fR.  It accepts a null-terminated Unicode string,
 181 a Unicode pattern, and a boolean value specifying whether the match should
 182 be case sensitive and returns whether the string matches the pattern.
 183 .PP
 184 \fBTcl_UtfNcmp\fR corresponds to \fBstrncmp\fR for UTF-8 strings. It
 185 accepts two null-terminated UTF-8 strings and the number of characters
 186 to compare.  (Both strings are assumed to be at least \fInumChars\fR
 187 characters long.)  \fBTcl_UtfNcmp\fR compares the two strings
 188 character-by-character according to the Unicode character ordering.
 189 It returns an integer greater than, equal to, or less than 0 if the
 190 first string is greater than, equal to, or less than the second string
 191 respectively.
 192 .PP
 193 \fBTcl_UtfNcasecmp\fR corresponds to \fBstrncasecmp\fR for UTF-8
 194 strings.  It is similar to \fBTcl_UtfNcmp\fR except comparisons ignore
 195 differences in case when comparing upper, lower or title case
 196 characters.
 197 .PP
 198 \fBTcl_UtfCharComplete\fR returns 1 if the source UTF-8 string \fIsrc\fR
 199 of \fIlength\fR bytes is long enough to be decoded by
 200 \fBTcl_UtfToUniChar\fR/\fBTcl_UtfNext\fR, or 0 otherwise.  This function
 201 does not guarantee that the UTF-8 string is properly formed.  This routine
 202 is used by procedures that are operating on a byte at a time and need to
 203 know if a full Tcl_UniChar has been seen.
 204 .PP
 205 \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings.  It
 206 returns the number of Tcl_UniChars that are represented by the UTF-8 string
 207 \fIsrc\fR.  The length of the source string is \fIlength\fR bytes.  If the
 208 length is negative, all bytes up to the first null byte are used.
 209 .PP
 210 \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings.  It
 211 returns a pointer to the first occurrence of the Tcl_UniChar \fIch\fR
 212 in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
 213 considered part of the UTF-8 string.
 214 .PP
 215 \fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings.  It
 216 returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR
 217 in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
 218 considered part of the UTF-8 string.
 219 .PP
 220 Given \fIsrc\fR, a pointer to some location in a UTF-8 string,
 221 \fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the
 222 string.  The caller must not ask for the next character after the last
 223 character in the string if the string is not terminated by a null
 224 character. \fBTcl_UtfCharComplete\fR can be used in that case to
 225 make sure enough bytes are available before calling \fBTcl_UtfNext\fR.
 226 .PP
 227 \fBTcl_UtfPrev\fR is used to step backward through but not beyond the
 228 UTF-8 string that begins at \fIstart\fR.  If the UTF-8 string is made
 229 up entirely of complete and well-formed characters, and \fIsrc\fR points
 230 to the lead byte of one of those characters (or to the location one byte
 231 past the end of the string), then repeated calls of \fBTcl_UtfPrev\fR will
 232 return pointers to the lead bytes of each character in the string, one
 233 character at a time, terminating when it returns \fIstart\fR.
 234 .PP
 235 When the conditions of completeness and well-formedness may not be satisfied,
 236 a more precise description of the function of \fBTcl_UtfPrev\fR is necessary.
 237 It always returns a pointer greater than or equal to \fIstart\fR; that is,
 238 always a pointer to a location in the string. It always returns a pointer to
 239 a byte that begins a character when scanning for characters beginning
 240 from \fIstart\fR. When \fIsrc\fR is greater than \fIstart\fR, it
 241 always returns a pointer less than \fIsrc\fR and greater than or
 242 equal to (\fIsrc\fR - \fBTCL_UTF_MAX\fR).  The character that begins
 243 at the returned pointer is the first one that either includes the
 244 byte \fIsrc[-1]\fR, or might include it if the right trail bytes are
 245 present at \fIsrc\fR and greater. \fBTcl_UtfPrev\fR never reads the
 246 byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte
 247 \fIsrc[-\fBTCL_UTF_MAX\fI-1]\fR.
 248 .PP
 249 \fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the
 250 Pascal Ord() function.  It returns the Tcl_UniChar represented at the
 251 specified character (not byte) \fIindex\fR in the UTF-8 string
 252 \fIsrc\fR.  The source string must contain at least \fIindex\fR
 253 characters.  Behavior is undefined if a negative \fIindex\fR is given.
 254 .PP
 255 \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not
 256 byte) \fIindex\fR in the UTF-8 string \fIsrc\fR.  The source string must
 257 contain at least \fIindex\fR characters.  This is equivalent to calling
 258 \fBTcl_UtfToUniChar\fR \fIindex\fR times.  If a negative \fIindex\fR is given,
 259 the return pointer points to the first character in the source string.
 260 .PP
 261 \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl
 262 commands.  It parses a backslash sequence and stores the properly formed
 263 UTF-8 character represented by the backslash sequence in the output
 264 buffer \fIdst\fR.  At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
 265 \fBTcl_UtfBackslash\fR modifies \fI*readPtr\fR to contain the number
 266 of bytes in the backslash sequence, including the backslash character.
 267 The return value is the number of bytes stored in the output buffer.
 268 .PP
 269 See the \fBTcl\fR manual entry for information on the valid backslash
 270 sequences.  All of the sequences described in the Tcl manual entry are
 271 supported by \fBTcl_UtfBackslash\fR.
 272
 273 .SH KEYWORDS
 274 utf, unicode, backslash