Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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
       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 dic-tionary dictionary
                                                  tionary object, an error message is  left  in  the  inter-preter's interpreter's
                                                  preter's result object unless interp is NULL.

       Tcl_Obj *dictPtr (in/out)                  Points  to  the  dictionary  object to be manipulated.  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 interested in the key.

       Tcl_Obj *valuePtr (in)                     Points to the value for the key/value pair  being  manipu-late manipulate
                                                  late  within  the dictionary object (or sub-object, in the
                                                  case of Tcl_DictObjPutKeyList.)

       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 enu-merating enumerating
                                                  merating all key/value pairs in a  dictionary.   The  con-tents contents
                                                  tents  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 writ-ten written
                                                  ten into it when the enumeration of the key/value pairs in
                                                  a dictionary has completed, and a zero otherwise.

       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  objects  that   Tcl_DictOb-jPutKeyList Tcl_DictObjPutKeyList
                                                  jPutKeyList   and  Tcl_DictObjRemoveKeyList  will  use  to
                                                  locate the key/value pair to manipulate  within  the  sub-dictionaries subdictionaries
                                                  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 dictio-nary dictionary
       nary 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 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 con-verted converted
       verted 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 dictionary, plac-ing placing
       ing  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 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  dictio-nary dictionary
       nary  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 cannot be converted to a  dic-tionary, dictionary,
       tionary,  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 iteration. Because of this, once the iteration over a dictionary'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 particular searchPtr is passed to Tcl_DictObjDone, passing it to  Tcl_DictOb-jNext Tcl_DictObjNext
       jNext  (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_Dic-tObjPut Tcl_DictObjPut
       tObjPut 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 val-ues values
       ues 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 corre-sponding corresponding
       sponding 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)