Unix/Linux Go Back    


CentOS 7.0 - man page for tcl_dictobjnext (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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_DictObjRe-
       moveKeyList - manipulate Tcl objects 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 an object
						  to be a dictionary object, an error message  is
						  left	in the interpreter's result object unless
						  interp is NULL.

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

       Tcl_Obj *keyPtr (in)			  Points  to the key for the key/value pair being
						  manipulated within the dictionary object.

       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  inter-
						  ested in the key.

       Tcl_Obj *valuePtr (in)			  Points  to  the  value  for  the key/value pair
						  being manipulate within the  dictionary  object
						  (or  sub-object,  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 dictio-
						  nary 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  terminated  before
						  all	values	 in   the  dictionary  have  been
						  returned, the search record must be  passed  to
						  Tcl_DictObjDone to enable the internal 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  com-
						  pleted, and a zero otherwise.

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

       Tcl_Obj *const *keyv (in)		  Array of keyc pointers to objects that Tcl_Dic-
						  tObjPutKeyList   and	 Tcl_DictObjRemoveKeyList
						  will use to locate the key/value pair to manip-
						  ulate  within  the sub-dictionaries of the main
						  dictionary object passed to them.
_________________________________________________________________

DESCRIPTION
       Tcl dictionary objects have an internal representation  that  supports  efficient  mapping
       from  keys  to values and which guarantees that the particular 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 objects from C code.

       Tcl_NewDictObj creates a new, empty dictionary object.  The string representation  of  the
       object will be invalid, and the reference count of the object 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 variable 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  con-
       verted 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 dictionary.

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

       Tcl_DictObjFirst  commences  an iteration across all the key/value pairs in the given dic-
       tionary, placing the key and value in the variables pointed to by the keyPtrPtr	and  val-
       uePtrPtr  arguments (which may be NULL to indicate that the caller is uninterested in they
       key or variable 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  termination 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 argument points to a variable that is updated to be zero
       of  there are further 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 can-
       not  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 dictio-
       nary is modified during the iteration. Because of this, once the iteration over a  dictio-
       nary's  keys has finished (whether because all values have been iterated over as indicated
       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  par-
       ticular	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 respectively, 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 argu-
       ments 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_DictObjPutKeyList, 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
		   * objects 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 object, dictionary, dictionary object, hash table, iteration, object

Tcl					       8.5				   Tcl_DictObj(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:03 PM.