1Tcl_GetIndexFromObj(3) Tcl Library Procedures Tcl_GetIndexFromObj(3)
2______________________________________________________________________________
6
8 Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct - lookup string in table
9 of keywords
10
12 #include <tcl.h>
13 int
15 Tcl_GetIndexFromObj(interp, objPtr, tablePtr, msg, flags,
16 indexPtr)
17 int
19 Tcl_GetIndexFromObjStruct(interp, objPtr, structTablePtr, offset,
20 msg, flags, indexPtr)
21
23 Tcl_Interp *interp (in) Interpreter to use for error
24 reporting; if NULL, then no
25 message is provided on errors.
26 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 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 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 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 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 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 int *indexPtr (out) The index of the string in
78 tablePtr that matches the
79 value of objPtr is returned
80 here.
81_________________________________________________________________
82
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 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 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 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
122 Tcl_WrongNumArgs
123
126 index, object, table lookup
127Tcl 8.1 Tcl_GetIndexFromObj(3)