Tcl_GetIndexFromObj(3) Tcl Library Procedures Tcl_GetIndexFromObj(3)______________________________________________________________________________NAME
Tcl_GetIndexFromObj - lookup string in table of keywords
SYNOPSIS
#include <tcl.h>
int
Tcl_GetIndexFromObj(interp, objPtr, tablePtr, 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.
char **tablePtr (in) An array of null-terminated
strings. The end of the array is
marked by a NULL string pointer.
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 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.
SEE ALSO
Tcl_WrongNumArgs
KEYWORDS
index, object, table lookup
Tcl 8.0 Tcl_GetIndexFromObj(3)