TclJava Library Procedures - TclIndex manual page

  CLASS
    tcl.lang.TclIndex -- This class provides an efficient way to match a string with a predefined array of strings.
  IMPLEMENTS
    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

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

### IMPLEMENTS

tcl.lang.InternalRep

### 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

The TclIndex class provides an efficient way to look up keywords, switch names, option names, and similar things where the value of an object must be one of a predefined set of values. We commonly use this class to identify the subcommand or switch of a Tcl command.

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

Tcl_GetIndexFromObj

### SEE ALSO

InternalRep, TclObject, TclString, TclInteger, createCmd, TclException

### KEYWORDS

index, internal representation, object, object type, string, exception

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