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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct -	lookup string in table
       of keywords

SYNOPSIS
       #include	<tcl.h>

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

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

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_IN-
						DEX_TEMP_TABLE	 flag  is  not
						specified, the internal	repre-
						sentation is modified to  hold
						the  index of the matching ta-
						ble 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 rep-
						resent the address of a	stati-
						cally-allocated	array.

       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, unless the  TCL_IN-
						DEX_TEMP_TABLE	flag is	speci-
						fied,	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
						structures.

       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
						pointer.

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

       int flags (in)				OR-ed combination of bits pro-
						viding additional  information
						for  operation.	 The only bits
						that are currently defined are
						TCL_EXACT , TCL_INDEX_TEMP_TA-
						BLE, 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
       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_GetIndexFro-
       mObj 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 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 the TCL_INDEX_TEMP_TABLE was not specified, when Tcl_GetIndexFromObj
       completes successfully it modifies the internal representation  of  ob-
       jPtr to hold the	address	of the table and the index of the matching en-
       try.   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  en-
       tries in	tablePtr are static: they must not change between invocations.
       This  caching  mechanism	 can  be  disallowed by	specifying the TCL_IN-
       DEX_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_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.

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
       prefix(n), Tcl_WrongNumArgs(3)

KEYWORDS
       index, option, value, table lookup

Tcl				      8.1		Tcl_GetIndexFromObj(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_GetIndexFromObjStruct.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help