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

### 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_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList — 辞書としてのTcl 値を操作する　 manipulate Tcl values as dictionaries
  SYNOPSIS
    #include <tcl.h>
    Tcl_Obj *
    Tcl_NewDictObj()
    int
    Tcl_DictObjGet(interp, dictPtr, keyPtr, valuePtrPtr)
    int
    Tcl_DictObjPut(interp, dictPtr, keyPtr, valuePtr)
    int
    Tcl_DictObjRemove(interp, dictPtr, keyPtr)
    int
    Tcl_DictObjSize(interp, dictPtr, sizePtr)
    int
    Tcl_DictObjFirst(interp, dictPtr, searchPtr,
    keyPtrPtr, valuePtrPtr, donePtr)
    void
    Tcl_DictObjNext(searchPtr, keyPtrPtr, valuePtrPtr, donePtr)
    void
    Tcl_DictObjDone(searchPtr)
    int
    Tcl_DictObjPutKeyList(interp, dictPtr, keyc, keyv, valuePtr)
    int
    Tcl_DictObjRemoveKeyList(interp, dictPtr, keyc, keyv)
  ARGUMENTS
  DESCRIPTION
  用例 EXAMPLE
  SEE ALSO
  KEYWORDS

### NAME

Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList — 辞書としてのTcl 値を操作する　 manipulate Tcl values as dictionaries

### SYNOPSIS

#include <tcl.h>
Tcl_Obj *
Tcl_NewDictObj()
int
Tcl_DictObjGet(interp, dictPtr, keyPtr, valuePtrPtr)
int
Tcl_DictObjPut(interp, dictPtr, keyPtr, valuePtr)
int
Tcl_DictObjRemove(interp, dictPtr, keyPtr)
int
Tcl_DictObjSize(interp, dictPtr, sizePtr)
int
Tcl_DictObjFirst(interp, dictPtr, searchPtr,
`` keyPtrPtr, valuePtrPtr, donePtr)
void
Tcl_DictObjNext(searchPtr, keyPtrPtr, valuePtrPtr, donePtr)
void
Tcl_DictObjDone(searchPtr)
int
Tcl_DictObjPutKeyList(interp, dictPtr, keyc, keyv, valuePtr)
int
Tcl_DictObjRemoveKeyList(interp, dictPtr, keyc, keyv)

### ARGUMENTS

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

Tcl_Obj *dictPtr (入出力in/out)
  操作される辞書値を指す｡もし dictPtr が未だ辞書値を指していない場合､それを変換させる試みがなされる｡ 　 Points to the dictionary value to be manipulated. If dictPtr does not already point to a dictionary value, an attempt will be made to convert it to one.

Tcl_Obj *keyPtr (in)
  辞書値の内部で操作される 鍵/値 対の為の鍵を指す｡　 Points to the key for the key/value pair being manipulated within the dictionary value.

Tcl_Obj **keyPtrPtr (出力out)
  内部の 鍵/値 対からの鍵をその中に置かせることになる変数を指す｡呼出し者がその中に興味を持たない NULL を指しても好い｡　 Points to a variable that will have the key from a key/value pair placed within it. May be NULL to indicate that the caller is not interested in the key.

Tcl_Obj *valuePtr (入力in)
  辞書値の内部で操作される 鍵/値 対の為の値を指す(又は､Tcl_DictObjPutKeyList の場合の 副-値)｡　 Points to the value for the key/value pair being manipulated within the dictionary value (or sub-value, in the case of Tcl_DictObjPutKeyList.)

Tcl_Obj **valuePtrPtr (出力out)
  内部の 鍵/値 対からの鍵をその中に置かせることになる変数を指す｡Tcl_DictObjFirst と Tcl_DictObjNext の為には､これは呼出し者がその中に興味を持たない NULL でも好い｡　 Points to a variable that will have the value from a key/value pair placed within it. For Tcl_DictObjFirst and Tcl_DictObjNext, this may be NULL to indicate that the caller is not interested in the value.

int *sizePtr (出力out)
  辞書内部に含まれる 鍵/値 対の個数をその内部に置かせる変数を指す｡　 Points to a variable that will have the number of key/value pairs contained within the dictionary placed within it.

Tcl_DictSearch *searchPtr (入出力in/out)
  辞書内の全ての 鍵/値 対の列挙の進捗の追跡を守る為に使用する記録への指示子｡その記録の内容は､ Tcl_DictObjFirst への呼出しによって初期化される｡もし列挙が､辞書内の全ての値が返される前に終了されると､捜索記録は解除される内部施錠を可能にする為に Tcl_DictObjDone に渡されなければならない｡　 Pointer to record to use to keep track of progress in enumerating all key/value pairs in a dictionary. The contents of the record will be initialized by the call to Tcl_DictObjFirst. If the enumerating is to be terminated before all values in the dictionary have been returned, the search record must be passed to Tcl_DictObjDone to enable the internal locks to be released.

int *donePtr (出力out)
  辞書の中の 鍵/値 対の列挙が完成した時に非零値を､そうでない時には零を､その中に書かせる変数を指す｡　 Points to a variable that will have a non-zero value written into it when the enumeration of the key/value pairs in a dictionary has completed, and a zero otherwise.

int keyc (入力in)
  keyv 配列内に供給されている鍵の個数を指す｡ Indicates the number of keys that will be supplied in the keyv array.

Tcl_Obj *const *keyv (入力in)
  主辞書値を其処に渡した副辞書内部を操作する為の 鍵/値 対を設置する為に Tcl_DictObjPutKeyList と Tcl_DictObjRemoveKeyList が使用することになる値への keyc 指示子の配列｡　 　　　 Array of keyc pointers to values that Tcl_DictObjPutKeyList and Tcl_DictObjRemoveKeyList will use to locate the key/value pair to manipulate within the sub-dictionaries of the main dictionary value passed to them.

### DESCRIPTION

Tcl 辞書値は､内部表現を有し､それにより鍵から値への効果的な対応を運営し､どの鍵が削除されても(並んだ順列から削除する)追加されても(末尾にそれを追加する)､辞書内の鍵の順序は同じ剰余位置のままであることを保証する｡もしリストとして再解釈されてしまうと､リスト内の偶数値で索引される値が辞書の鍵になり､それぞれに､その鍵に結合した値(奇数値索引のもの)が続くことになってしまう｡ 　　　 Tcl dictionary values have an internal representation that supports efficient mapping from keys to values and which guarantees that the particular ordering of keys within the dictionary remains the same modulo any keys being deleted (which removes them from the order) or added (which adds them to the end of the order). If reinterpreted as a list, the values at the even-valued indices in the list will be the keys of the dictionary, and each will be followed (in the odd-valued index) by the value associated with that key.

この取扱い説明書の頁内に記述された手続函数は C 命令符号から辞書値について､生成､修正､索引､繰返することに使用される｡ 　　　 The procedures described in this man page are used to create, modify, index, and iterate over dictionary values from C code.

Tcl_NewDictObj は新しい空の辞書対照を作成する｡値の文字列表現は無効になり､値の参照回数は零にされる｡ Tcl_NewDictObj creates a new, empty dictionary value. The string representation of the value will be invalid, and the reference count of the value will be zero.

Tcl_DictObjGet は与えられた辞書内部で与えられた鍵を調べる､そしてその鍵に結合した値へのポインターを valuePtrPtr によって指定された変数内に書く､但し鍵が辞書内に対応がない場合は NULL を書く｡この手続函数の結果は TCL_OK か､もし dictPtr が辞書に変換できないときは TCL_ERROR である｡ Tcl_DictObjGet looks up the given key within the given dictionary and writes a pointer to the value associated with that key into the variable pointed to by valuePtrPtr, or a NULL if the key has no mapping within the dictionary. The result of this procedure is TCL_OK, or TCL_ERROR if the dictPtr cannot be converted to a dictionary.

Tcl_DictObjPut は与えられた辞書を更新し与えられた鍵に与えられた値を対応させる; どの鍵も特定のどの辞書にも高々一つだけ存在する｡辞書は共有してはならないが､鍵と値はしてもよい｡この手続函数は鍵と値を保存する必要証明すると両方への参照数を増加する｡鍵も値のどちらも NULL であってはならない｡この手続の結果は TCL_OK であり､もし dictPtr が辞書に変換できないときは TCL_ERROR である｡ Tcl_DictObjPut updates the given dictionary so that the given key maps to the given value; any key may exist at most once in any particular dictionary. The dictionary must not be shared, but the key and value may be. This procedure may increase the reference count of both key and value if it proves necessary to store them. Neither key nor value should be NULL. The result of this procedure is TCL_OK, or TCL_ERROR if the dictPtr cannot be converted to a dictionary.

Tcl_DictObjRemove は与えられた辞書を更新し与えられた鍵が何も値に対応を有さなくさせる｡辞書は共有してはならないが､鍵と値はしてもよい｡辞書内に実際に保存された鍵はもしそれが存在した場合は参照数を減らされる｡鍵が以前に実在しない場合は不都合ではない｡この手続の結果は TCL_OK であり､もし dictPtr が辞書に変換できないときは TCL_ERROR である｡ Tcl_DictObjRemove updates the given dictionary so that the given key has no mapping to any value. The dictionary must not be shared, but the key may be. The key actually stored in the dictionary will have its reference count decremented if it was present. It is not an error if the key did not previously exist. The result of this procedure is TCL_OK, or TCL_ERROR if the dictPtr cannot be converted to a dictionary.

Tcl_DictObjSize は与えられた辞書内の 鍵/値 対の現在の数として与えられた変数を更新する｡この手続の結果は TCL_OK であり､もし dictPtr が辞書に変換できないときは TCL_ERROR である｡ Tcl_DictObjSize updates the given variable with the number of key/value pairs currently in the given dictionary. The result of this procedure is TCL_OK, or TCL_ERROR if the dictPtr cannot be converted to a dictionary.

Tcl_DictObjFirst は与えられた辞書内の全ての 鍵/値 対を横断して処理の繰返しを開始し､鍵と値を keyPtrPtr と valuePtrPtr 引数に(それは呼出し側がその鍵又は値にそれぞれ無関係であることを指し示す NULL であるかもしれない)よって指される変数内に置く｡辞書内の次の 鍵/値 対は Tcl_DictObjNext によって取出し得る｡辞書が非共有でない限り､辞書の内部表現の同時更新は反復処理を変更しないであろう､該当する時は､その代わりにそれは反復処理の早過ぎる終了を引き起こすであろう( Tcl 記述譜は dict 命令経由では起動できない)｡ searchPtr 引数は文脈の断片を指し､それはどの反復が遂行されているかの識別に使用される､又､ Tcl_DictObjFirst を呼出すことにより初期化される｡ donePtr 引数は､更に繰り返されるべき 鍵/値 対がある場合は零､繰り返しが完了した場合は非零に更新される引数を指す｡繰返しの順序は実装により定義される｡ dictPtr 引数が辞書に変換できない場合､と､繰返しが始められない場合は Tcl_DictObjFirst は TCL_ERROR を返す､それ以外は TCL_OK を返す｡ Tcl_DictObjFirst commences an iteration across all the key/value pairs in the given dictionary, placing the key and value in the variables pointed to by the keyPtrPtr and valuePtrPtr arguments (which may be NULL to indicate that the caller is uninterested in they key or variable respectively.) The next key/value pair in the dictionary may be retrieved with Tcl_DictObjNext. Concurrent updates of the dictionary's internal representation will not modify the iteration processing unless the dictionary is unshared, when this will trigger premature termination of the iteration instead (which Tcl scripts cannot trigger via the dict command.) The searchPtr argument points to a piece of context that is used to identify which particular iteration is being performed, and is initialized by the call to Tcl_DictObjFirst. The donePtr argument points to a variable that is updated to be zero of there are further key/value pairs to be iterated over, or non-zero if the iteration is complete. The order of iteration is implementation-defined. If the dictPtr argument cannot be converted to a dictionary, Tcl_DictObjFirst returns TCL_ERROR and the iteration is not commenced, and otherwise it returns TCL_OK.

Tcl_DictObjFirst が辞書上で呼ばれる時､繰返し処理の間に辞書が修正されるかを考慮することなく安全に反復処理されることを可能にする為に錠が辞書上に取付けられる｡この理由で､一度辞書の鍵の上の反復処理が終了すると( donePtr 引数によって指定される変数が１であることにより指し示されことにより全ての値が反復処理し終えた為か､或は更なる値が無くなった為か､いずれかにより)､ Tcl_DictObjDone 函数はそれにより内部錠が解除される様に､ Tcl_DictObjFirst に渡されたと同じ searchPtr と共に呼ばれなければならない｡一たび特定の searchPtr が Tcl_DictObjDone に渡されると､ Tcl_DictObjNext にそれを渡すことは( Tcl_DictObjFirst で最初に初期化することなしに)､何も値を生成しない結果になり､ donePtr によって指される変数は､１に設定される｡それぞれの Tcl_DictObjFirst への呼出しの為に､同じ searchPtr 上への複数回の Tcl_DictObjDone 呼出しは安全である｡ 　　　 When Tcl_DictObjFirst is called upon a dictionary, a lock is placed on the dictionary to enable that dictionary to be iterated over safely without regard for whether the dictionary is modified during the iteration. Because of this, once the iteration over a dictionary's keys has finished (whether because all values have been iterated over as indicated by the variable indicated by the donePtr argument being set to one, or because no further values are required) the Tcl_DictObjDone function must be called with the same searchPtr as was passed to Tcl_DictObjFirst so that the internal locks can be released. Once a particular searchPtr is passed to Tcl_DictObjDone, passing it to Tcl_DictObjNext (without first initializing it with Tcl_DictObjFirst) will result in no values being produced and the variable pointed to by donePtr being set to one. It is safe to call Tcl_DictObjDone multiple times on the same searchPtr for each call to Tcl_DictObjFirst.

手続函数 Tcl_DictObjPutKeyList と Tcl_DictObjRemoveKeyList はそれぞれ Tcl_DictObjPut と Tcl_DictObjRemove に良く似ているが違いは､単一の辞書で働くのではなく､内側の辞書が外側の辞書の内側に値として保存されている様な樹木状の入れ子になった辞書を操作するように設計されている｡ keyc と keyv 引数は鍵のリストを指定する(最外鍵が最初)､それは､影響を受ける鍵/値 対への経路として働く｡註意すべきは､Tcl_DictObjGet の繰返し使用による構築は容易であるので､経路の為の値を読むために対応する操作はない｡ Tcl_DictObjPutKeyList により､入れ子になった辞書は､実在しない場所に､非終端鍵の為に作成される｡ Tcl_DictObjRemoveKeyList により､全ての非終端鍵は実在しなけれればならず､その値として辞書を有しなければなない｡ 　　　 The procedures Tcl_DictObjPutKeyList and Tcl_DictObjRemoveKeyList are the close analogues of Tcl_DictObjPut and Tcl_DictObjRemove respectively, except that instead of working with a single dictionary, they are designed to operate on a nested tree of dictionaries, with inner dictionaries stored as values inside outer dictionaries. The keyc and keyv arguments specify a list of keys (with outermost keys first) that acts as a path to the key/value pair to be affected. Note that there is no corresponding operation for reading a value for a path as this is easy to construct from repeated use of Tcl_DictObjGet. With Tcl_DictObjPutKeyList, nested dictionaries are created for non-terminal keys where they do not already exist. With Tcl_DictObjRemoveKeyList, all non-terminal keys must exist and have dictionaries as their values.

### 用例 EXAMPLE

自分自身に対応する鍵が存在するかの決定の為に､辞書の捜索の為の相互対話の繰返し処理を使う: 　　　 Using the dictionary iteration interface to search determine if there is a key that maps to itself:

    Tcl_DictSearch search;
    Tcl_Obj *key, *value;
    int done;

    /*
     * interp と objPtr は假引数であると仮定する｡これは
    辞書の繰返し処理を始める定石である;内部の表現に錠を
    設定する､それは通常の参照勘定が同時に使用されている
    場合は同時の修正による項目はないことを確定する｡
    その錠は繰返しが終了した時に自動的に解除されるが､
    例外処理により繰返しが終了した時は手動で解除しなけれ
    ばならない｡但し､我々が繰返しを終了していても錠の解除の
    試みは安全である｡
     * Assume interp and objPtr are parameters.  This is the
     * idiomatic way to start an iteration over the dictionary; it
     * sets a lock on the internal representation that ensures that
     * there are no concurrent modification issues when normal
     * reference count management is also used.  The lock is
     * released automatically when the loop is finished, but must
     * be released manually when an exceptional exit from the loop
     * is performed. However it is safe to try to release the lock
     * even if we've finished iterating over the loop.
     */
    if (Tcl_DictObjFirst(interp, objPtr, &search,
            &key, &value, &done) != TCL_OK) {
        return TCL_ERROR;
    }
    for (; !done ; Tcl_DictObjNext(&search, &key, &value, &done)) {
        /*
         * 註意すべきは､ strcmp() は値の比較には適していないが
         * 実演の目的に､敢えて使っているだけである｡
         * Note that strcmp() is not a good way of comparing
         * values and is just used here for demonstration
         * purposes.
         */
        if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
            break;
        }
    }
    Tcl_DictObjDone(&search);
    Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
    return TCL_OK;

### SEE ALSO

Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable

### KEYWORDS

dict, dict value, dictionary, dictionary value, hash table, iteration, value
Copyright © 2003 Donal K. Fellows