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.
38 const void *structTablePtr (in) An array of arbitrary type,
40 typically some struct type.
41 The first member of the struc‐
42 ture must be a null-terminated
43 string. The size of the
44 structure is given by offset.
45 int offset (in) The offset to add to struct‐
47 TablePtr to get to the next
48 entry. The end of the array
49 is marked by a NULL string
50 pointer.
51 const char *msg (in) Null-terminated string
53 describing what is being
54 looked up, such as option.
55 This string is included in
56 error messages.
57 int flags (in) OR-ed combination of bits pro‐
59 viding additional information
60 for operation. The only bit
61 that is currently defined is
62 TCL_EXACT.
63 int *indexPtr (out) The index of the string in
65 tablePtr that matches the
66 value of objPtr is returned
67 here.
68_________________________________________________________________
69
72 This procedure provides an efficient way for looking up keywords,
73 switch names, option names, and similar things where the value of an
74 object must be one of a predefined set of values. ObjPtr is compared
75 against each of the strings in tablePtr to find a match. A match
76 occurs if objPtr's string value is identical to one of the strings in
77 tablePtr, or if it is a non-empty unique abbreviation for exactly one
78 of the strings in tablePtr and the TCL_EXACT flag was not specified; in
79 either case the index of the matching entry is stored at *indexPtr and
80 TCL_OK is returned.
81 If there is no matching entry, TCL_ERROR is returned and an error mes‐
83 sage is left in interp's result if interp is not NULL. Msg is included
84 in the error message to indicate what was being looked up. For exam‐
85 ple, if msg is option the error message will have a form like “bad
86 option "firt": must be first, second, or third”.
87 If Tcl_GetIndexFromObj completes successfully it modifies the internal
89 representation of objPtr to hold the address of the table and the index
90 of the matching entry. If Tcl_GetIndexFromObj is invoked again with
91 the same objPtr and tablePtr arguments (e.g. during a reinvocation of a
92 Tcl command), it returns the matching index immediately without having
93 to redo the lookup operation. Note: Tcl_GetIndexFromObj assumes that
94 the entries in tablePtr are static: they must not change between invo‐
95 cations. If the value of objPtr is the empty string, Tcl_GetIndexFro‐
96 mObj will treat it as a non-matching value and return TCL_ERROR.
97 Tcl_GetIndexFromObjStruct works just like Tcl_GetIndexFromObj, except
99 that instead of treating tablePtr as an array of string pointers, it
100 treats it as a pointer to the first string in a series of strings that
101 have offset bytes between them (i.e. that there is a pointer to the
102 first array of characters at tablePtr, a pointer to the second array of
103 characters at tablePtr+offset bytes, etc.) This is particularly useful
104 when processing things like Tk_ConfigurationSpec, whose string keys are
105 in the same place in each of several array elements.
106
109 Tcl_WrongNumArgs
110
113 index, object, table lookup
114Tcl 8.1 Tcl_GetIndexFromObj(3)