TclGetIndexFromObj(3) Tcl Library Procedures TclGetIndexFromObj(3)

NAME
       TclGetIndexFromObj, TclGetIndexFromObjStruct - lookup string in table
       of keywords

SYNOPSIS
       ##iinncclluuddee <>

       int
       TTccllGGeettIInnddeexxFFrroommOObbjj(interp, objPtr, tablePtr, msg, flags,
       indexPtr)

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

AARRGGUUMMEENNTTSS
       TclInterp   *interp      (in)      Interpreter  to   use   for   error
                                           reporting; if NULL, then no message
                                           is provided on errors.

       TclObj      *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 ssttrruucctt 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
                                           ooppttiioonn.  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 TTCCLLEEXXAACCTT.

       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 unique abbreviation  for  exactly  one  of  the
       strings in tablePtr and the TTCCLLEEXXAACCTT flag was not specified; in either
       case the index of the matching entry is stored at *indexPtr and  TCLOK
       is returned.

       If  there is no matching entry, TCLERROR 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 ooppttiioonn the error message  will  have  a  form  like  bbaadd
       ooppttiioonn ""ffiirrtt"":: mmuusstt bbee ffiirrsstt,, sseeccoonndd,, oorr tthhiirrdd.

       If  TTccllGGeettIInnddeexxFFrroommOObbjj completes successfully it modifies the internal
       representation of objPtr to hold the address of the table and the index
       of  the  matching  entry.  If TTccllGGeettIInnddeexxFFrroommOObbjj 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: TTccllGGeettIInnddeexxFFrroommOObbjj  assumes  that
       the  entries in tablePtr are static: they must not change between invo-
       cations.  If the value of objPtr is the empty string,  TTccllGGeettIInnddeexxFFrroo-
       mmOObbjj will treat it as a non-matching value and return TCLERROR.        |

       TTccllGGeettIInnddeexxFFrroommOObbjjSSttrruucctt  works  just like TTccllGGeettIInnddeexxFFrroommOObbjj, 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  TTkkCCoonnffiigguurraattiioonnSSppeecc,  whose string keys are in the same place in |
       each of several array elements.


SEE ALSO
       TclWrongNumArgs


KKEEYYWWOORRDDSS
       index, object, table lookup



Tcl                                   8.1               TclGetIndexFromObj(3)