DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_GetIndexFromObj(3)




Tcl_GetIndexFromObj(3)Tcl Library ProcedureTcl_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  report-
                                              ing; if NULL,  then
                                              no  message is pro-
                                              vided on errors.

     Tcl_Obj *objPtr (in/out)                 The string value of
                                              this object is used
                                              to  search  through
                                              tablePtr.       The
                                              internal  represen-
                                              tation  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.  Note that
                                              references  to  the
                                              tablePtr   may   be
                                              retained   in   the
                                              internal  represen-
                                              tation  of  objPtr,
                                              so    this   should
                                              represent       the
                                              address     of    a
                                              statically-
                                              allocated array.

     const void *structTablePtr (in)          An     array     of

Tcl                     Last change: 8.1                        1

Tcl_GetIndexFromObj(3)Tcl Library ProcedureTcl_GetIndexFromObj(3)

                                              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   refer-
                                              ences     to    the
                                              structTablePtr  may
                                              be  retained in the
                                              internal  represen-
                                              tation  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 informa-
                                              tion 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.

Tcl                     Last change: 8.1                        2

Tcl_GetIndexFromObj(3)Tcl Library ProcedureTcl_GetIndexFromObj(3)

_________________________________________________________________


DESCRIPTION

     These procedures provide 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.  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

     Tcl_WrongNumArgs

Tcl                     Last change: 8.1                        3

Tcl_GetIndexFromObj(3)Tcl Library ProcedureTcl_GetIndexFromObj(3)


KEYWORDS

     index, object, table lookup

Tcl                     Last change: 8.1                        4


Man(1) output converted with man2html