Tcl_GetIndexFromObj(3tcl) Tcl Library Procedures Tcl_GetIndexFromObj(3tcl)
______________________________________________________________________________
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 value
is used to search through
tablePtr. The internal repre-
sentation is modified to hold
the index of the matching ta-
ble entry.
const char *const *tablePtr (in) An array of null-terminated
strings. The end of the array
is marked by a NULL string
pointer. Note that references
to the tablePtr may be re-
tained in the internal repre-
sentation of objPtr, so this
should represent the address
of a statically-allocated ar-
ray.
const void *structTablePtr (in) An array of arbitrary type,
typically some struct type.
The first member of the struc-
ture must be a null-terminated
string. The size of the
structure is given by offset.
Note that references to the
structTablePtr may be retained
in the internal representation
of objPtr, so this should rep-
resent the address of a stati-
cally-allocated array of
structures.
int offset (in) The offset to add to struct-
TablePtr 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 de-
scribing what is being looked
up, such as option. This
string is included in error
messages.
int flags (in) OR-ed combination of bits pro-
viding additional information
for operation. The only bit
that is currently defined is
TCL_EXACT.
int *indexPtr (out) The index of the string in
tablePtr that matches the
value of objPtr is returned
here.
______________________________________________________________________________
DESCRIPTION
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_GetIndexFro-
mObj 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 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 is not 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 op-
tion "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 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.
SEE ALSO
prefix(3tcl), Tcl_WrongNumArgs(3tcl)
KEYWORDS
index, option, value, table lookup
Tcl 8.1 Tcl_GetIndexFromObj(3tcl)
Generated by dwww version 1.14 on Thu Jan 23 00:21:10 CET 2025.