DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_NewDictObj(3tcl)




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 dic-
     tionaries


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 con-
                                                verting an object
                                                to  be a diction-
                                                ary  object,   an
                                                error  message is
                                                left    in    the
                                                interpreter's

Tcl                     Last change: 8.5                        1

Tcl_DictObj(3)       Tcl Library Procedures        Tcl_DictObj(3)

                                                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  mani-
                                                pulated    within
                                                the    dictionary
                                                object.

     Tcl_Obj **keyPtrPtr (out)                  Points to a vari-
                                                able   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  manipulate
                                                within  the  dic-
                                                tionary    object
                                                (or   sub-object,
                                                in  the  case  of
                                                Tcl_DictObjPutKeyList.)

     Tcl_Obj **valuePtrPtr (out)                Points to a vari-
                                                able   that  will
                                                have  the   value
                                                from  a key/value
                                                pair       placed
                                                within  it.   For
                                                Tcl_DictObjFirst
                                                and

Tcl                     Last change: 8.5                        2

Tcl_DictObj(3)       Tcl Library Procedures        Tcl_DictObj(3)

                                                Tcl_DictObjNext,
                                                this  may be NULL
                                                to indicate  that
                                                the caller is not
                                                interested in the
                                                value.

     int *sizePtr (out)                         Points to a vari-
                                                able   that  will
                                                have  the  number
                                                of      key/value
                                                pairs   contained
                                                within  the  dic-
                                                tionary    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 dic-
                                                tionary.      The
                                                contents  of  the
                                                record  will   be
                                                initialized    by
                                                the    call    to
                                                Tcl_DictObjFirst.
                                                If the  enumerat-
                                                ing is to be ter-
                                                minated    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 vari-
                                                able   that  will
                                                have  a  non-zero
                                                value     written
                                                into it when  the
                                                enumeration    of
                                                the     key/value
                                                pairs  in  a dic-
                                                tionary has  com-
                                                pleted,   and   a
                                                zero otherwise.

Tcl                     Last change: 8.5                        3

Tcl_DictObj(3)       Tcl Library Procedures        Tcl_DictObj(3)

     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_DictObjPutKeyList
                                                and
                                                Tcl_DictObjRemoveKeyList
                                                will    use    to
                                                locate        the
                                                key/value pair to
                                                manipulate within
                                                the          sub-
                                                dictionaries   of
                                                the main diction-
                                                ary 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  dic-
     tionary  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

Tcl                     Last change: 8.5                        4

Tcl_DictObj(3)       Tcl Library Procedures        Tcl_DictObj(3)

     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 diction-
     ary.

     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  dic-
     tionary.

     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, 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  variable  respec-
     tively.)   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  com-
     mand.)   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 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 diction-
     ary  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                     Last change: 8.5                        5

Tcl_DictObj(3)       Tcl Library Procedures        Tcl_DictObj(3)

     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  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  dic-
     tionaries.  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_DictObjPutKeyList,  nested  dic-
     tionaries 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)) {
              /*

Tcl                     Last change: 8.5                        6

Tcl_DictObj(3)       Tcl Library Procedures        Tcl_DictObj(3)

               * 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                     Last change: 8.5                        7


Man(1) output converted with man2html