flight/libraries/PyMite/vm/dict.h

   1 /*
   2 # This file is Copyright 2003, 2006, 2007, 2009, 2010 Dean Hall.
   3 #
   4 # This file is part of the PyMite VM.
   5 # The PyMite VM is free software: you can redistribute it and/or modify
   6 # it under the terms of the GNU GENERAL PUBLIC LICENSE Version 2.
   7 #
   8 # The PyMite VM is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  11 # A copy of the GNU GENERAL PUBLIC LICENSE Version 2
  12 # is seen in the file COPYING in this directory.
  13 */
  14
  15
  16 #ifndef __DICT_H__
  17 #define __DICT_H__
  18
  19
  20 /**
  21  * \file
  22  * \brief Dict Object Type
  23  *
  24  * Dict object type header.
  25  */
  26
  27
  28 /**
  29  * Dict
  30  *
  31  * Contains ptr to two seglists,
  32  * one for keys, the other for values;
  33  * and a length, the number of key/value pairs.
  34  */
  35 typedef struct PmDict_s
  36 {
  37     /** object descriptor */
  38     PmObjDesc_t od;
  39     /** number of key,value pairs in the dict */
  40     int16_t length;
  41     /** ptr to seglist containing keys */
  42     pSeglist_t d_keys;
  43     /** ptr to seglist containing values */
  44     pSeglist_t d_vals;
  45 } PmDict_t,
  46  *pPmDict_t;
  47
  48
  49 /**
  50  * Clears the contents of a dict.
  51  * after this operation, the dict should in the same state
  52  * as if it were just created using dict_new().
  53  *
  54  * @param   pdict ptr to dict to clear.
  55  * @return  nothing
  56  */
  57 PmReturn_t dict_clear(pPmObj_t pdict);
  58
  59 /**
  60  * Gets the value in the dict using the given key.
  61  *
  62  * @param   pdict ptr to dict to search
  63  * @param   pkey ptr to key obj
  64  * @param   r_pobj Return; addr of ptr to obj
  65  * @return  Return status
  66  */
  67 PmReturn_t dict_getItem(pPmObj_t pdict, pPmObj_t pkey, pPmObj_t *r_pobj);
  68
  69 #ifdef HAVE_DEL
  70 /**
  71  * Removes a key and value from the dict.
  72  * Throws TypeError if pdict is not a dict.
  73  * Throws KeyError if pkey does not exist in pdict.
  74  *
  75  * @param   pdict Ptr to dict to search
  76  * @param   pkey Ptr to key obj
  77  * @return  Return status
  78  */
  79 PmReturn_t dict_delItem(pPmObj_t pdict, pPmObj_t pkey);
  80 #endif /* HAVE_DEL */
  81
  82 /**
  83  * Allocates space for a new Dict.
  84  * Return a pointer to the dict by reference.
  85  *
  86  * @param   r_pdict Return; Addr of ptr to dict
  87  * @return  Return status
  88  */
  89 PmReturn_t dict_new(pPmObj_t *r_pdict);
  90
  91 /**
  92  * Sets a value in the dict using the given key.
  93  *
  94  * If the dict already contains a matching key, the value is
  95  * replaced; otherwise the new key,val pair is inserted
  96  * at the front of the dict (for fast lookup).
  97  * In the later case, the length of the dict is incremented.
  98  *
  99  * @param   pdict ptr to dict in which (key,val) will go
 100  * @param   pkey ptr to key obj
 101  * @param   pval ptr to val obj
 102  * @return  Return status
 103  */
 104 PmReturn_t dict_setItem(pPmObj_t pdict, pPmObj_t pkey, pPmObj_t pval);
 105
 106 #ifdef HAVE_PRINT
 107 /**
 108  * Prints out a dict. Uses obj_print() to print elements.
 109  *
 110  * @param pobj Object to print.
 111  * @return Return status
 112  */
 113 PmReturn_t dict_print(pPmObj_t pdict);
 114 #endif /* HAVE_PRINT */
 115
 116 /**
 117  * Updates the destination dict with the key,value pairs from the source dict
 118  *
 119  * @param   pdestdict ptr to destination dict in which key,val pairs will go
 120  * @param   psourcedict ptr to source dict which has all key,val pairs to copy
 121  * @return  Return status
 122  */
 123 PmReturn_t dict_update(pPmObj_t pdestdict, pPmObj_t psourcedict);
 124
 125 #endif /* __DICT_H__ */