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 representation is modified to hold the
                                                index of the matching table 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  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.

       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 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_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

       prefix(3tcl), Tcl_WrongNumArgs(3tcl)

KEYWORDS

       index, option, value, table lookup