dict.h

00001 /*
00002 # This file is Copyright 2003, 2006, 2007, 2009 Dean Hall.
00003 #
00004 # This file is part of the PyMite VM.
00005 # The PyMite VM is free software: you can redistribute it and/or modify
00006 # it under the terms of the GNU GENERAL PUBLIC LICENSE Version 2.
00007 #
00008 # The PyMite VM is distributed in the hope that it will be useful,
00009 # but WITHOUT ANY WARRANTY; without even the implied warranty of
00010 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00011 # A copy of the GNU GENERAL PUBLIC LICENSE Version 2
00012 # is seen in the file COPYING in this directory.
00013 */
00014 
00015 
00016 #ifndef __DICT_H__
00017 #define __DICT_H__
00018 
00019 
00020 /**
00021  * \file
00022  * \brief Dict Object Type
00023  *
00024  * Dict object type header.
00025  */
00026 
00027 
00028 /**
00029  * Dict
00030  *
00031  * Contains ptr to two seglists,
00032  * one for keys, the other for values;
00033  * and a length, the number of key/value pairs.
00034  */
00035 typedef struct PmDict_s
00036 {
00037     /** object descriptor */
00038     PmObjDesc_t od;
00039     /** number of key,value pairs in the dict */
00040     int16_t length;
00041     /** ptr to seglist containing keys */
00042     pSeglist_t d_keys;
00043     /** ptr to seglist containing values */
00044     pSeglist_t d_vals;
00045 } PmDict_t,
00046  *pPmDict_t;
00047 
00048 
00049 /**
00050  * Clears the contents of a dict.
00051  * after this operation, the dict should in the same state
00052  * as if it were just created using dict_new().
00053  *
00054  * @param   pdict ptr to dict to clear.
00055  * @return  nothing
00056  */
00057 PmReturn_t dict_clear(pPmObj_t pdict);
00058 
00059 /**
00060  * Gets the value in the dict using the given key.
00061  *
00062  * @param   pdict ptr to dict to search
00063  * @param   pkey ptr to key obj
00064  * @param   r_pobj Return; addr of ptr to obj
00065  * @return  Return status
00066  */
00067 PmReturn_t dict_getItem(pPmObj_t pdict, pPmObj_t pkey, pPmObj_t *r_pobj);
00068 
00069 #ifdef HAVE_DEL
00070 /**
00071  * Removes a key and value from the dict.
00072  * Throws TypeError if pdict is not a dict.
00073  * Throws KeyError if pkey does not exist in pdict.
00074  *
00075  * @param   pdict Ptr to dict to search
00076  * @param   pkey Ptr to key obj
00077  * @return  Return status
00078  */
00079 PmReturn_t dict_delItem(pPmObj_t pdict, pPmObj_t pkey);
00080 #endif /* HAVE_DEL */
00081 
00082 /**
00083  * Allocates space for a new Dict.
00084  * Return a pointer to the dict by reference.
00085  *
00086  * @param   r_pdict Return; Addr of ptr to dict
00087  * @return  Return status
00088  */
00089 PmReturn_t dict_new(pPmObj_t *r_pdict);
00090 
00091 /**
00092  * Sets a value in the dict using the given key.
00093  *
00094  * If the dict already contains a matching key, the value is
00095  * replaced; otherwise the new key,val pair is inserted
00096  * at the front of the dict (for fast lookup).
00097  * In the later case, the length of the dict is incremented.
00098  *
00099  * @param   pdict ptr to dict in which (key,val) will go
00100  * @param   pkey ptr to key obj
00101  * @param   pval ptr to val obj
00102  * @return  Return status
00103  */
00104 PmReturn_t dict_setItem(pPmObj_t pdict, pPmObj_t pkey, pPmObj_t pval);
00105 
00106 #ifdef HAVE_PRINT
00107 /**
00108  * Prints out a dict. Uses obj_print() to print elements.
00109  *
00110  * @param pobj Object to print.
00111  * @return Return status
00112  */
00113 PmReturn_t dict_print(pPmObj_t pdict);
00114 #endif /* HAVE_PRINT */
00115 
00116 /**
00117  * Updates the destination dict with the key,value pairs from the source dict
00118  *
00119  * @param   pdestdict ptr to destination dict in which key,val pairs will go
00120  * @param   psourcedict ptr to source dict which has all key,val pairs to copy
00121  * @return  Return status
00122  */
00123 PmReturn_t dict_update(pPmObj_t pdestdict, pPmObj_t psourcedict);
00124 
00125 #endif /* __DICT_H__ */