---
name: "GetIndex"
section: "3"
platform: "macos"
package: "tcl"
version: "152"
release: "macOS 26.5"
platforms: ["macos"]
url: "https://new.carta.tech/GetIndex"
---

# GetIndex(3)

lookup string in table of keywords

## NAME

Tcl\_GetIndexFromObj, Tcl\_GetIndexFromObjStruct - lookup string in table of keywords

## SYNOPSIS

```
#include <tcl.h>

int
Tcl_GetIndexFromObj(interp, objPtr, tablePtr, msg, flags,
indexPtr)

int
Tcl_GetIndexFromObjStruct(interp, objPtr, structTablePtr, offset,
                          msg, flags, indexPtr)
```

## ARGUMENTS

Interpreter to use for error reporting; if NULL, then no message is provided on errors. The string value of this object is used to search through *tablePtr*. The internal representation is modified to hold the index of the matching table entry. An array of null-terminated strings.  The end of the array is marked by a NULL string pointer. An array of arbitrary type, typically some **struct** type. The first member of the structure must be a null-terminated string. The size of the structure is given by *offset*. The offset to add to structTablePtr to get to the next entry. The end of the array is marked by a NULL string pointer. Null-terminated string describing what is being looked up, such as **option**.  This string is included in error messages. OR-ed combination of bits providing additional information for operation.  The only bit that is currently defined is **TCL\_EXACT**. The index of the string in *tablePtr* that matches the value of *objPtr* is returned here.

## DESCRIPTION

This procedure provides an efficient way for looking up keywords, switch names, option names, and similar things where the value of an object must be one of a predefined set of values. *ObjPtr* is compared against each of the strings in *tablePtr* to find a match.  A match occurs if *objPtr*'s string value is identical to one of the strings in *tablePtr*, or if it is a non-empty unique abbreviation for exactly one of the strings in *tablePtr* and the **TCL\_EXACT** flag was not specified; in either case the index of the matching entry is stored at *\*indexPtr* and **TCL\_OK** is returned.

If there is no matching entry, **TCL\_ERROR** is returned and an error message is left in *interp*'s result if *interp* is not NULL.  *Msg* is included in the error message to indicate what was being looked up.  For example, if *msg* is **option** the error message will have a form like

If **Tcl\_GetIndexFromObj** completes successfully it modifies the internal representation of *objPtr* to hold the address of the table and the index of the matching entry.  If **Tcl\_GetIndexFromObj** is invoked again with the same *objPtr* and *tablePtr* arguments (e.g. during a reinvocation of a Tcl command), it returns the matching index immediately without having to redo the lookup operation.  Note: **Tcl\_GetIndexFromObj** assumes that the entries in *tablePtr* are static: they must not change between invocations.  If the value of *objPtr* is the empty string, **Tcl\_GetIndexFromObj** will treat it as a non-matching value and return **TCL\_ERROR**.

**Tcl\_GetIndexFromObjStruct** works just like **Tcl\_GetIndexFromObj**, except that instead of treating *tablePtr* as an array of string pointers, it treats it as a pointer to the first string in a series of strings that have *offset* bytes between them (i.e. that there is a pointer to the first array of characters at *tablePtr*, a pointer to the second array of characters at *tablePtr*+*offset* bytes, etc.) This is particularly useful when processing things like **Tk\_ConfigurationSpec**, whose string keys are in the same place in each of several array elements.

## SEE ALSO

Tcl\_WrongNumArgs

## KEYWORDS

index, object, table lookup