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 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 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 re‐
39 tained in the internal repre‐
40 sentation of objPtr, so this
41 should represent the address
42 of a statically-allocated ar‐
43 ray.
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 de‐
66 scribing what is being looked
67 up, such as option. This
68 string is included in error
69 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
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 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 op‐
98 tion "firt": must be first, second, or third”.
99 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 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
120 prefix(n), Tcl_WrongNumArgs(3)
121
123 index, option, value, table lookup
124Tcl 8.1 Tcl_GetIndexFromObj(3)