Tcl_GetIndexFromObj(3)
Tcl_GetIndexFromObj(3)Tcl Library ProcedureTcl_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 report-
ing; if NULL, then
no message is pro-
vided on errors.
Tcl_Obj *objPtr (in/out) The string value of
this object is used
to search through
tablePtr. The
internal represen-
tation is modified
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. Note that
references to the
tablePtr may be
retained in the
internal represen-
tation of objPtr,
so this should
represent the
address of a
statically-
allocated array.
const void *structTablePtr (in) An array of
Tcl Last change: 8.1 1
Tcl_GetIndexFromObj(3)Tcl Library ProcedureTcl_GetIndexFromObj(3)
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 refer-
ences to the
structTablePtr may
be retained in the
internal represen-
tation of objPtr,
so this should
represent the
address of a
statically-
allocated array of
structures.
int offset (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 informa-
tion 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.
Tcl Last change: 8.1 2
Tcl_GetIndexFromObj(3)Tcl Library ProcedureTcl_GetIndexFromObj(3)
_________________________________________________________________
DESCRIPTION
These procedures provide 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. 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 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 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".
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 invocations. 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 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
Tcl_WrongNumArgs
Tcl Last change: 8.1 3
Tcl_GetIndexFromObj(3)Tcl Library ProcedureTcl_GetIndexFromObj(3)
KEYWORDS
index, object, table lookup
Tcl Last change: 8.1 4
Man(1) output converted with
man2html