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

### 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_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement, Tcl_ScanCountedElement, Tcl_ConvertCountedElement — Tcl リストを操作する　 manipulate Tcl lists
  SYNOPSIS
    #include <tcl.h>
    int
    Tcl_SplitList(interp, list, argcPtr, argvPtr)
    char *
    Tcl_Merge(argc, argv)
    int
    Tcl_ScanElement(src, flagsPtr)
    int
    Tcl_ScanCountedElement(src, length, flagsPtr)
    int
    Tcl_ConvertElement(src, dst, flags)
    int
    Tcl_ConvertCountedElement(src, length, dst, flags)
  引数 ARGUMENTS
    Tcl_Interp *interp (出力out)
    const char *list (入力in)
    int *argcPtr (出力out)
    const char ***argvPtr (出力out)
    int argc (入力in)
    const char *const *argv (入力in)
    const char *src (入力in)
    int *flagsPtr (入力in)
    int length (入力in)
    char *dst (入力in)
    int flags (入力in)
  説明 DESCRIPTION
  SEE ALSO
  KEYWORDS

### NAME

Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement, Tcl_ScanCountedElement, Tcl_ConvertCountedElement — Tcl リストを操作する　 manipulate Tcl lists

### SYNOPSIS

#include <tcl.h>
int
Tcl_SplitList(interp, list, argcPtr, argvPtr)
char *
Tcl_Merge(argc, argv)
int
Tcl_ScanElement(src, flagsPtr)
int
Tcl_ScanCountedElement(src, length, flagsPtr)
int
Tcl_ConvertElement(src, dst, flags)
int
Tcl_ConvertCountedElement(src, length, dst, flags)

### 引数 ARGUMENTS

Tcl_Interp *interp (出力out)
  不都合報告の為に使用する解釈実行機能｡もし NULL なら不都合伝言文を何も残さない｡ Interpreter to use for error reporting. If NULL, then no error message is left.

const char *list (入力in)
  適切な構造を伴う文字列への指示子｡　 Pointer to a string with proper list structure.

int *argcPtr (出力out)
  リスト内の要素の数で満たされる｡　 Filled in with number of elements in list.

const char ***argvPtr (出力out)
  拡張されたリストの要素の文字列への指示子の配列の番地で *argvPtr が充たされる｡ NULL 項目が添付された､配列内の *argcPtr 個の適正な項目がある｡ *argvPtr will be filled in with the address of an array of pointers to the strings that are the extracted elements of list. There will be *argcPtr valid entries in the array, followed by a NULL entry.

int argc (入力in)
  argv 内の要素の数｡　 Number of elements in argv.

const char *const *argv (入力in)
  一つのリストに一緒に併合する文字列の配列｡各文字列は区切られたリストの要素になる｡　 Array of strings to merge together into a single list. Each string will become a separate element of the list.

const char *src (入力in)
  リストの要素になるべき文字列｡　 String that is to become an element of a list.

int *flagsPtr (入力in)
  源譜に関する情報で充たした語への指示子｡ *flagsPtr の値は Tcl_ConvertElement に渡さねばならない｡　 Pointer to word to fill in with information about src. The value of *flagsPtr must be passed to Tcl_ConvertElement.

int length (入力in)
  源譜文字列内のバイトの個数｡　 Number of bytes in string src.

char *dst (入力in)
  変換されたリスト要素を複写する場所｡変換された文字列を保有する為に充分な文字を含んでいなければならない｡　 Place to copy converted list element. Must contain enough characters to hold converted string.

int flags (入力in)
  源譜に関する情報｡Tcl_ScanElementへの事前の予備出しの値でなければならない､TCL_DONT_USE_BRACES との論理和の可能性がある｡　 Information about src. Must be value returned by previous call to Tcl_ScanElement, possibly OR-ed with TCL_DONT_USE_BRACES.

### 説明 DESCRIPTION

これ等の手続函数は､ Tcl リスト逆アセンブルと再アセンブルファイルに使用できる｡ Tcl_SplitList はリストをその構成要素に解体して､ argcPtr と argvPtr を使って要素へのポインターの配列を返す｡引数を抽出している間､Tcl_SplitList は逆斜線置換と波括弧についての通常の規則を得る｡ *argvPtr により指される記憶域は動的に割当てられる; ポインターの配列に加え､全てのリスト要素の複写を保有する｡この記憶域の全ての解除は呼出し側の責務である｡譬えば､次の命令譜を使い Tcl_SplitList を呼んだ場合､: These procedures may be used to disassemble and reassemble Tcl lists. Tcl_SplitList breaks a list up into its constituent elements, returning an array of pointers to the elements using argcPtr and argvPtr. While extracting the arguments, Tcl_SplitList obeys the usual rules for backslash substitutions and braces. The area of memory pointed to by *argvPtr is dynamically allocated; in addition to the array of pointers, it also holds copies of all the list elements. It is the caller's responsibility to free up all of this storage. For example, suppose that you have called Tcl_SplitList with the following code:

    int argc, code;
    char *string;
    char **argv;
    	...
    code = Tcl_SplitList(interp, string, &argc, &argv);

次に最後には次の様に呼び出して記憶域を解除すべきである: Then you should eventually free the storage with a call like the following:

    Tcl_Free((char *) argv);

Tcl_SplitList は通常 TCL_OK を返す､それはリストは成功裏に渡されたことを意味する｡もし､ list 内に構文不具合がある場合､ TCL_ERROR が返され､解釈実行機能の結果は問題点を記述する不都合伝言文を指す(もし解釈実行機能が NULLでなければ)｡もし TCL_ERROR が返されると記憶域は割付されず､ *argvPtr は修正されない｡ Tcl_SplitList normally returns TCL_OK, which means the list was successfully parsed. If there was a syntax error in list, then TCL_ERROR is returned and the interpreter's result will point to an error message describing the problem (if interp was not NULL). If TCL_ERROR is returned then no memory is allocated and *argvPtr is not modified.

Tcl_Merge は Tcl_SplitList の逆である: argc と argv によって与えられた文字列の集まりを取り適切なリスト構造を有する結果を生成する｡これは､元の要素を再度抽出するために index のような命令が使われることを意味する｡更に､もし Tcl_Merge の結果が Tcl_Eval に渡されると､ argc に分解され､その値は Tcl_Merge に渡された argv 文字列と同じになる｡ Tcl_Merge は波括弧と逆斜線を伴うリスト要素を適切な Tcl リスト構造を生成する為に修正する｡その結果の文字列は Tcl_Alloc を使って､動的に割付けられる; 呼出し者は最終的には Tcl_Free を使って空白を解除しなければならない｡ Tcl_Merge is the inverse of Tcl_SplitList: it takes a collection of strings given by argc and argv and generates a result string that has proper list structure. This means that commands like index may be used to extract the original elements again. In addition, if the result of Tcl_Merge is passed to Tcl_Eval, it will be parsed into argc words whose values will be the same as the argv strings passed to Tcl_Merge. Tcl_Merge will modify the list elements with braces and/or backslashes in order to produce proper Tcl list structure. The result string is dynamically allocated using Tcl_Alloc; the caller must eventually release the space using Tcl_Free.

もし Tcl_Merge の結果が Tcl_SplitList に渡されると､ Tcl_SplitList に返された要素は Tcl_Merge に渡されたものと同一になる｡但し､その逆は真ではない: もし Tcl_SplitList が与えられた文字列を渡されると､結果の argc と argv は Tcl_Merge に渡される､結果の文字列は Tcl_SplitList に渡された元の文字列と同じではないかもしれない｡理由は Tcl_Merge は元の文字列とは異なって逆斜線と波括弧を使うかもしれいないから｡ If the result of Tcl_Merge is passed to Tcl_SplitList, the elements returned by Tcl_SplitList will be identical to those passed into Tcl_Merge. However, the converse is not true: if Tcl_SplitList is passed a given string, and the resulting argc and argv are passed to Tcl_Merge, the resulting string may not be the same as the original string passed to Tcl_SplitList. This is because Tcl_Merge may use backslashes and braces differently than the original string.

Tcl_ScanElement と Tcl_ConvertElement は Tcl_Merge の実働の全てを行う手続函数である｡ Tcl_ScanElement はその src 引数を調べ､それをリストの要素に変換する時に逆斜線と波括弧を如何に使うかを定める｡それはリスト要素として src を表現する為に要求された文字並びの数の過大評価を返す､次いで Tcl_ConvertElement.によって必要とされる *flagsPtr 内の情報を保存する｡ Tcl_ScanElement and Tcl_ConvertElement are the procedures that do all of the real work of Tcl_Merge. Tcl_ScanElement scans its src argument and determines how to use backslashes and braces when converting it to a list element. It returns an overestimate of the number of characters required to represent src as a list element, and it stores information in *flagsPtr that is needed by Tcl_ConvertElement.

Tcl_ConvertElement は Tcl_ScanElement の仲間の手続函数である｡それは文字列をリスト要素に変換する実質的な働きを行う｡その flags 引数は Tcl_ScanElement によって返された値と同じである｡ Tcl_ConvertElement は適切なリスト要素を記憶域の *dst の箇所に書き､書いた文字の総数を返す､それは Tcl_ScanElement によって返される結果である｡ Tcl_ConvertElement は実際のリストを先頭と末尾の空白なしに書き出す:隣接したリスト要素の間に空白を含ませることは呼出し側の責務である｡ Tcl_ConvertElement is a companion procedure to Tcl_ScanElement. It does the actual work of converting a string to a list element. Its flags argument must be the same as the value returned by Tcl_ScanElement. Tcl_ConvertElement writes a proper list element to memory starting at *dst and returns a count of the total number of characters written, which will be no more than the result returned by Tcl_ScanElement. Tcl_ConvertElement writes out only the actual list element without any leading or trailing spaces: it is up to the caller to include spaces between adjacent list elements.

Tcl_ConvertElement は src 内の特別の文字を処理する為に二つの異なる接近方法のうちの１つを使う｡それは､可能であれば､波括弧で囲った文字列によって特殊な文字を扱う｡これは見掛けのよい出力を生成するが､ある状況では使用できない､譬えば src が不釣合いの波括弧を含む場合｡この様な状況では Tcl_ConvertElement はそれについて逆斜線並びを生成することにより特殊文字を処理する｡呼出し側は､ Tcl_ScanElement に返された旗印値と TCL_DONT_USE_BRACES との､論理和の結合による第２の接近を強調するかもしれない｡しかし､これは芳しくない結果になる､ Tcl_ConvertElement が､ Tcl 命令の為の引数の部位を生成するために使われる場合の様な特殊な状況では有用である｡この場合､波括弧で囲まれた src は､命令が正しく解析されないことを惹き起こす｡ Tcl_ConvertElement uses one of two different approaches to handle the special characters in src. Wherever possible, it handles special characters by surrounding the string with braces. This produces clean-looking output, but cannot be used in some situations, such as when src contains unmatched braces. In these situations, Tcl_ConvertElement handles special characters by generating backslash sequences for them. The caller may insist on the second approach by OR-ing the flag value returned by Tcl_ScanElement with TCL_DONT_USE_BRACES. Although this will produce an uglier result, it is useful in some special situations, such as when Tcl_ConvertElement is being used to generate a portion of an argument for a Tcl command. In this case, surrounding src with curly braces would cause the command not to be parsed correctly.

無為設定により Tcl_ConvertElement は要素の最初の文字が確実に井桁文字 (“#”) でない様に出力内に引用を使う｡これは eval に渡されたどのリストの最初の要素も注釈の始まりとして誤って渡すことが決してないようにする｡リスト要素がリストの最初の要素ではない場合､引用は必要ではない｡要素がリストの採用の要素でないことが確実に判る時は Tcl_ScanElement に返された旗印値と TCL_DONT_QUOTE_HASH との､論理和の結合により｡先頭の井桁文字の引用をできなくすることが可能である｡ By default, Tcl_ConvertElement will use quoting in its output to be sure the first character of an element is not the hash character (“#”.) This is to be sure the first element of any list passed to eval is not mis-parsed as the beginning of a comment. When a list element is not the first element of a list, this quoting is not necessary. When the caller can be sure that the element is not the first element of a list, it can disable quoting of the leading hash character by OR-ing the flag value returned by Tcl_ScanElement with TCL_DONT_QUOTE_HASH.

Tcl_ScanCountedElement と Tcl_ConvertCountedElement は､ src 文字列の長さが length 引数によって指定されることと､文字列が埋め込まれた零文字を含むかもしれないことを除き Tcl_ScanElement と Tcl_ConvertElement と同じである｡ Tcl_ScanCountedElement and Tcl_ConvertCountedElement are the same as Tcl_ScanElement and Tcl_ConvertElement, except the length of string src is specified by the length argument, and the string may contain embedded nulls.

### SEE ALSO

Tcl_ListObjGetElements

### KEYWORDS

backslash, convert, element, list, merge, split, strings
Copyright © 1989-1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.