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                                                                                                       2
       Tcl_GetIndexFromObjStruct(interp, objPtr, structTablePtr, offset,                                         2
       msg, flags, indexPtr)                                                                                     2

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  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 representation of objPtr, so this  should
                                           represent the address of a statically-allocated array.

       CONST VOID   *structTablePtr(in)    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 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.                                        2

       int          offset       (in)                                                                            2
                                           The offset to add to structTablePtr to get to the  next  entry.   The 2
                                           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
                                           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  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 isn't 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.                                                                                                2

       Tcl_GetIndexFromObjStruct  works  just like Tcl_GetIndexFromObj, except that instead of treating tablePtr 2
       as an array of string pointers, it treats it as the first in a series of  string  ptrs  that  are  spaced 2
       apart  by  offset  bytes.  This  is particularly useful when processing things like Tk_ConfigurationSpec, 2
       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(3tcl)