| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1997 Sun Microsystems, Inc.
|
| 3 |
|
|
'\"
|
| 4 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
| 5 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
| 6 |
|
|
'\"
|
| 7 |
|
|
'\" RCS: @(#) $Id: GetIndex.3,v 1.1.1.1 2002-01-16 10:25:23 markom Exp $
|
| 8 |
|
|
'\"
|
| 9 |
|
|
.so man.macros
|
| 10 |
|
|
.TH Tcl_GetIndexFromObj 3 8.0 Tcl "Tcl Library Procedures"
|
| 11 |
|
|
.BS
|
| 12 |
|
|
.SH NAME
|
| 13 |
|
|
Tcl_GetIndexFromObj \- lookup string in table of keywords
|
| 14 |
|
|
.SH SYNOPSIS
|
| 15 |
|
|
.nf
|
| 16 |
|
|
\fB#include \fR
|
| 17 |
|
|
.sp
|
| 18 |
|
|
int
|
| 19 |
|
|
\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags, indexPtr\fR)
|
| 20 |
|
|
.SH ARGUMENTS
|
| 21 |
|
|
.AS Tcl_Interp **tablePtr
|
| 22 |
|
|
.AP Tcl_Interp *interp in
|
| 23 |
|
|
Interpreter to use for error reporting; if NULL, then no message is
|
| 24 |
|
|
provided on errors.
|
| 25 |
|
|
.AP Tcl_Obj *objPtr in/out
|
| 26 |
|
|
The string value of this object is used to search through \fItablePtr\fR.
|
| 27 |
|
|
The internal representation is modified to hold the index of the matching
|
| 28 |
|
|
table entry.
|
| 29 |
|
|
.AP char **tablePtr in
|
| 30 |
|
|
An array of null-terminated strings. The end of the array is marked
|
| 31 |
|
|
by a NULL string pointer.
|
| 32 |
|
|
.AP char *msg in
|
| 33 |
|
|
Null-terminated string describing what is being looked up, such as
|
| 34 |
|
|
\fBoption\fR. This string is included in error messages.
|
| 35 |
|
|
.AP int flags in
|
| 36 |
|
|
OR-ed combination of bits providing additional information for
|
| 37 |
|
|
operation. The only bit that is currently defined is \fBTCL_EXACT\fR.
|
| 38 |
|
|
.AP int *indexPtr out
|
| 39 |
|
|
The index of the string in \fItablePtr\fR that matches the value of
|
| 40 |
|
|
\fIobjPtr\fR is returned here.
|
| 41 |
|
|
.BE
|
| 42 |
|
|
|
| 43 |
|
|
.SH DESCRIPTION
|
| 44 |
|
|
.PP
|
| 45 |
|
|
This procedure provides an efficient way for looking up keywords,
|
| 46 |
|
|
switch names, option names, and similar things where the value of
|
| 47 |
|
|
an object must be one of a predefined set of values.
|
| 48 |
|
|
\fIObjPtr\fR is compared against each of
|
| 49 |
|
|
the strings in \fItablePtr\fR to find a match. A match occurs if
|
| 50 |
|
|
\fIobjPtr\fR's string value is identical to one of the strings in
|
| 51 |
|
|
\fItablePtr\fR, or if it is a unique abbreviation
|
| 52 |
|
|
for exactly one of the strings in \fItablePtr\fR and the
|
| 53 |
|
|
\fBTCL_EXACT\fR flag was not specified; in either case
|
| 54 |
|
|
the index of the matching entry is stored at \fI*indexPtr\fR
|
| 55 |
|
|
and TCL_OK is returned.
|
| 56 |
|
|
.PP
|
| 57 |
|
|
If there is no matching entry,
|
| 58 |
|
|
TCL_ERROR is returned and an error message is left in \fIinterp\fR's
|
| 59 |
|
|
result if \fIinterp\fR isn't NULL. \fIMsg\fR is included in the
|
| 60 |
|
|
error message to indicate what was being looked up. For example,
|
| 61 |
|
|
if \fImsg\fR is \fBoption\fR the error message will have a form like
|
| 62 |
|
|
\fBbad option "firt": must be first, second, or third\fR.
|
| 63 |
|
|
.PP
|
| 64 |
|
|
If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
|
| 65 |
|
|
internal representation of \fIobjPtr\fR to hold the address of
|
| 66 |
|
|
the table and the index of the matching entry. If \fBTcl_GetIndexFromObj\fR
|
| 67 |
|
|
is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
|
| 68 |
|
|
arguments (e.g. during a reinvocation of a Tcl command), it returns
|
| 69 |
|
|
the matching index immediately without having to redo the lookup
|
| 70 |
|
|
operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
|
| 71 |
|
|
in \fItablePtr\fR are static: they must not change between invocations.
|
| 72 |
|
|
|
| 73 |
|
|
.SH "SEE ALSO"
|
| 74 |
|
|
Tcl_WrongNumArgs
|
| 75 |
|
|
|
| 76 |
|
|
.SH KEYWORDS
|
| 77 |
|
|
index, object, table lookup
|
