flight/libraries/PyMite/vm/tuple.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 __TUPLE_H__
  17 #define __TUPLE_H__
  18
  19
  20 /**
  21  * \file
  22  * \brief Tuple Object Type
  23  *
  24  * Tuple object type header.
  25  */
  26
  27 /**
  28  * Tuple obj
  29  *
  30  * Immutable ordered sequence.  Contains array of ptrs to objs.
  31  */
  32 typedef struct PmTuple_s
  33 {
  34     /** Object descriptor */
  35     PmObjDesc_t od;
  36
  37     /**
  38      * Length of tuple
  39      * I don't expect a tuple to ever exceed 255 elements,
  40      * but if I set this type to int8_t, a 0-element tuple
  41      * is too small to be allocated.
  42      */
  43     int16_t length;
  44
  45     /** Array of ptrs to objs */
  46     pPmObj_t val[1];
  47 } PmTuple_t,
  48  *pPmTuple_t;
  49
  50
  51 #define tuple_copy(src, dest) tuple_replicate((src), 1, (dest))
  52
  53
  54 /**
  55  * Creates a Tuple by loading a tuple image from memory.
  56  *
  57  * Obtain space for tuple from the heap.
  58  * Load all objs within the tuple img.
  59  * Leave contents of paddr pointing one byte past end of
  60  * last obj in tuple.
  61  *
  62  * The tuple image has the following structure:
  63  *      -type:      S8 - OBJ_TYPE_TUPLE
  64  *      -length     U8 - N number of objects in the tuple.
  65  *                  N objects follow in the stream.
  66  *
  67  * @param   memspace Memory space.
  68  * @param   paddr Ptr to ptr to tuple in memspace
  69  * @param   r_ptuple Return by reference; new filled tuple
  70  * @return  Return status
  71  */
  72 PmReturn_t tuple_loadFromImg(PmMemSpace_t memspace,
  73                              uint8_t const **paddr, pPmObj_t *r_ptuple);
  74
  75 /**
  76  * Allocates space for a new Tuple.  Returns a pointer to the tuple.
  77  *
  78  * @param   n the number of elements the tuple will contain
  79  * @param   r_ptuple Return by ref, ptr to new tuple
  80  * @return  Return status
  81  */
  82 PmReturn_t tuple_new(uint16_t n, pPmObj_t *r_ptuple);
  83
  84 /**
  85  * Replicates a tuple, n number of times to create a new tuple
  86  *
  87  * Copies the pointers (not the objects).
  88  *
  89  * @param   ptup Ptr to source tuple.
  90  * @param   n Number of times to replicate the tuple.
  91  * @param   r_ptuple Return arg; Ptr to new tuple.
  92  * @return  Return status
  93  */
  94 PmReturn_t tuple_replicate(pPmObj_t ptup, int16_t n, pPmObj_t *r_ptuple);
  95
  96 /**
  97  * Gets the object in the tuple at the index.
  98  *
  99  * @param   ptup Ptr to tuple obj
 100  * @param   index Index into tuple
 101  * @param   r_pobj Return by reference; ptr to item
 102  * @return  Return status
 103  */
 104 PmReturn_t tuple_getItem(pPmObj_t ptup, int16_t index, pPmObj_t *r_pobj);
 105
 106 #ifdef HAVE_PRINT
 107 /**
 108  * Prints out a tuple. Uses obj_print() to print elements.
 109  *
 110  * @param pobj Object to print.
 111  * @return Return status
 112  */
 113 PmReturn_t tuple_print(pPmObj_t pobj);
 114 #endif /* HAVE_PRINT */
 115
 116 #endif /* __TUPLE_H__ */