flight/libraries/PyMite/vm/lst.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 __LIST_H__
  17 #define __LIST_H__
  18
  19 /**
  20  * \file
  21  * \brief List Object Type
  22  *
  23  * List object type header.
  24  */
  25
  26 /**
  27  * List obj
  28  *
  29  * Mutable ordered sequence of objects.  Contains ptr to linked list of nodes.
  30  */
  31 typedef struct PmList_s
  32 {
  33     /** Object descriptor */
  34     PmObjDesc_t od;
  35
  36     /** List length; number of objs linked */
  37     int16_t length;
  38
  39     /** Ptr to linked list of nodes */
  40     pSeglist_t val;
  41 } PmList_t,
  42  *pPmList_t;
  43
  44
  45 /**
  46  * Allocates a new List object.
  47  *
  48  * If there is not enough memory to allocate the List,
  49  * the return status will indicate an OutOfMemoryError
  50  * that must be passed up to the interpreter.
  51  * Otherwise, a ptr to the list is returned by reference
  52  * and the return status is OK.
  53  *
  54  * @param   r_pobj Return; addr of ptr to obj
  55  * @return  Return status
  56  */
  57 PmReturn_t list_new(pPmObj_t *r_pobj);
  58
  59 /**
  60  * Gets the object in the list at the index.
  61  *
  62  * @param   plist Ptr to list obj
  63  * @param   index Index into list
  64  * @param   r_pobj Return by reference; ptr to item
  65  * @return  Return status
  66  */
  67 PmReturn_t list_getItem(pPmObj_t plist, int16_t index, pPmObj_t *r_pobj);
  68
  69 /**
  70  * Sets the item in the list at the index.
  71  *
  72  * @param   plist Ptr to list
  73  * @param   index Index into list
  74  * @param   pobj Ptr to obj to put into list
  75  * @return  Return status
  76  */
  77 PmReturn_t list_setItem(pPmObj_t plist, int16_t index, pPmObj_t pobj);
  78
  79 /**
  80  * Makes a copy of the given list.
  81  *
  82  * Allocate the necessary memory for root and nodes.
  83  * Duplicate ptrs to objs.
  84  *
  85  * @param   pobj Ptr to source list
  86  * @param   r_pobj Return; Addr of ptr to return obj
  87  * @return  Return status
  88  */
  89 PmReturn_t list_copy(pPmObj_t pobj, pPmObj_t *r_pobj);
  90
  91 /**
  92  * Appends the given obj to the end of the given list.
  93  *
  94  * Allocate the memory for the node.
  95  * Do not copy obj, just reuse ptr.
  96  *
  97  * @param   plist Ptr to list
  98  * @param   pobj Ptr to item to append
  99  * @return  Return status
 100  */
 101 PmReturn_t list_append(pPmObj_t plist, pPmObj_t pobj);
 102
 103 /**
 104  * Creates a new list with the contents of psrclist
 105  * copied pint number of times.
 106  * This implements the python code "[0,...] * N"
 107  * where the list can be any list and N is an integer.
 108  *
 109  * @param   psrclist The source list to replicate
 110  * @param   n The integer number of times to replicate it
 111  * @param   r_pnewlist Return; new list with its contents set.
 112  * @return  Return status
 113  */
 114 PmReturn_t list_replicate(pPmObj_t psrclist, int16_t n, pPmObj_t *r_pnewlist);
 115
 116 /**
 117  * Inserts the object into the list at the desired index.
 118  *
 119  * @param   plist Ptr to list obj
 120  * @param   pobj Ptr to obj to insert
 121  * @param   index Index of where to insert obj
 122  * @return  Return status
 123  */
 124 PmReturn_t list_insert(pPmObj_t plist, int16_t index, pPmObj_t pobj);
 125
 126 /**
 127  * Removes a given object from the list.
 128  *
 129  * @param   plist Ptr to list obj
 130  * @param   item Ptr to object to be removed
 131  * @return  Return status
 132  */
 133 PmReturn_t list_remove(pPmObj_t plist, pPmObj_t item);
 134
 135 /**
 136  * Finds the first index of the item that matches pitem.
 137  * Returns an ValueError Exception if the item is not found.
 138  *
 139  * @param   plist Ptr to list obj
 140  * @param   pitem Ptr to object to be removed
 141  * @param   r_index Return by reference; ptr to index (C uint16)
 142  * @return  Return status
 143  */
 144 PmReturn_t list_index(pPmObj_t plist, pPmObj_t pitem, uint16_t *r_index);
 145
 146 /**
 147  * Removes the item at the given index.
 148  * Raises a TypeError if the first argument is not a list.
 149  * Raises an IndexError if the index is out of bounds.
 150  *
 151  * @param   plist Ptr to list obj
 152  * @param   index Index of item to remove
 153  * @return  Return status
 154  */
 155 PmReturn_t list_delItem(pPmObj_t plist, int16_t index);
 156
 157 #ifdef HAVE_PRINT
 158 /**
 159  * Prints out a list. Uses obj_print() to print elements.
 160  *
 161  * @param pobj Object to print.
 162  * @return Return status
 163  */
 164 PmReturn_t list_print(pPmObj_t pobj);
 165 #endif /* HAVE_PRINT */
 166
 167 /**
 168  * Removes all items from the list and zeroes the length.
 169  *
 170  * @param plist List to clear
 171  * @return Return status
 172  */
 173 PmReturn_t list_clear(pPmObj_t plist);
 174
 175 #endif /* __LIST_H__ */