CLASS

tcl.lang.TclIndex -- This class provides an efficient way to match a string with a predefined array of strings.

EXTENDS

tcl.lang.InternalRep

METHODS

static int get(Interp interp, TclObject tobj, String table[], String msg, int flags) throws TclException

ARGUMENTS

DESCRIPTION

get

EXAMPLE

EQUIVALENT C FUNCTIONS

SEE ALSO

KEYWORDS

CLASS

EXTENDS

METHODS

static int get(Interp interp, TclObject tobj, String table[], String msg, int flags) throws TclException

ARGUMENTS

Interp interp ()

If an error occurs while converting tobj to a string object, an error message is left in the interpreter's result object unless interp is NULL.

TclObject tobj ()

TclObject containing the String to compare to those of table[]. If the internal representation of tobj is not TclString, the method attempts to convert it to TclString.

String table[] ()

Table of strings to compare against the string internal to tobj.

String msg ()

If an error occurs, msg is included in the error message to indicate what was being looked up.

int flags ()

If TCL.EXACT flag is specified, only exact matches are accepted. Otherwise, matches include unique abbreviations.

DESCRIPTION

get

The get method compares the internal string value of tobj against each of the strings in table to find a match. A match occurs if tobj's string value is identical to one of the strings in table, or if it is a unique abbreviation for exactly one of the strings in table and the TCL.EXACT flag was not specified.

If a match is made, the index of the matching entry is returned, and the internal representation of tobj is modified to hold the address of table and the index of the matching entry. If TclIndex.get() is invoked again with the same tobj and table arguments (e.g. during a re-invocation of a Tcl command), it returns the matching index immediately without having to redo the lookup operation.

If there is no matching entry, a TclException is thrown, and an error message is left in interp's result if interp isn't NULL. The msg argument is included in the error message to indicate what kind of data that was being looked up.

EXAMPLE

Suppose the foo command requires the use of one of the options in the following array of strings:

static final private String opts[] = {
	"first",
	"second",
	"third"
};

When a call is made to foo, we use the get method to find out which option was specified in the first argument to the foo command,argv[1]:

int opt = TclIndex.get(interp, argv[1], opts, "option", 0);

If argv[1]'s internal string representation is either "second", "sec", or "s" a match is made. However, if argv[1]'s internal string representation is "scd", no match is made, and the get method generates the following error message:

bad option "scd": must be first, second, or third.

EQUIVALENT C FUNCTIONS

SEE ALSO

KEYWORDS

Copyright © 1996-1998 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.