Tcl_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
                                           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.

       CONST char   **tablePtr   (in)      An   array    of    null-terminated
                                           strings.   The  end of the array is
                                           marked by a NULL string pointer.

       CONST VOID   *structTablePtr(in)    An array of arbitrary  type,  typi-
                                           cally  some struct type.  The first
                                           member of the structure must  be  a
                                           null-terminated  string.   The size
                                           of the structure is given  by  off-
                                           set.                                |

       int          off-                                                       |
       set       (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 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 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 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.  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 the first in a series of string ptrs that are spaced apart |
       by offset bytes. 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

KEYWORDS

       index, object, table lookup

Tcl                                   8.1               Tcl_GetIndexFromObj(3)