list.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 __LIST_H__
00017 #define __LIST_H__
00018 
00019 /**
00020  * \file
00021  * \brief List Object Type
00022  *
00023  * List object type header.
00024  */
00025 
00026 /**
00027  * List obj
00028  *
00029  * Mutable ordered sequence of objects.  Contains ptr to linked list of nodes.
00030  */
00031 typedef struct PmList_s
00032 {
00033     /** Object descriptor */
00034     PmObjDesc_t od;
00035 
00036     /** List length; number of objs linked */
00037     int16_t length;
00038 
00039     /** Ptr to linked list of nodes */
00040     pSeglist_t val;
00041 } PmList_t,
00042  *pPmList_t;
00043 
00044 
00045 /**
00046  * Allocates a new List object.
00047  *
00048  * If there is not enough memory to allocate the List,
00049  * the return status will indicate an OutOfMemoryError
00050  * that must be passed up to the interpreter.
00051  * Otherwise, a ptr to the list is returned by reference
00052  * and the return status is OK.
00053  *
00054  * @param   r_pobj Return; addr of ptr to obj
00055  * @return  Return status
00056  */
00057 PmReturn_t list_new(pPmObj_t *r_pobj);
00058 
00059 /**
00060  * Gets the object in the list at the index.
00061  *
00062  * @param   plist Ptr to list obj
00063  * @param   index Index into list
00064  * @param   r_pobj Return by reference; ptr to item
00065  * @return  Return status
00066  */
00067 PmReturn_t list_getItem(pPmObj_t plist, int16_t index, pPmObj_t *r_pobj);
00068 
00069 /**
00070  * Sets the item in the list at the index.
00071  *
00072  * @param   plist Ptr to list
00073  * @param   index Index into list
00074  * @param   pobj Ptr to obj to put into list
00075  * @return  Return status
00076  */
00077 PmReturn_t list_setItem(pPmObj_t plist, int16_t index, pPmObj_t pobj);
00078 
00079 /**
00080  * Makes a copy of the given list.
00081  *
00082  * Allocate the necessary memory for root and nodes.
00083  * Duplicate ptrs to objs.
00084  *
00085  * @param   pobj Ptr to source list
00086  * @param   r_pobj Return; Addr of ptr to return obj
00087  * @return  Return status
00088  */
00089 PmReturn_t list_copy(pPmObj_t pobj, pPmObj_t *r_pobj);
00090 
00091 /**
00092  * Appends the given obj to the end of the given list.
00093  *
00094  * Allocate the memory for the node.
00095  * Do not copy obj, just reuse ptr.
00096  *
00097  * @param   plist Ptr to list
00098  * @param   pobj Ptr to item to append
00099  * @return  Return status
00100  */
00101 PmReturn_t list_append(pPmObj_t plist, pPmObj_t pobj);
00102 
00103 /**
00104  * Creates a new list with the contents of psrclist
00105  * copied pint number of times.
00106  * This implements the python code "[0,...] * N"
00107  * where the list can be any list and N is an integer.
00108  *
00109  * @param   psrclist The source list to replicate
00110  * @param   n The integer number of times to replicate it
00111  * @param   r_pnewlist Return; new list with its contents set.
00112  * @return  Return status
00113  */
00114 PmReturn_t list_replicate(pPmObj_t psrclist, int16_t n, pPmObj_t *r_pnewlist);
00115 
00116 /**
00117  * Inserts the object into the list at the desired index.
00118  *
00119  * @param   plist Ptr to list obj
00120  * @param   pobj Ptr to obj to insert
00121  * @param   index Index of where to insert obj
00122  * @return  Return status
00123  */
00124 PmReturn_t list_insert(pPmObj_t plist, int16_t index, pPmObj_t pobj);
00125 
00126 /**
00127  * Removes a given object from the list.
00128  *
00129  * @param   plist Ptr to list obj
00130  * @param   item Ptr to object to be removed
00131  * @return  Return status
00132  */
00133 PmReturn_t list_remove(pPmObj_t plist, pPmObj_t item);
00134 
00135 /**
00136  * Finds the first index of the item that matches pitem.
00137  * Returns an ValueError Exception if the item is not found.
00138  *
00139  * @param   plist Ptr to list obj
00140  * @param   pitem Ptr to object to be removed
00141  * @param   r_index Return by reference; ptr to index (C uint16)
00142  * @return  Return status
00143  */
00144 PmReturn_t list_index(pPmObj_t plist, pPmObj_t pitem, uint16_t *r_index);
00145 
00146 /**
00147  * Removes the item at the given index.
00148  * Raises a TypeError if the first argument is not a list.
00149  * Raises an IndexError if the index is out of bounds.
00150  *
00151  * @param   plist Ptr to list obj
00152  * @param   index Index of item to remove
00153  * @return  Return status
00154  */
00155 PmReturn_t list_delItem(pPmObj_t plist, int16_t index);
00156 
00157 #ifdef HAVE_PRINT
00158 /**
00159  * Prints out a list. Uses obj_print() to print elements.
00160  *
00161  * @param pobj Object to print.
00162  * @return Return status
00163  */
00164 PmReturn_t list_print(pPmObj_t pobj);
00165 #endif /* HAVE_PRINT */
00166 
00167 /**
00168  * Removes all items from the list and zeroes the length.
00169  *
00170  * @param plist List to clear
00171  * @return Return status
00172  */
00173 PmReturn_t list_clear(pPmObj_t plist);
00174 
00175 #endif /* __LIST_H__ */