linuXperts.org

Tcl_GetIndexFromObj(3) Tcl Library Procedures Tcl_GetIndexFromObj(3) ______________________________________________________________________________ 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) Interpreter to use for error reporting; if NULL, then no message is provided on errors. Tcl_Obj *objPtr (in/out) The string value of this object is used to search through tablePtr. The internal representation is mod- ified to hold the index of the matching table entry. CONST char **tablePtr (in) An array of null-terminated strings. The end of the array is marked by a NULL string pointer. CONST VOID *structTablePtr(in) An array of arbitrary type, typi- cally some struct type. The first member of the structure must be a null-terminated string. The size of the structure is given by off- set. | int off- | set (in) | | 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) OR-ed combination of bits providing additional information for opera- tion. The only bit that is cur- rently defined is TCL_EXACT. int *indexPtr (out) The index of the string in tablePtr that matches the value of objPtr is returned here. _________________________________________________________________ DESCRIPTION This procedure provides an efficient way for looking up keywords, switch names, option names, and similar things where the value of an object must be one of a predefined set of values. ObjPtr is compared 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 the index of the matching entry is stored at *indexPtr and TCL_OK is returned. If there is no matching entry, TCL_ERROR is returned and an error mes- sage is left in interp's result if interp isn't NULL. Msg is included in the error message to indicate what was being looked up. For exam- ple, if msg is option the error message will have a form like bad option "firt": must be first, second, or third. If 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: Tcl_GetIndexFromObj assumes that the entries in tablePtr are static: they must not change between invo- cations. If the value of objPtr is the empty string, Tcl_GetIndexFro- mObj will treat it as a non-matching value and return TCL_ERROR. | Tcl_GetIndexFromObjStruct works just like Tcl_GetIndexFromObj, except | that instead of treating tablePtr as an array of string pointers, it | treats it as the first in a series of string ptrs that are spaced apart | by offset bytes. This is particularly useful when processing things | like Tk_ConfigurationSpec, whose string keys are in the same place in | each of several array elements. SEE ALSO Tcl_WrongNumArgs KEYWORDS index, object, table lookup Tcl 8.1 Tcl_GetIndexFromObj(3)