Tcl\_GetIndexFromObj(3) Tcl Library Procedures Tcl\_GetIndexFromObj(3)

```

```

# [NAME](#NAME)

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

# [SYNOPSIS](#SYNOPSIS)

```
#include <tcl.h>

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

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

# [ARGUMENTS](#ARGUMENTS)

Tcl\_Interp *\*interp* (in)

Interpreter to use for error reporting; if NULL, then no message is provided on errors.

Tcl\_Obj *\*objPtr* (in/out)

The string value of this value is used to search through *tablePtr*. If the **TCL\_INDEX\_TEMP\_TABLE** flag is not specified, the internal representation is modified to hold the index of the matching table entry.

const char \*const *\*tablePtr* (in)

An array of null-terminated strings. The end of the array is marked by a NULL string pointer. Note that, unless the **TCL\_INDEX\_TEMP\_TABLE** flag is specified, references to the *tablePtr* may be retained in the internal representation of *objPtr*, so this should represent the address of a statically-allocated array.

const void *\*structTablePtr* (in)

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*. Note that, unless the **TCL\_INDEX\_TEMP\_TABLE** flag is specified, references to the *structTablePtr* may be retained in the internal representation of *objPtr*, so this should represent the address of a statically-allocated array of structures.

int *offset* (in)

The offset to add to structTablePtr to get to the next entry. The end of the array is marked by a NULL string pointer.

const char *\*msg* (in)

Null-terminated string describing what is being looked up, such as **option**. This string is included in error messages.

int *flags* (in)

OR-ed combination of bits providing additional information for operation. The only bits that are currently defined are **TCL\_EXACT** , **TCL\_INDEX\_TEMP\_TABLE**, and **TCL\_NULL\_OK**.

enum|char|short|int|long *\*indexPtr* (out)

If not (int \*)NULL, the index of the string in *tablePtr* that matches the value of *objPtr* is returned here. The variable can be any integer type, signed or unsigned, char, short, long or long long. It can also be an enum.

```
    
```

# [DESCRIPTION](#DESCRIPTION)

These procedures provide an efficient way for looking up keywords, switch names, option names, and similar things where the literal value of a Tcl value must be chosen from a predefined set. **Tcl\_GetIndexFromObj** compares *objPtr* 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 **TCL\_OK** is returned. If *indexPtr* is not NULL the index of the matching entry is stored at *\*indexPtr*.

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 “**bad option "firt": must be first, second, or third**”.

If the **TCL\_INDEX\_TEMP\_TABLE** was not specified, when **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 that **Tcl\_GetIndexFromObj** assumes that the entries in *tablePtr* are static: they must not change between invocations. This caching mechanism can be disallowed by specifying the **TCL\_INDEX\_TEMP\_TABLE** flag. If the **TCL\_NULL\_OK** flag was specified, objPtr is allowed to be NULL or the empty string. The resulting index is -1. Otherwise, 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.

# [REFERENCE COUNT MANAGEMENT](#REFERENCE_COUNT_MANAGEMENT)

**Tcl\_GetIndexFromObj** and **Tcl\_GetIndexFromObjStruct** do not modify the reference count of their *objPtr* arguments; they only read. Note however that these functions may set the interpreter result; if that is the only place that is holding a reference to the object, it will be deleted.

# [SEE ALSO](#SEE_ALSO)

[prefix(n)](/man/os/tcl/prefix.n), [Tcl\_WrongNumArgs(3)](/man/os/tcl/Tcl_WrongNumArgs.3)

# [KEYWORDS](#KEYWORDS)

index, option, value, table lookup

8.1 Tcl

---

Document: Tcl_GetIndexFromObj(3) from tcl 9.1.0-r0 (Chainguard OS)
Source: https://downloads.sourceforge.net/project/tcl/Tcl/9.1.0/tcl9.1.0-src.tar.gz