Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tcl_GetIndexFromObj(3)	    Tcl	Library	Procedures	Tcl_GetIndexFromObj(3)


       Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct -	lookup string in table
       of keywords

       #include	<tcl.h>

       Tcl_GetIndexFromObj(interp, objPtr, tablePtr, msg, flags,

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

       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  ob-
						ject is	used to	search through
						tablePtr.  The internal	repre-
						sentation  is modified to hold
						the index of the matching  ta-
						ble entry.

       const char **tablePtr (in)		An  array  of  null-terminated
						strings.  The end of the array
						is  marked  by	a  NULL	string
						pointer.  Note that references
						to  the	 tablePtr  may	be re-
						tained in the internal	repre-
						sentation  of  objPtr, so this
						should represent  the  address
						of  a statically-allocated ar-

       const void *structTablePtr (in)		An array  of  arbitrary	 type,
						typically  some	 struct	 type.
						The first member of the	struc-
						ture must be a null-terminated
						string.	  The  size   of   the
						structure  is given by offset.
						Note that  references  to  the
						structTablePtr may be retained
						in the internal	representation
						of objPtr, so this should rep-
						resent the address of a	stati-
						cally-allocated	   array    of

       int offset (in)				The offset to add  to  struct-
						TablePtr  to  get  to the next
						entry.	The end	of  the	 array
						is  marked  by	a  NULL	string

       const char *msg (in)			Null-terminated	  string   de-
						scribing  what is being	looked
						up,  such  as  option.	  This
						string	is  included  in error

       int flags (in)				OR-ed combination of bits pro-
						viding	additional information
						for operation.	The  only  bit
						that  is  currently defined is

       int *indexPtr (out)			The index  of  the  string  in
						tablePtr   that	  matches  the
						value of  objPtr  is  returned

       These  procedures  provide  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.  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 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 mes-
       sage 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 exam-
       ple, if msg is option the error message will have a form	like "bad  op-
       tion "firt": must be first, second, or third".

       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 invo-
       cations.	 If the	value of objPtr	is the empty string,  Tcl_GetIndexFro-
       mObj 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.


       index, object, table lookup

Tcl				      8.1		Tcl_GetIndexFromObj(3)


Want to link to this manual page? Use this URL:

home | help