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 value
28                                                is   used  to  search  through
29                                                tablePtr.  The internal repre‐
30                                                sentation  is modified to hold
31                                                the index of the matching  ta‐
32                                                ble entry.
33
34       const char *const *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

DESCRIPTION

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

SEE ALSO

120       prefix(n), Tcl_WrongNumArgs(3)
121

KEYWORDS

123       index, option, value, table lookup
124
125
126
127Tcl                                   8.1               Tcl_GetIndexFromObj(3)
Impressum