Manual Pages for UNIX Operating System command usage for man Tcl_GetIndexFromObjStruct

Tcl Library Procedures                  Tcl_GetIndexFromObj(3TCL)



_________________________________________________________________

NAME
     Tcl_GetIndexFromObj,  Tcl_GetIndexFromObjStruct   -   lookup
     string in table of keywords

SYNOPSIS
     #include 

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

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

     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  |



Tcl                     Last change: 8.1                        1






Tcl Library Procedures                  Tcl_GetIndexFromObj(3TCL)



                                         pointer.

     CONST char   *msg         (in)      Null-terminated   string
                                         describing what is being
                                         looked   up,   such   as
                                         option.   This string is
                                         included in  error  mes-
                                         sages.

     int          flags        (in)      OR-ed   combination   of
                                         bits   providing   addi-
                                         tional  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
     This procedure provides an efficient way for looking up key-
     words,  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 speci-
     fied; 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



Tcl                     Last change: 8.1                        2






Tcl Library Procedures                  Tcl_GetIndexFromObj(3TCL)



     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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.























Tcl                     Last change: 8.1                        3