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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       Tcl_NewDictObj,	 Tcl_DictObjPut,   Tcl_DictObjGet,  Tcl_DictObjRemove,
       Tcl_DictObjSize,	 Tcl_DictObjFirst,  Tcl_DictObjNext,  Tcl_DictObjDone,
       Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList - manipulate Tcl	values
       as dictionaries

SYNOPSIS
       #include	<tcl.h>

       Tcl_Obj *
       Tcl_NewDictObj()

       int
       Tcl_DictObjGet(interp, dictPtr, keyPtr, valuePtrPtr)

       int
       Tcl_DictObjPut(interp, dictPtr, keyPtr, valuePtr)

       int
       Tcl_DictObjRemove(interp, dictPtr, keyPtr)

       int
       Tcl_DictObjSize(interp, dictPtr,	sizePtr)

       int
       Tcl_DictObjFirst(interp,	dictPtr, searchPtr,
			keyPtrPtr, valuePtrPtr,	donePtr)

       void
       Tcl_DictObjNext(searchPtr, keyPtrPtr, valuePtrPtr, donePtr)

       void
       Tcl_DictObjDone(searchPtr)

       int
       Tcl_DictObjPutKeyList(interp, dictPtr, keyc, keyv, valuePtr)

       int
       Tcl_DictObjRemoveKeyList(interp,	dictPtr, keyc, keyv)

ARGUMENTS
       Tcl_Interp *interp (in)			  If  an  error	 occurs	 while
						  converting  a	 value to be a
						  dictionary value,  an	 error
						  message  is  left in the in-
						  terpreter's result value un-
						  less interp is NULL.

       Tcl_Obj *dictPtr	(in/out)		  Points   to  the  dictionary
						  value	to be manipulated.  If
						  dictPtr   does  not  already
						  point	to a dictionary	value,
						  an  attempt  will be made to
						  convert it to	one.

       Tcl_Obj *keyPtr (in)			  Points to the	 key  for  the
						  key/value pair being manipu-
						  lated	within the  dictionary
						  value.

       Tcl_Obj **keyPtrPtr (out)		  Points  to  a	 variable that
						  will have  the  key  from  a
						  key/value pair placed	within
						  it.  May be NULL to indicate
						  that	the  caller is not in-
						  terested in the key.

       Tcl_Obj *valuePtr (in)			  Points to the	value for  the
						  key/value pair being manipu-
						  lated	within the  dictionary
						  value	 (or sub-value,	in the
						  case	   of	   Tcl_DictOb-
						  jPutKeyList.)

       Tcl_Obj **valuePtrPtr (out)		  Points  to  a	 variable that
						  will have the	value  from  a
						  key/value pair placed	within
						  it.	For   Tcl_DictObjFirst
						  and	Tcl_DictObjNext,  this
						  may be NULL to indicate that
						  the caller is	not interested
						  in the value.

       int *sizePtr (out)			  Points to  a	variable  that
						  will	 have  the  number  of
						  key/value  pairs   contained
						  within the dictionary	placed
						  within it.

       Tcl_DictSearch *searchPtr (in/out)	  Pointer to record to use  to
						  keep	track  of  progress in
						  enumerating  all   key/value
						  pairs	 in a dictionary.  The
						  contents of the record  will
						  be  initialized  by the call
						  to Tcl_DictObjFirst.	If the
						  enumerating  is to be	termi-
						  nated	before all  values  in
						  the dictionary have been re-
						  turned,  the	search	record
						  must be passed to Tcl_DictO-
						  bjDone to enable the	inter-
						  nal locks to be released.

       int *donePtr (out)			  Points  to  a	 variable that
						  will have a  non-zero	 value
						  written  into	 it  when  the
						  enumeration of the key/value
						  pairs	 in  a	dictionary has
						  completed, and a zero	other-
						  wise.

       int keyc	(in)				  Indicates the	number of keys
						  that will be supplied	in the
						  keyv array.

       Tcl_Obj *const *keyv (in)		  Array	 of  keyc  pointers to
						  values   that	   Tcl_DictOb-
						  jPutKeyList  and Tcl_DictOb-
						  jRemoveKeyList will  use  to
						  locate the key/value pair to
						  manipulate within  the  sub-
						  dictionaries	 of  the  main
						  dictionary value  passed  to
						  them.
______________________________________________________________________________

DESCRIPTION
       Tcl dictionary values have an internal representation that supports ef-
       ficient mapping from keys to values and which guarantees	that the  par-
       ticular	ordering of keys within	the dictionary remains the same	modulo
       any keys	being deleted (which removes them from	the  order)  or	 added
       (which  adds them to the	end of the order). If reinterpreted as a list,
       the values at the even-valued indices in	the list will be the  keys  of
       the  dictionary,	and each will be followed (in the odd-valued index) by
       the value associated with that key.

       The procedures described	in this	man page are used to  create,  modify,
       index, and iterate over dictionary values from C	code.

       Tcl_NewDictObj  creates a new, empty dictionary value.  The string rep-
       resentation of the value	will be	invalid, and the  reference  count  of
       the value will be zero.

       Tcl_DictObjGet  looks  up the given key within the given	dictionary and
       writes a	pointer	to the value associated	with that key into  the	 vari-
       able  pointed  to  by  valuePtrPtr, or a	NULL if	the key	has no mapping
       within the dictionary.  The result of  this  procedure  is  TCL_OK,  or
       TCL_ERROR if the	dictPtr	cannot be converted to a dictionary.

       Tcl_DictObjPut  updates the given dictionary so that the	given key maps
       to the given value; any key may exist at	most once  in  any  particular
       dictionary.   The  dictionary must not be shared, but the key and value
       may be.	This procedure may increase the	reference count	 of  both  key
       and  value if it	proves necessary to store them.	 Neither key nor value
       should be NULL.	The result of this procedure is	TCL_OK,	 or  TCL_ERROR
       if the dictPtr cannot be	converted to a dictionary.

       Tcl_DictObjRemove  updates  the	given dictionary so that the given key
       has no mapping to any value.  The dictionary must not  be  shared,  but
       the  key	 may  be.  The key actually stored in the dictionary will have
       its reference count decremented if it was present.  It is not an	 error
       if  the	key did	not previously exist.  The result of this procedure is
       TCL_OK, or TCL_ERROR if the dictPtr cannot be converted	to  a  dictio-
       nary.

       Tcl_DictObjSize updates the given variable with the number of key/value
       pairs currently in the given dictionary.	The result of  this  procedure
       is TCL_OK, or TCL_ERROR if the dictPtr cannot be	converted to a dictio-
       nary.

       Tcl_DictObjFirst	commences an iteration across all the key/value	 pairs
       in  the	given  dictionary,  placing the	key and	value in the variables
       pointed to by the keyPtrPtr and valuePtrPtr  arguments  (which  may  be
       NULL  to	 indicate that the caller is uninterested in they key or vari-
       able respectively.)  The	next key/value pair in the dictionary  may  be
       retrieved with Tcl_DictObjNext.	Concurrent updates of the dictionary's
       internal	representation will not	modify the iteration processing	unless
       the  dictionary	is unshared, when this will trigger premature termina-
       tion of the iteration instead (which Tcl	scripts	cannot trigger via the
       dict  command.)	 The  searchPtr	 argument points to a piece of context
       that is used to identify	which particular iteration is being performed,
       and  is initialized by the call to Tcl_DictObjFirst.  The donePtr argu-
       ment points to a	variable that is updated to be zero of there are  fur-
       ther  key/value pairs to	be iterated over, or non-zero if the iteration
       is complete.  The order of iteration is implementation-defined.	If the
       dictPtr	argument cannot	be converted to	a dictionary, Tcl_DictObjFirst
       returns TCL_ERROR and the iteration is not commenced, and otherwise  it
       returns TCL_OK.

       When  Tcl_DictObjFirst is called	upon a dictionary, a lock is placed on
       the dictionary to enable	that dictionary	to  be	iterated  over	safely
       without regard for whether the dictionary is modified during the	itera-
       tion. Because of	this, once the iteration over a	dictionary's keys  has
       finished	 (whether  because all values have been	iterated over as indi-
       cated by	the variable indicated by the donePtr argument	being  set  to
       one,  or	 because  no  further values are required) the Tcl_DictObjDone
       function	must be	called with  the  same	searchPtr  as  was  passed  to
       Tcl_DictObjFirst	 so  that  the	internal locks can be released.	Once a
       particular searchPtr  is	 passed	 to  Tcl_DictObjDone,  passing	it  to
       Tcl_DictObjNext	(without  first	initializing it	with Tcl_DictObjFirst)
       will result in no values	being produced and the variable	pointed	to  by
       donePtr	being set to one.  It is safe to call Tcl_DictObjDone multiple
       times on	the same searchPtr for each call to Tcl_DictObjFirst.

       The procedures Tcl_DictObjPutKeyList and	 Tcl_DictObjRemoveKeyList  are
       the  close  analogues  of  Tcl_DictObjPut and Tcl_DictObjRemove respec-
       tively, except that instead of working with a single  dictionary,  they
       are  designed  to  operate on a nested tree of dictionaries, with inner
       dictionaries stored as values inside outer dictionaries.	 The keyc  and
       keyv  arguments specify a list of keys (with outermost keys first) that
       acts as a path to the key/value pair to be affected.  Note  that	 there
       is no corresponding operation for reading a value for a path as this is
       easy to construct from repeated use of Tcl_DictObjGet. With Tcl_DictOb-
       jPutKeyList,  nested  dictionaries  are	created	 for non-terminal keys
       where they do not already  exist.  With	Tcl_DictObjRemoveKeyList,  all
       non-terminal keys must exist and	have dictionaries as their values.

EXAMPLE
       Using  the  dictionary iteration	interface to search determine if there
       is a key	that maps to itself:

	      Tcl_DictSearch search;
	      Tcl_Obj *key, *value;
	      int done;

	      /*
	       * Assume	interp and objPtr are parameters.  This	is the
	       * idiomatic way to start	an iteration over the dictionary; it
	       * sets a	lock on	the internal representation that ensures that
	       * there are no concurrent modification issues when normal
	       * reference count management is also used.  The lock is
	       * released automatically	when the loop is finished, but must
	       * be released manually when an exceptional exit from the	loop
	       * is performed. However it is safe to try to release the	lock
	       * even if we've finished	iterating over the loop.
	       */
	      if (Tcl_DictObjFirst(interp, objPtr, &search,
		      &key, &value, &done) != TCL_OK) {
		  return TCL_ERROR;
	      }
	      for (; !done ; Tcl_DictObjNext(&search, &key, &value, &done)) {
		  /*
		   * Note that strcmp()	is not a good way of comparing
		   * values and	is just	used here for demonstration
		   * purposes.
		   */
		  if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
		      break;
		  }
	      }
	      Tcl_DictObjDone(&search);
	      Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
	      return TCL_OK;

SEE ALSO
       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable

KEYWORDS
       dict, dict value, dictionary, dictionary	value, hash table,  iteration,
       value

Tcl				      8.5			Tcl_DictObj(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | EXAMPLE | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_DictObjDone.tcl87&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help