1Tcl_GetIndexFromObj(3)      Tcl Library Procedures      Tcl_GetIndexFromObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct - lookup string in table
9       of keywords
10

SYNOPSIS

12       #include <tcl.h>
13
14       int
15       Tcl_GetIndexFromObj(interp, objPtr, tablePtr, msg, flags,
16       indexPtr)
17
18       int
19       Tcl_GetIndexFromObjStruct(interp, objPtr, structTablePtr, offset,
20                                 msg, flags, indexPtr)
21

ARGUMENTS

23       Tcl_Interp *interp (in)                  Interpreter to use  for  error
24                                                reporting;  if  NULL,  then no
25                                                message is provided on errors.
26
27       Tcl_Obj *objPtr (in/out)                 The  string  value   of   this
28                                                object   is   used  to  search
29                                                through tablePtr.  The  inter‐
30                                                nal representation is modified
31                                                to  hold  the  index  of   the
32                                                matching table entry.
33
34       const char **tablePtr (in)               An  array  of  null-terminated
35                                                strings.  The end of the array
36                                                is  marked  by  a  NULL string
37                                                pointer.  Note that references
38                                                to   the   tablePtr   may   be
39                                                retained in the internal  rep‐
40                                                resentation of objPtr, so this
41                                                should represent  the  address
42                                                of    a   statically-allocated
43                                                array.
44
45       const void *structTablePtr (in)          An array  of  arbitrary  type,
46                                                typically  some  struct  type.
47                                                The first member of the struc‐
48                                                ture must be a null-terminated
49                                                string.   The  size   of   the
50                                                structure  is given by offset.
51                                                Note that  references  to  the
52                                                structTablePtr may be retained
53                                                in the internal representation
54                                                of objPtr, so this should rep‐
55                                                resent the address of a stati‐
56                                                cally-allocated    array    of
57                                                structures.
58
59       int offset (in)                          The offset to add  to  struct‐
60                                                TablePtr  to  get  to the next
61                                                entry.  The end of  the  array
62                                                is  marked  by  a  NULL string
63                                                pointer.
64
65       const char *msg (in)                     Null-terminated         string
66                                                describing   what   is   being
67                                                looked  up,  such  as  option.
68                                                This  string  is  included  in
69                                                error messages.
70
71       int flags (in)                           OR-ed combination of bits pro‐
72                                                viding  additional information
73                                                for operation.  The  only  bit
74                                                that  is  currently defined is
75                                                TCL_EXACT.
76
77       int *indexPtr (out)                      The index  of  the  string  in
78                                                tablePtr   that   matches  the
79                                                value of  objPtr  is  returned
80                                                here.
81_________________________________________________________________
82
83

DESCRIPTION

85       These  procedures  provide  an  efficient  way for looking up keywords,
86       switch names, option names, and similar things where the  value  of  an
87       object  must be one of a predefined set of values.  Tcl_GetIndexFromObj
88       compares objPtr against each of the  strings  in  tablePtr  to  find  a
89       match.   A match occurs if objPtr's string value is identical to one of
90       the strings in tablePtr, or if it is a  non-empty  unique  abbreviation
91       for  exactly  one of the strings in tablePtr and the TCL_EXACT flag was
92       not specified; in either case the index of the matching entry is stored
93       at *indexPtr and TCL_OK is returned.
94
95       If  there is no matching entry, TCL_ERROR is returned and an error mes‐
96       sage is left in interp's result if interp is not NULL.  Msg is included
97       in  the  error message to indicate what was being looked up.  For exam‐
98       ple, if msg is option the error message will  have  a  form  like  “bad
99       option "firt": must be first, second, or third”.
100
101       If  Tcl_GetIndexFromObj completes successfully it modifies the internal
102       representation of objPtr to hold the address of the table and the index
103       of  the  matching  entry.  If Tcl_GetIndexFromObj is invoked again with
104       the same objPtr and tablePtr arguments (e.g. during a reinvocation of a
105       Tcl  command), it returns the matching index immediately without having
106       to redo the lookup operation.  Note: Tcl_GetIndexFromObj  assumes  that
107       the  entries in tablePtr are static: they must not change between invo‐
108       cations.  If the value of objPtr is the empty string,  Tcl_GetIndexFro‐
109       mObj will treat it as a non-matching value and return TCL_ERROR.
110
111       Tcl_GetIndexFromObjStruct  works  just like Tcl_GetIndexFromObj, except
112       that instead of treating tablePtr as an array of  string  pointers,  it
113       treats  it as a pointer to the first string in a series of strings that
114       have offset bytes between them (i.e. that there is  a  pointer  to  the
115       first array of characters at tablePtr, a pointer to the second array of
116       characters at tablePtr+offset bytes, etc.)  This is particularly useful
117       when processing things like Tk_ConfigurationSpec, whose string keys are
118       in the same place in each of several array elements.
119
120

SEE ALSO

122       Tcl_WrongNumArgs
123
124

KEYWORDS

126       index, object, table lookup
127
128
129
130Tcl                                   8.1               Tcl_GetIndexFromObj(3)
Impressum