## Tcl8.6.17/Tk8.6.17 Documentation > Tcl C API > Utf

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    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 — UTF-8 文字列を取扱う業務譜　 routines for manipulating UTF-8 strings
  SYNOPSIS
    #include <tcl.h>
    typedef ... Tcl_UniChar;
    int
    Tcl_UniCharToUtf(ch, buf)
    int
    Tcl_UtfToUniChar(src, chPtr)
    char *
    Tcl_UniCharToUtfDString(uniStr, uniLength, dsPtr)
    Tcl_UniChar *
    Tcl_UtfToUniCharDString(src, length, dsPtr)
    int
    Tcl_UniCharLen(uniStr)
    int
    Tcl_UniCharNcmp(ucs, uct, numChars)
    int
    Tcl_UniCharNcasecmp(ucs, uct, numChars)
    int
    Tcl_UniCharCaseMatch(uniStr, uniPattern, nocase)
    int
    Tcl_UtfNcmp(cs, ct, numChars)
    int
    Tcl_UtfNcasecmp(cs, ct, numChars)
    int
    Tcl_UtfCharComplete(src, length)
    int
    Tcl_NumUtfChars(src, length)
    const char *
    Tcl_UtfFindFirst(src, ch)
    const char *
    Tcl_UtfFindLast(src, ch)
    const char *
    Tcl_UtfNext(src)
    const char *
    Tcl_UtfPrev(src, start)
    Tcl_UniChar
    Tcl_UniCharAtIndex(src, index)
    const char *
    Tcl_UtfAtIndex(src, index)
    int
    Tcl_UtfBackslash(src, readPtr, dst)
  引数 ARGUMENTS
    char *buf (出力out)
    int ch (in)
    Tcl_UniChar *chPtr (出力out)
    const char *src (入力in)
    const char *cs (入力in)
    const char *ct (入力in)
    const Tcl_UniChar *uniStr (入力in)
    const Tcl_UniChar *ucs (入力in)
    const Tcl_UniChar *uct (入力in)
    const Tcl_UniChar *uniPattern (入力in)
    int length (入力in)
    int uniLength (入力in)
    Tcl_DString *dsPtr (入出力in/out)
    unsigned long numChars (入力in)
    const char *start (入力in)
    int index (入力in)
    int *readPtr (出力out)
    char *dst (出力out)
    int nocase (入力in)
  説明 DESCRIPTION
  KEYWORDS

### NAME

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 — UTF-8 文字列を取扱う業務譜　 routines for manipulating UTF-8 strings

### SYNOPSIS

#include <tcl.h>
typedef ... Tcl_UniChar;
int
Tcl_UniCharToUtf(ch, buf)
int
Tcl_UtfToUniChar(src, chPtr)
char *
Tcl_UniCharToUtfDString(uniStr, uniLength, dsPtr)
Tcl_UniChar *
Tcl_UtfToUniCharDString(src, length, dsPtr)
int
Tcl_UniCharLen(uniStr)
int
Tcl_UniCharNcmp(ucs, uct, numChars)
int
Tcl_UniCharNcasecmp(ucs, uct, numChars)
int
Tcl_UniCharCaseMatch(uniStr, uniPattern, nocase)
int
Tcl_UtfNcmp(cs, ct, numChars)
int
Tcl_UtfNcasecmp(cs, ct, numChars)
int
Tcl_UtfCharComplete(src, length)
int
Tcl_NumUtfChars(src, length)
const char *
Tcl_UtfFindFirst(src, ch)
const char *
Tcl_UtfFindLast(src, ch)
const char *
Tcl_UtfNext(src)
const char *
Tcl_UtfPrev(src, start)
Tcl_UniChar
Tcl_UniCharAtIndex(src, index)
const char *
Tcl_UtfAtIndex(src, index)
int
Tcl_UtfBackslash(src, readPtr, dst)

### 引数 ARGUMENTS

char *buf (出力out)
  Tcl_UniChar の UTF-8 表現がその中に保存されている緩衝域｡最大では TCL_UTF_MAX バイトが緩衝域に保存されている｡　　　 Buffer in which the UTF-8 representation of the Tcl_UniChar is stored. At most TCL_UTF_MAX bytes are stored in the buffer.

int ch (in)
  変換又は調査対象のユニコード文字｡　　　 The Unicode character to be converted or examined.

Tcl_UniChar *chPtr (出力out)
  UTF-8 文字列の冒頭部による表現のTcl_UniChar で充たされている｡　 　 Filled with the Tcl_UniChar represented by the head of the UTF-8 string.

const char *src (入力in)
  UTF-8 文字列への指示子｡　 Pointer to a UTF-8 string.

const char *cs (入力in)
  UTF-8 文字列への指示子｡　 Pointer to a UTF-8 string.

const char *ct (入力in)
  UTF-8 文字列への指示子｡　 Pointer to a UTF-8 string.

const Tcl_UniChar *uniStr (入力in)
  零終端のユニコード文字列｡　 A null-terminated Unicode string.

const Tcl_UniChar *ucs (入力in)
  零終端のユニコード文字列｡　 A null-terminated Unicode string.

const Tcl_UniChar *uct (入力in)
  零終端のユニコード文字列｡　 A null-terminated Unicode string.

const Tcl_UniChar *uniPattern (入力in)
  零終端のユニコード文字列｡　 A null-terminated Unicode string.

int length (入力in)
  バイト単位の UTF-8 文字列の長さ(UTF-8 文字ではない)｡もし負数の場合､最初のヌルバイト迄の全てのバイトが使用される｡ 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.

int uniLength (入力in)
  ユニコード文字列の文字単位の長さ｡ 0 かそれ以上でなければならない｡　 The length of the Unicode string in characters. Must be greater than or equal to 0.

Tcl_DString *dsPtr (入出力in/out)
  事前に初期化された Tcl_DString への指示子｡　 A pointer to a previously initialized Tcl_DString.

unsigned long numChars (入力in)
  比較すべき文字の個数｡　 The number of characters to compare.

const char *start (入力in)
  UTF-8 文字列の先頭への指示子｡　 Pointer to the beginning of a UTF-8 string.

int index (入力in)
  UTF-8 文字列内の文字(バイトではなく)の索引｡　 The index of a character (not byte) in the UTF-8 string.

int *readPtr (出力out)
  もし非-NULL なら逆斜線の並びの中の逆斜線文字も含めた､バイトの個数で充たされる｡　 If non-NULL, filled with the number of bytes in the backslash sequence, including the backslash character.

char *dst (出力out)
  逆斜線並びにより表現されたバイトがその中に保存される緩衝域｡緩衝域に最大 TCL_UTF_MAX バイトが保存される｡　 Buffer in which the bytes represented by the backslash sequence are stored. At most TCL_UTF_MAX bytes are stored in the buffer.

int nocase (入力in)
  合致が大文字小文字を考慮する (0) か､又は無視する (1) か､のどちらでなされるべきかを指定する｡　　 Specifies whether the match should be done case-sensitive (0) or case-insensitive (1).

### 説明 DESCRIPTION

これ等の業務譜は UTF-8 文字列と Tcl_UniChar の間を変換する｡ Tcl_UniChar はユニコード文字を符号無し､固定長の量として表す｡UTF-8 文字は最大長さが TCL_UTF_MAX の可変長バイト列として表わされるユニコード文字である｡多バイト UTF-8 列は先頭バイトに幾つかの従属バイトが続いて構成される｡ These routines convert between UTF-8 strings and Tcl_UniChars. A Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size quantity. A UTF-8 character is a Unicode character represented as a varying-length sequence of up to TCL_UTF_MAX bytes. A multibyte UTF-8 sequence consists of a lead byte followed by some number of trail bytes.

TCL_UTF_MAX は UTF-8 表現の一つのユニコード文字が使う最大バイト個数である｡ TCL_UTF_MAX is the maximum number of bytes that it takes to represent one Unicode character in the UTF-8 representation.

Tcl_UniCharToUtf は Tcl_UniChar ch を buf から始まるUTF-8 文字列として保存する｡返り値は buf に保存されたバイト数｡ Tcl_UniCharToUtf stores the Tcl_UniChar ch as a UTF-8 string in starting at buf. The return value is the number of bytes stored in buf.

Tcl_UtfToUniChar は src から始まる一つの UTF-8 文字を読み *chPtr に Tcl_UniChar として保存する｡返り値は src から読み出したバイトの数である｡ 呼出し側は､源の緩衝域が十分に長いことを確認し､この処理が末尾を駆け抜け非存在や不規則記憶を参照する事がない様にしなければならない; もし源緩衝域が零終端になっていることが判っている場合このようなことは起らない｡もし入力が適切な UTF-8 書式ではない場合､Tcl_UtfToUniChar は src の第１バイトを *chPtr に 0x80 から 0xFF の間のTcl_UniChar として保存し 1 を返す｡ Tcl_UtfToUniChar reads one UTF-8 character starting at src and stores it as a Tcl_UniChar in *chPtr. The return value is the number of bytes read from src. The caller must ensure that the source buffer is long enough such that this routine does not run off the end and dereference non-existent or random memory; if the source buffer is known to be null-terminated, this will not happen. If the input is not in proper UTF-8 format, Tcl_UtfToUniChar will store the first byte of src in *chPtr as a Tcl_UniChar between 0x80 and 0xFF and return 1.

Tcl_UniCharToUtfDString は与えられたユニコード文字列を UTF-8 に変換し結果を予め初期化された Tcl_DString に保存する｡使用者は､与えられたユニコード文字列の長さ uniLength を指定せねばならない｡返り値はユニコード文字列の UTF-8 表現へのポインタの値である｡返り値の為の保管域は Tcl_DString の末尾に追記される｡ Tcl_UniCharToUtfDString converts the given Unicode string to UTF-8, storing the result in a previously initialized Tcl_DString. You must specify uniLength, 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 Tcl_DString.

Tcl_UtfToUniCharDString は与えられた UTF-8 文字列をユニコードに変換し､結果を予め初期化された Tcl_DString に保存する｡引数 length 内に､与えられた UTF-8 文字列の長さをバイト単位か､又は “-1” の孰れかで指定する､後者の場合 Tcl_UtfToUniCharDString は長さを計算する為に strlen を使う｡戻り値は UTF-8 文字列のユニコード表現へのポインタの値である｡返り値の為の保管域は Tcl_DString の末尾に追記される｡ユニコード文字列はユニコードの零文字を伴って終る｡ Tcl_UtfToUniCharDString converts the given UTF-8 string to Unicode, storing the result in the previously initialized Tcl_DString. In the argument length, you may either specify the length of the given UTF-8 string in bytes or “-1”, in which case Tcl_UtfToUniCharDString uses strlen 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 Tcl_DString. The Unicode string is terminated with a Unicode null character.

Tcl_UniCharLen はユニコード文字の為の strlen に相当する｡それは零終端のユニード文字列を受取り､文字列内の文字数(バイト数ではなく)を返す｡ Tcl_UniCharLen corresponds to strlen for Unicode characters. It accepts a null-terminated Unicode string and returns the number of Unicode characters (not bytes) in that string.

Tcl_UniCharNcmp と Tcl_UniCharNcasecmp はユニコード文字に関して､ strncmp と strncasecmp にそれぞれ相当する｡それらは二つの零終端のユニコード文字列と比較すべき文字数を受取る｡両方の文字列共に最低限 numChars 文字長さを有すると仮定される｡Tcl_UniCharNcmp は二つの文字列を一文字づつユニコード文字の順位を比較する｡第１の文字列が第２の文字列に較べ大きいか等しいか小さい場合､それぞれ､零より大きいか等しいか小さい整数を返す｡Tcl_UniCharNcasecmp はユニコードの大文字小文字を区別しない版である｡ Tcl_UniCharNcmp and Tcl_UniCharNcasecmp correspond to strncmp and strncasecmp, respectively, for Unicode characters. They accept two null-terminated Unicode strings and the number of characters to compare. Both strings are assumed to be at least numChars characters long. Tcl_UniCharNcmp 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. Tcl_UniCharNcasecmp is the Unicode case insensitive version.

Tcl_UniCharCaseMatch は Tcl_StringCaseMatch に同一のユニコード版である｡零終端のユニコード文字列と､ユニコード紋様と､大文字小文字を区別するか否かを指定する論理値を受取り､文字列が紋様に合致するか否かを返す｡ Tcl_UniCharCaseMatch is the Unicode equivalent to Tcl_StringCaseMatch. It accepts a null-terminated Unicode string, a Unicode pattern, and a boolean value specifying whether the match should be case sensitive and returns whether the string matches the pattern.

Tcl_UtfNcmp は UTF-8 文字列の為の strncmp に相当する｡二つの零終端の UTF-8 文字列と比較すべき文字の数を受取る｡(両方の文字列は少なくとも numChars 文字長さ以上と仮定される｡) Tcl_UtfNcmp は二つの文字列を一文字づつユニコード文字の順位を比較する｡もし第１文字列が第２文字列より大きい､等しい､小さい場合､それぞれ 0 より大きい､等しい､小さい整数を返す｡ Tcl_UtfNcmp corresponds to strncmp for UTF-8 strings. It accepts two null-terminated UTF-8 strings and the number of characters to compare. (Both strings are assumed to be at least numChars characters long.) Tcl_UtfNcmp 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.

Tcl_UtfNcasecmp は UTF-8 文字列の為の strncasecmp に相当する｡比較の時に大文字小文字､或は表題文字を区別しないことを除き Tcl_UtfNcmp と似ている｡ Tcl_UtfNcasecmp corresponds to strncasecmp for UTF-8 strings. It is similar to Tcl_UtfNcmp except comparisons ignore differences in case when comparing upper, lower or title case characters.

Tcl_UtfCharComplete は長さ length バイトの源の UTF-8 文字列 src がTcl_UtfToUniChar/Tcl_UtfNext によって符号化されたものに足るだけ長いと 1 を､そうでないと 0 を返す｡この函数は UTF-8 文字列が適切に形成されることは保障されない｡この函数はその時に バイト上で操作が行われ､全 Tcl_UniChar が見えるか否かを知る必要がある手続函数で使用される｡ Tcl_UtfCharComplete returns 1 if the source UTF-8 string src of length bytes is long enough to be decoded by Tcl_UtfToUniChar/Tcl_UtfNext, or 0 otherwise. This function does not guarantee that the UTF-8 string is properly formed. This routine is used by procedures that are operating on a byte at a time and need to know if a full Tcl_UniChar has been seen.

Tcl_NumUtfChars は UTF-8 文字列の為の strlen に相当する｡UTF-8 で表現された文字列 src の長さを返す｡源の文字列の長さは length バイトである｡もし長さが負数である場合､最初の零バイト迄の全てのバイトが使用される｡ Tcl_NumUtfChars corresponds to strlen for UTF-8 strings. It returns the number of Tcl_UniChars that are represented by the UTF-8 string src. The length of the source string is length bytes. If the length is negative, all bytes up to the first null byte are used.

Tcl_UtfFindFirst は UTF-8 文字列の為の strchr に相当する｡零終端 UTF-8 文字列 src 内の最初の Tcl_UniChar 文字 ch が占めるポインタを返す｡零終端は UTF-8 文字列の一部と看做される｡ Tcl_UtfFindFirst corresponds to strchr for UTF-8 strings. It returns a pointer to the first occurrence of the Tcl_UniChar ch in the null-terminated UTF-8 string src. The null terminator is considered part of the UTF-8 string.

Tcl_UtfFindLast は UTF-8 文字列の為の strrchr に相当する｡零終端 UTF-8 文字列 src 内の最後の Tcl_UniChar 文字 ch が占めるポインタを返す｡零終端は UTF-8 文字列の一部と看做される｡ Tcl_UtfFindLast corresponds to strrchr for UTF-8 strings. It returns a pointer to the last occurrence of the Tcl_UniChar ch in the null-terminated UTF-8 string src. The null terminator is considered part of the UTF-8 string.

UTF-8 文字列内のある位置へのポインタ src が与えられ Tcl_UtfNext は､文字列内の次の UTF-8 文字へのポインタを返す｡もし､文字列が零文字で終っていない場合は､呼出し側は､文字列の最後の文字の次の文字を要求してはならない｡その様な場合､ Tcl_UtfNext を呼出す前に､充分なバイトが利用可能であることを確認する為に Tcl_UtfCharComplete が使用できる｡ Given src, a pointer to some location in a UTF-8 string, Tcl_UtfNext returns a pointer to the next UTF-8 character in the string. The caller must not ask for the next character after the last character in the string if the string is not terminated by a null character. Tcl_UtfCharComplete can be used in that case to make sure enough bytes are available before calling Tcl_UtfNext.

Tcl_UtfPrev は逆向きへの進行に使われるが､ start 位置から始まる UTF-8 文字列を越える事はない｡もし､ UTF-8 文字列が完全に作成され､且つ完全な形式の文字であり且つ､ src がこれ等の文字の内の一つの先頭バイト(又は､文字列の末尾を１バイト超えた位置)を指す場合､ Tcl_UtfPrev への呼出しの繰返しは文字列内のそれぞれの文字の先頭バイトへのポインタを一度に一つの文字づつ返すことになり､ start 位置に至ると終了する｡ Tcl_UtfPrev is used to step backward through but not beyond the UTF-8 string that begins at start. If the UTF-8 string is made up entirely of complete and well-formed characters, and src points to the lead byte of one of those characters (or to the location one byte past the end of the string), then repeated calls of Tcl_UtfPrev will return pointers to the lead bytes of each character in the string, one character at a time, terminating when it returns start.

状態が完了であって且つ出来栄えが満足でない時は､ Tcl_UtfPrev の更なる正確な記述が必要である｡それは常に､ start と同じかより大きいポインターを返す; 即ち､常に文字列内の位置へのポインタである｡文字への走査が start から始まる時､常に文字が始まるバイトへのポインタを返す｡ src が start より大きい時､それは､ src より小さく､且つ (src - TCL_UTF_MAX) より大きいか等しいポインタを返す｡返されたポインターで始まる文字は最初のものであって､それは src[-1] バイトを含むか､右末尾が src にあるか大きい場合はそれを含むかもしれない｡Tcl_UtfPrev は src[0] バイトも start[-1] バイトも src[-TCL_UTF_MAX-1] も読むことはない｡ When the conditions of completeness and well-formedness may not be satisfied, a more precise description of the function of Tcl_UtfPrev is necessary. It always returns a pointer greater than or equal to start; that is, always a pointer to a location in the string. It always returns a pointer to a byte that begins a character when scanning for characters beginning from start. When src is greater than start, it always returns a pointer less than src and greater than or equal to (src - TCL_UTF_MAX). The character that begins at the returned pointer is the first one that either includes the byte src[-1], or might include it if the right trail bytes are present at src and greater. Tcl_UtfPrev never reads the byte src[0] nor the byte start[-1] nor the byte src[-TCL_UTF_MAX-1].

Tcl_UniCharAtIndex は､ C 言語の文字配列の間接参照またはパスカル言語の Ord() 函数に相当する｡それは UTF-8 文字列 src 内の index の文字(バイトではない) で指定された位置の Tcl_UniChar 表現を返す｡源文字列は少なくとも index 個の文字を含んでいなければならない｡もし index が負数の場合､挙動は定義されていない｡ Tcl_UniCharAtIndex corresponds to a C string array dereference or the Pascal Ord() function. It returns the Tcl_UniChar represented at the specified character (not byte) index in the UTF-8 string src. The source string must contain at least index characters. Behavior is undefined if a negative index is given.

Tcl_UtfAtIndex は UTF-8 文字列 src 内の指定された文字(バイトではない) index へのポインタを返す｡源文字列は少なくとも index 個の文字を含んでいなければならない｡これは､Tcl_UtfToUniChar の index 回呼出しと等価である｡｡もし負の index が与えられた場合､返されるポインタは源文字列の最初の文字を指す｡ Tcl_UtfAtIndex returns a pointer to the specified character (not byte) index in the UTF-8 string src. The source string must contain at least index characters. This is equivalent to calling Tcl_UtfToUniChar index times. If a negative index is given, the return pointer points to the first character in the source string.

Tcl_UtfBackslash は､幾つかの Tcl 命令に使用される便益手続函数である｡それは逆斜線の文字並びを構文解析し､逆斜線の文字並びによって表現される適切な形式の UTF-8 文字列を出力緩衝域 dst に保存する｡最大 TCL_UTF_MAX バイトが緩衝域内に保存される｡ Tcl_UtfBackslash は､逆斜線文字を含む逆斜線並び内のバイト個数を含む *readPtr を修正する｡返る値は出力緩衝域に保存されたバイト個数である｡ Tcl_UtfBackslash is a utility procedure used by several of the Tcl commands. It parses a backslash sequence and stores the properly formed UTF-8 character represented by the backslash sequence in the output buffer dst. At most TCL_UTF_MAX bytes are stored in the buffer. Tcl_UtfBackslash modifies *readPtr to contain the number of bytes in the backslash sequence, including the backslash character. The return value is the number of bytes stored in the output buffer.

Tcl の取扱説明書の適切な逆斜線並びの情報の項目を参照されたい｡ Tcl 取扱説明書の項目内に記述された全ての文字並びは Tcl_UtfBackslash によって運営されている｡ See the Tcl manual entry for information on the valid backslash sequences. All of the sequences described in the Tcl manual entry are supported by Tcl_UtfBackslash.

### KEYWORDS

utf, unicode, backslash
Copyright © 1997 Sun Microsystems, Inc.