Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct - lookup string in table
       of keywords


       #include <tcl.h>

       Tcl_GetIndexFromObj(interp, objPtr, tablePtr, msg, flags,

       int                                                                     |
       Tcl_GetIndexFromObjStruct(interp, objPtr, structTablePtr, offset,       |
       msg, flags, indexPtr)                                                   |


       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.


       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.




       index, object, table lookup

Tcl                                   8.1               Tcl_GetIndexFromObj(3)

Man(1) output converted with man2html