## Tcl9.0.3/Tk9.0.3 Documentation > Tcl C API > GetIndex

### 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_GetIndexFromObj, Tcl_GetIndexFromObjStruct — 検索語彙の表内の文字列を捜す　 lookup string in table of keywords
  SYNOPSIS
    #include <tcl.h>
    int
    Tcl_GetIndexFromObj(interp, objPtr, tablePtr, msg, flags,
    indexPtr)
    int
    Tcl_GetIndexFromObjStruct(interp, objPtr, structTablePtr, offset,
    msg, flags, indexPtr)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    Tcl_Obj *objPtr (入出力in/out)
    const char *const *tablePtr (入力in)
    const void *structTablePtr (入力in)
    int offset (入力in)
    const char *msg (入力in)
    int flags (入力in)
    enum|char|short|int|long *indexPtr (出力out)
  DESCRIPTION
  参照回数管理 REFERENCE COUNT MANAGEMENT
  SEE ALSO
  KEYWORDS

### NAME

Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct — 検索語彙の表内の文字列を捜す　 lookup string in table of keywords

### SYNOPSIS

#include <tcl.h>
int
Tcl_GetIndexFromObj(interp, objPtr, tablePtr, msg, flags,
indexPtr)
int
Tcl_GetIndexFromObjStruct(interp, objPtr, structTablePtr, offset,
`` msg, flags, indexPtr)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  不都合を報告する為に使用する解釈実行機能; もし NULL なら不都合の時に伝言文は提供されない｡　 Interpreter to use for error reporting; if NULL, then no message is provided on errors.

Tcl_Obj *objPtr (入出力in/out)
  この値の文字列値はtablePtrを通して捜索する為に使われる｡ もし､TCL_INDEX_TEMP_TABLE旗徴が指定されないと､内部表現は､整合表見出しの位置を保持する為に修正される｡ The string value of this value is used to search through tablePtr. If the TCL_INDEX_TEMP_TABLE flag is not specified, the internal representation is modified to hold the index of the matching table entry.

const char *const *tablePtr (入力in)
  零終端文字列の配列｡この配列の末尾は NULL 文字列指示子により印付けられる｡註意すべきは､tablePtr への参照は objPtr の内部表現で保持されるかもしれない､それで､これは静的に-割当てられた配列の番地を表現することになる｡ 　　　 An array of null-terminated strings. The end of the array is marked by a NULL string pointer. Note that, unless the TCL_INDEX_TEMP_TABLE flag is specified, references to the tablePtr may be retained in the internal representation of objPtr, so this should represent the address of a statically-allocated array.

const void *structTablePtr (入力in)
  任意の型の配列､典型的には何かのstruct型｡構造の第一の要員はヌル終末型の文字列でなければならない｡構造の寸法はoffsetによって与えられる｡註意すべきは､TCL_INDEX_TEMP_TABLE旗徴が指定されている限り､structTablePtrへの参照は､objPtrの内部表現内に留められ得る､そこで､これは構造の静的な割当ての番地を現す筈である｡ An array of arbitrary type, typically some struct type. The first member of the structure must be a null-terminated string. The size of the structure is given by offset. Note that, unless the TCL_INDEX_TEMP_TABLE flag is specified, references to the structTablePtr may be retained in the internal representation of objPtr, so this should represent the address of a statically-allocated array of structures.

int offset (入力in)
  次の項目を得る為の structTablePtr に加える偏移｡配列の末尾は NULL 文字列指示子によって印付けられる｡　 The offset to add to structTablePtr to get to the next entry. The end of the array is marked by a NULL string pointer.

const char *msg (入力in)
  捜索されていることを記述する零終端文字列､譬えば指定項目の如く｡この文字列は不都合伝言文内に含まれる｡　 Null-terminated string describing what is being looked up, such as option. This string is included in error messages.

int flags (入力in)
  操作の為の追加情報を提供するビットの論理和の組合せ｡ 現在定義されているビットは､TCL_EXACTとTCL_INDEX_TEMP_TABLEとTCL_NULL_OKのみ｡ OR-ed combination of bits providing additional information for operation. The only bits that are currently defined are TCL_EXACT , TCL_INDEX_TEMP_TABLE, and TCL_NULL_OK.

enum|char|short|int|long *indexPtr (出力out)
  もし(int *)NULLでなければ､objPtrの値に整合するtablePtr内の文字列の位置が､ここに返される｡変数はどの様な､符号無し､符号付､文字､単精度､長精度､長長精度の型でも好い｡列挙型でもよい｡ If not (int *)NULL, the index of the string in tablePtr that matches the value of objPtr is returned here. The variable can be any integer type, signed or unsigned, char, short, long or long long. It can also be an enum.

### DESCRIPTION

これらの手続函数は､鍵語､切替え名称､選択肢名､同様な Tcl 値の文字値が予備定義された組から選択されなければならない事柄､を捜索する効率的方法を提供する｡ Tcl_GetIndexFromObj は objPtr をそれぞれ tablePtr 内の合致を捜すべき文字列に対して比較する｡ objPtr の文字列値が tablePtr の内の一つと同一であるか､ tablePtr 内の厳密に一つを特定できる短縮形であり､且つ TCL_EXACT 旗印が設定されていないかの場合が合致である; どの場合も､TCL_OKが返される｡ もし､indexPtrがNULLでない場合､適合している見出しの位置が*indexPtrに保存される｡ These procedures provide an efficient way for looking up keywords, switch names, option names, and similar things where the literal value of a Tcl value must be chosen from a predefined set. Tcl_GetIndexFromObj compares objPtr against each of the strings in tablePtr to find a match. A match occurs if objPtr's string value is identical to one of the strings in tablePtr, or if it is a non-empty unique abbreviation for exactly one of the strings in tablePtr and the TCL_EXACT flag was not specified; in either case TCL_OK is returned. If indexPtr is not NULL the index of the matching entry is stored at *indexPtr.

もし合致する見出しが存在しない場合､ TCL_ERROR が返され､ interp が NULL でない場合､不都合伝言文が interp の結果に保存される｡何が調査されたかを指し示す為に msg は不都合伝言文の中に含まれる｡譬えば､もし msg が option であると､伝言文はこの様な形式になる “不適切な指示項目 "firt": は first か second か thirdの筈” ｡ If there is no matching entry, TCL_ERROR is returned and an error message is left in interp's result if interp is not NULL. Msg is included in the error message to indicate what was being looked up. For example, if msg is option the error message will have a form like “bad option "firt": must be first, second, or third”.

TCL_INDEX_TEMP_TABLEが指定されてない場合､ Tcl_GetIndexFromObjが成功裡に終了する時､表の番地と､整合する見出しの位置と､をを保持する為に､objPtrの内部表現を修正する｡ もし同じ objPtr と tablePtr 引数を伴って再度 Tcl_GetIndexFromObjが起動されると(譬えば､ Tcl 命令の再起動の間に)､捜索操作の再実行をさせることなく合致する索引をすぐさま返す｡ 註意すべきは､ Tcl_GetIndexFromObj は tablePtr 内の見出しは静的であると仮定している: それらは起動中は変化するはずはない｡ この高速記憶の機構はTCL_INDEX_TEMP_TABLE旗徴を指定して､禁止できる｡ もし､TCL_NULL_OK旗徴が指定されると､objPtrにNULLや空文字列が許容される｡ 結果の位置は-1である｡ それ以外の場合､もし､objPtrが空文字列であると､Tcl_GetIndexFromObjは､それを非整合値として取扱い､TCL_ERRORを返す｡ If the TCL_INDEX_TEMP_TABLE was not specified, when Tcl_GetIndexFromObj completes successfully it modifies the internal representation of objPtr to hold the address of the table and the index of the matching entry. If Tcl_GetIndexFromObj is invoked again with the same objPtr and tablePtr arguments (e.g. during a reinvocation of a Tcl command), it returns the matching index immediately without having to redo the lookup operation. Note that Tcl_GetIndexFromObj assumes that the entries in tablePtr are static: they must not change between invocations. This caching mechanism can be disallowed by specifying the TCL_INDEX_TEMP_TABLE flag. If the TCL_NULL_OK flag was specified, objPtr is allowed to be NULL or the empty string. The resulting index is -1. Otherwise, if the value of objPtr is the empty string, Tcl_GetIndexFromObj will treat it as a non-matching value and return TCL_ERROR.

Tcl_GetIndexFromObjStruct は丁度 Tcl_GetIndexFromObj の様に働く､違いは､ tablePtr を文字列ポインターの配列として扱うのではなく､その間に offset バイトを有する継続した文字列内の最初の文字列へのポインターとして取扱うことである(即ち､ tablePtr の位置にある第１の文字配列を指すポインターがあり､ tablePtr+offset バイトの位置にある第二の文字配列を指すポインターがあり､等)｡これはその文字列鍵が幾つかの配列要素のそれぞれの同じ位置にある Tk_ConfigurationSpec の様なものの処理には特に便利である｡ Tcl_GetIndexFromObjStruct works just like Tcl_GetIndexFromObj, except that instead of treating tablePtr as an array of string pointers, it treats it as a pointer to the first string in a series of strings that have offset bytes between them (i.e. that there is a pointer to the first array of characters at tablePtr, a pointer to the second array of characters at tablePtr+offset bytes, etc.) This is particularly useful when processing things like Tk_ConfigurationSpec, whose string keys are in the same place in each of several array elements.

### 参照回数管理 REFERENCE COUNT MANAGEMENT

Tcl_GetIndexFromObjとTcl_GetIndexFromObjStructはそのobjPtr引数の参照回数を修正しない; 唯読出すだけである｡註意､但し､これ等の函数は解釈実行機能の結果を修正し得る; もし､対象への参照を保持するだけ場所の場合は､削除される事になる｡ Tcl_GetIndexFromObj and Tcl_GetIndexFromObjStruct do not modify the reference count of their objPtr arguments; they only read. Note however that these functions may set the interpreter result; if that is the only place that is holding a reference to the object, it will be deleted.

### SEE ALSO

prefix, Tcl_WrongNumArgs

### KEYWORDS

index, option, value, table lookup
Copyright © 1997 Sun Microsystems, Inc.