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

### 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_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace — リストとしての Tcl 変数を扱う manipulate Tcl values as lists
  SYNOPSIS
    #include <tcl.h>
    int
    Tcl_ListObjAppendList(interp, listPtr, elemListPtr)
    int
    Tcl_ListObjAppendElement(interp, listPtr, objPtr)
    Tcl_Obj *
    Tcl_NewListObj(objc, objv)
    Tcl_SetListObj(objPtr, objc, objv)
    int
    Tcl_ListObjGetElements(interp, listPtr, objcPtr, objvPtr)
    int
    Tcl_ListObjLength(interp, listPtr, lengthPtr)
    int
    Tcl_ListObjIndex(interp, listPtr, index, objPtrPtr)
    int
    Tcl_ListObjReplace(interp, listPtr, first, count, objc, objv)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    Tcl_Obj *listPtr (入出力in/out)
    Tcl_Obj *elemListPtr (入出力in/out)
    Tcl_Obj *objPtr (入力in)
    int *objcPtr (入力in)
    Tcl_Obj ***objvPtr (出力out)
    int objc (入力in)
    Tcl_Obj *const objv[] (入力in)
    int *lengthPtr (out)
    int index (入力in)
    Tcl_Obj **objPtrPtr (出力out)
    int first (入力in)
    int count (入力in)
  説明 DESCRIPTION
  SEE ALSO
  KEYWORDS

### NAME

Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace — リストとしての Tcl 変数を扱う manipulate Tcl values as lists

### SYNOPSIS

#include <tcl.h>
int
Tcl_ListObjAppendList(interp, listPtr, elemListPtr)
int
Tcl_ListObjAppendElement(interp, listPtr, objPtr)
Tcl_Obj *
Tcl_NewListObj(objc, objv)
Tcl_SetListObj(objPtr, objc, objv)
int
Tcl_ListObjGetElements(interp, listPtr, objcPtr, objvPtr)
int
Tcl_ListObjLength(interp, listPtr, lengthPtr)
int
Tcl_ListObjIndex(interp, listPtr, index, objPtrPtr)
int
Tcl_ListObjReplace(interp, listPtr, first, count, objc, objv)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  値からリスト値への変換中に不都合が生じた場合､解釈実行機能が NULL でない限り､不都合伝言文が解釈実行機能の結果の値に残される｡　 If an error occurs while converting a value to be a list value, an error message is left in the interpreter's result value unless interp is NULL.

Tcl_Obj *listPtr (入出力in/out)
  操作されるべきリスト値を指す｡もし listPtr が未だリスト値を指していない場合､その様に変換させようと試みる｡　 Points to the list value to be manipulated. If listPtr does not already point to a list value, an attempt will be made to convert it to one.

Tcl_Obj *elemListPtr (入出力in/out)
  Tcl_ListObjAppendList については､これは listPtr に追記されるべき要素を含んでいるリスト値を指す｡ *elemListPtr のそれぞれの要素は listPtr の新しい要素になる｡もし *elemListPtr が NULL でなく､且つ未だリスト値を指していない場合､その様に変換させようと試みる｡ 　　 For Tcl_ListObjAppendList, this points to a list value containing elements to be appended onto listPtr. Each element of *elemListPtr will become a new element of listPtr. If *elemListPtr is not NULL and does not already point to a list value, an attempt will be made to convert it to one.

Tcl_Obj *objPtr (入力in)
  Tcl_ListObjAppendElement については､これは listPtr に追記されるべき Tcl 値を含んでいるリスト値を指す｡ Tcl_SetListObj については､これは､ objv に参照されている配列の objc 要素を含むリスト値に変換されるべき Tcl 値を指す｡ 　　　 For Tcl_ListObjAppendElement, points to the Tcl value that will be appended to listPtr. For Tcl_SetListObj, this points to the Tcl value that will be converted to a list value containing the objc elements of the array referenced by objv.

int *objcPtr (入力in)
  listPtr 内の要素値の数を保存する Tcl_ListObjGetElements の場所を指す｡　 　 Points to location where Tcl_ListObjGetElements stores the number of element values in listPtr.

Tcl_Obj ***objvPtr (出力out)
  listPtr 内の要素値への指示子の配列の指示子を保存する Tcl_ListObjGetElements の場所｡ 　　　 A location where Tcl_ListObjGetElements stores a pointer to an array of pointers to the element values of listPtr.

int objc (入力in)
  Tcl_NewListObj が新しいリスト値に挿入する､及び､ Tcl_ListObjReplace が listPtr に挿入する Tcl 値の個数｡Tcl_SetListObj については､ objPtr に挿入する Tcl 値の個数｡　 　　 The number of Tcl values that Tcl_NewListObj will insert into a new list value, and Tcl_ListObjReplace will insert into listPtr. For Tcl_SetListObj, the number of Tcl values to insert into objPtr.

Tcl_Obj *const objv[] (入力in)
  値への指示子の配列｡Tcl_NewListObj はこれらの値を新しいリスト値に挿入し､Tcl_ListObjReplace はそれらを既存の listPtr に挿入する｡各々の値は隔てられたリスト要素になる｡　 　　　 An array of pointers to values. Tcl_NewListObj will insert these values into a new list value and Tcl_ListObjReplace will insert them into an existing listPtr. Each value will become a separate list element.

int *lengthPtr (out)
  Tcl_ListObjLength がリストの長さを保存する場所を指す｡　 Points to location where Tcl_ListObjLength stores the length of the list.

int index (入力in)
  Tcl_ListObjIndex が返すリスト要素の番号｡最初の要素は番号 0 を有す｡　 Index of the list element that Tcl_ListObjIndex is to return. The first element has index 0.

Tcl_Obj **objPtrPtr (出力out)
  Tcl_ListObjIndex が結果のリスト要素値への指示子を保存する場所を指す｡　 　　 Points to place where Tcl_ListObjIndex is to store a pointer to the resulting list element value.

int first (入力in)
  Tcl_ListObjReplace が置換すべきリスト要素の開始番号｡リストの最初の要素が番号 0 を有す｡　 　　 Index of the starting list element that Tcl_ListObjReplace is to replace. The list's first element has index 0.

int count (入力in)
  Tcl_ListObjReplace が置換すべき要素の個数｡　 　　 The number of elements that Tcl_ListObjReplace is to replace..BE

### 説明 DESCRIPTION

Tcl リスト値は効果的な索引と追記を支援している内部表現を有する｡この取扱説明書の頁に記述された手続函数は C 符号命令から Tcl リスト値を生成､修正､索引､追記する為に使用される｡ 　　　 Tcl list values have an internal representation that supports the efficient indexing and appending. The procedures described in this man page are used to create, modify, index, and append to Tcl list values from C code.

Tcl_ListObjAppendList と Tcl_ListObjAppendElement は両方とも､ listPtr によって参照されたリスト値の末尾に一つ或はそれ以上の値を追加する｡ Tcl_ListObjAppendList は elemListPtr によって参照されるリスト値のそれぞれの要素に追記する､又 Tcl_ListObjAppendElement は objPtr に参照される一つの値を追記する｡両方の手続函数とも必要なら listPtr により参照される値を変換する｡もし変換中に不都合が生じると､両方の手続函数は TCL_ERROR を返し､もし解釈実行機能が NULL でなければ解釈実行機能の結果の中に不都合伝言文を残す｡同様に､もし elemListPtr がリスト値を未だ参照していない場合､ Tcl_ListObjAppendList はそれの変換を試み､変換中に不都合が生じると TCL_ERROR を返し､もし解釈実行機能が NULL でなければ解釈実行機能の結果の中に不都合伝言文を残す｡両方の手続函数は､どの listPtr を表現する古い文字列表現も無効にし､リスト値に変換された場合はどの古い内部表現も解放する｡同様に､ Tcl_ListObjAppendList も､もしそれがリスト値に変換されると elemListPtr の古い内部表現を解放する｡ elemListPtr 内のそれぞれの要素に追記した後､ Tcl_ListObjAppendList は要素の参照個数を増加する､理由は listPtr は今それを参照しているから｡同じ理由で Tcl_ListObjAppendElement は objPtr の参照個数を増加する｡もし不都合が生じない場合､二つの手続函数は値を追記した後 TCL_OK を返す｡ Tcl_ListObjAppendList and Tcl_ListObjAppendElement both add one or more values to the end of the list value referenced by listPtr. Tcl_ListObjAppendList appends each element of the list value referenced by elemListPtr while Tcl_ListObjAppendElement appends the single value referenced by objPtr. Both procedures will convert the value referenced by listPtr to a list value if necessary. If an error occurs during conversion, both procedures return TCL_ERROR and leave an error message in the interpreter's result value if interp is not NULL. Similarly, if elemListPtr does not already refer to a list value, Tcl_ListObjAppendList will attempt to convert it to one and if an error occurs during conversion, will return TCL_ERROR and leave an error message in the interpreter's result value if interp is not NULL. Both procedures invalidate any old string representation of listPtr and, if it was converted to a list value, free any old internal representation. Similarly, Tcl_ListObjAppendList frees any old internal representation of elemListPtr if it converts it to a list value. After appending each element in elemListPtr, Tcl_ListObjAppendList increments the element's reference count since listPtr now also refers to it. For the same reason, Tcl_ListObjAppendElement increments objPtr's reference count. If no error occurs, the two procedures return TCL_OK after appending the values.

Tcl_NewListObj と Tcl_SetListObj は､それぞれの要素が Tcl 値を指し示す objv によって参照される配列の objc 要素を保持する為に､新しい値を創製するか既存の値を修正する｡もし objc が零と同じかより小さい場合､両者は空値を返す｡もし objv が NULL であると結果のリストは 0 の要素を含み､ objc の更なる要素に関する内部表現の為の予約域を伴う(後々の再割当てを避ける為)｡新しい値の文字列の表現は不適正のまま残される｡この二つの手続き函数は､objc 内の要素の参照個数を､今参照しているリスト値から､増加する｡Tcl_NewListObj から返される新しいリスト値は参照個数零を有する｡ Tcl_NewListObj and Tcl_SetListObj create a new value or modify an existing value to hold the objc elements of the array referenced by objv where each element is a pointer to a Tcl value. If objc is less than or equal to zero, they return an empty value. If objv is NULL, the resulting list contains 0 elements, with reserved space in an internal representation for objc more elements (to avoid its reallocation later). The new value's string representation is left invalid. The two procedures increment the reference counts of the elements in objc since the list value now refers to them. The new list value returned by Tcl_NewListObj has reference count zero.

Tcl_ListObjGetElements はリスト値内の要素の配列の個数とポインターを返す｡それは番地 objcPtr 内に保存することにより個数を返す｡同様に､それは番地 objvPtr 内に保存することににより配列ポインターを返す｡番地指定の記憶域は Tcl により管理され､呼び出し側に解放も書かれもしない｡もしリストが空の場合､ 0 が objcPtr の箇所に､ NULL が objvPtr に保存される｡もし listPtr が未だリスト値でない場合､Tcl_ListObjGetElements がそれへの変換を試みる; 変換が失敗すると TCL_ERROR を返し､もし解釈実行機能 interp が NULL でなければ解釈実行機能の結果の中に不都合伝言文を残す｡そうでない場合個数と配列ポインターを保存した後に TCL_OK を返す｡ Tcl_ListObjGetElements returns a count and a pointer to an array of the elements in a list value. It returns the count by storing it in the address objcPtr. Similarly, it returns the array pointer by storing it in the address objvPtr. The memory pointed to is managed by Tcl and should not be freed or written to by the caller. If the list is empty, 0 is stored at objcPtr and NULL at objvPtr. If listPtr is not already a list value, Tcl_ListObjGetElements will attempt to convert it to one; if the conversion fails, it returns TCL_ERROR and leaves an error message in the interpreter's result value if interp is not NULL. Otherwise it returns TCL_OK after storing the count and array pointer.

Tcl_ListObjLength は listPtr によって参照されるリスト値内の要素の数を返す｡それは､番地 lengthPtr 内に整数を保存することによってこの個数を返す｡もし値が未だリスト値でない場合､ Tcl_ListObjLength はそれへの変換を試みる; もし変換が失敗すると TCL_ERROR を返し､もし interp が NULL でなければ解釈実行機能の結 値の中に不都合伝言文を残す｡そうでなければ リストの長さを保存した後 TCL_OK を返す｡ Tcl_ListObjLength returns the number of elements in the list value referenced by listPtr. It returns this count by storing an integer in the address lengthPtr. If the value is not already a list value, Tcl_ListObjLength will attempt to convert it to one; if the conversion fails, it returns TCL_ERROR and leaves an error message in the interpreter's result value if interp is not NULL. Otherwise it returns TCL_OK after storing the list's length.

手続函数 Tcl_ListObjIndex は listPtr によって参照されるリスト内の index 番目の要素の値へのポインターを返す｡それはこの値を指すポインターを番地 objPtrPtr に保存して返す｡もし listPtr が未だリスト値を参照しない場合､ Tcl_ListObjIndex はそれへの変換を試みる; もし変換が失敗すると TCL_ERROR を返し､もし解釈実行機能が NULL でなければ解釈実行機能の結果の中に不都合伝言文を残す｡もし索引が範囲を逸脱している場合､即ち､ index が負か､リスト内の要素の数以上かの場合 Tcl_ListObjIndex は objPtrPtr 内に NULL を保存し TCL_OK を返す｡それ以外の場合､要素の値のポインターを保存した後に TCL_OK を返す｡リスト要素への参照個数は増加されない; 呼出側は要素へのポインターを保有する必要があればそうしなければならない｡ 　　　 The procedure Tcl_ListObjIndex returns a pointer to the value at element index in the list referenced by listPtr. It returns this value by storing a pointer to it in the address objPtrPtr. If listPtr does not already refer to a list value, Tcl_ListObjIndex will attempt to convert it to one; if the conversion fails, it returns TCL_ERROR and leaves an error message in the interpreter's result value if interp is not NULL. If the index is out of range, that is, index is negative or greater than or equal to the number of elements in the list, Tcl_ListObjIndex stores a NULL in objPtrPtr and returns TCL_OK. Otherwise it returns TCL_OK after storing the element's value pointer. The reference count for the list element is not incremented; the caller must do that if it needs to retain a pointer to the element.

Tcl_ListObjReplace は listPtr によって参照されるリストの要素の零或はそれ以上の要素を objv によって参照される配列内の objc の値と置換える｡もし listPtr がリスト値を指していない場合､Tcl_ListObjReplace はそれへの変換を試みる; もし変換が失敗すると TCL_ERROR を返し､もし解釈実行機能が NULL でなければ解釈実行機能の結果の中に不都合伝言文を残す｡それ以外の場合､値を置換えた後に TCL_OK を返す｡もし objv が NULL の場合､新しい要素は加えられない｡引数 first が負か零の場合､それは最初の要素を参照する｡もしリスト内の要素の数と等しいかそれより大きい場合､どの要素も削除されない; 新しい要素はリストに追記される｡ count は置換えるべき要素の数を与える｡もし count が零か負の場合どの要素も削除されない; 新しい要素は単に first により指定されたものの前に挿入される｡ Tcl_ListObjReplace は listPtr の古い文字列表現を無効にする｡ objv からのどの要素への参照個数も､今それを参照している結果のリストから増加する｡同様にどの置換した値の参照個数も減少される｡ Tcl_ListObjReplace replaces zero or more elements of the list referenced by listPtr with the objc values in the array referenced by objv. If listPtr does not point to a list value, Tcl_ListObjReplace will attempt to convert it to one; if the conversion fails, it returns TCL_ERROR and leaves an error message in the interpreter's result value if interp is not NULL. Otherwise, it returns TCL_OK after replacing the values. If objv is NULL, no new elements are added. If the argument first is zero or negative, it refers to the first element. If first is greater than or equal to the number of elements in the list, then no elements are deleted; the new elements are appended to the list. count gives the number of elements to replace. If count is zero or negative then no elements are deleted; the new elements are simply inserted before the one designated by first. Tcl_ListObjReplace invalidates listPtr's old string representation. The reference counts of any elements inserted from objv are incremented since the resulting list now refers to them. Similarly, the reference counts for any replaced values are decremented.

Tcl_ListObjReplace は両方の挿入､削除要素を組合せるので､リスト操作の数の実装に使うことができる｡譬えば､次の符号命令はポインター値 objv の配列によって参照される objc 値を listPtr によって参照されるリストの index 番目要素の直前に挿入する: 　　　　 Because Tcl_ListObjReplace combines both element insertion and deletion, it can be used to implement a number of list operations. For example, the following code inserts the objc values referenced by the array of value pointers objv just before the element index of the list referenced by listPtr:

    result = Tcl_ListObjReplace(interp, listPtr, index, 0,
            objc, objv);

同様に､次の符号命令は配列 objv によって参照される objc 値をリスト listPtr の末尾に追記する: 　　　 Similarly, the following code appends the objc values referenced by the array objv to the end of the list listPtr:

    result = Tcl_ListObjLength(interp, listPtr, &length);
    if (result == TCL_OK) {
        result = Tcl_ListObjReplace(interp, listPtr, length, 0,
                objc, objv);
    }

first で始まる count リスト要素は単に NULL objvPtr を伴う Tcl_ListObjReplace 呼出しで削除可能である: 　　　 The count list elements starting at first can be deleted by simply calling Tcl_ListObjReplace with a NULL objvPtr:

    result = Tcl_ListObjReplace(interp, listPtr, first, count,
            0, NULL);

### SEE ALSO

Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult

### KEYWORDS

append, index, insert, internal representation, length, list, list value, list type, value, value type, replace, string representation
Copyright © 1996-1997 Sun Microsystems, Inc.