tuple.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 __TUPLE_H__
00017 #define __TUPLE_H__
00018 
00019 
00020 /**
00021  * \file
00022  * \brief Tuple Object Type
00023  *
00024  * Tuple object type header.
00025  */
00026 
00027 /**
00028  * Tuple obj
00029  *
00030  * Immutable ordered sequence.  Contains array of ptrs to objs.
00031  */
00032 typedef struct PmTuple_s
00033 {
00034     /** Object descriptor */
00035     PmObjDesc_t od;
00036 
00037     /**
00038      * Length of tuple
00039      * I don't expect a tuple to ever exceed 255 elements,
00040      * but if I set this type to int8_t, a 0-element tuple
00041      * is too small to be allocated.
00042      */
00043     int16_t length;
00044 
00045     /** Array of ptrs to objs */
00046     pPmObj_t val[1];
00047 } PmTuple_t,
00048  *pPmTuple_t;
00049 
00050 
00051 #define tuple_copy(src, dest) tuple_replicate((src), 1, (dest))
00052 
00053 
00054 /**
00055  * Creates a Tuple by loading a tuple image from memory.
00056  *
00057  * Obtain space for tuple from the heap.
00058  * Load all objs within the tuple img.
00059  * Leave contents of paddr pointing one byte past end of
00060  * last obj in tuple.
00061  *
00062  * The tuple image has the following structure:
00063  *      -type:      S8 - OBJ_TYPE_TUPLE
00064  *      -length     U8 - N number of objects in the tuple.
00065  *                  N objects follow in the stream.
00066  *
00067  * @param   memspace Memory space.
00068  * @param   paddr Ptr to ptr to tuple in memspace
00069  * @param   r_ptuple Return by reference; new filled tuple
00070  * @return  Return status
00071  */
00072 PmReturn_t tuple_loadFromImg(PmMemSpace_t memspace,
00073                              uint8_t const **paddr, pPmObj_t *r_ptuple);
00074 
00075 /**
00076  * Allocates space for a new Tuple.  Returns a pointer to the tuple.
00077  *
00078  * @param   n the number of elements the tuple will contain
00079  * @param   r_ptuple Return by ref, ptr to new tuple
00080  * @return  Return status
00081  */
00082 PmReturn_t tuple_new(uint16_t n, pPmObj_t *r_ptuple);
00083 
00084 /**
00085  * Replicates a tuple, n number of times to create a new tuple
00086  *
00087  * Copies the pointers (not the objects).
00088  *
00089  * @param   ptup Ptr to source tuple.
00090  * @param   n Number of times to replicate the tuple.
00091  * @param   r_ptuple Return arg; Ptr to new tuple.
00092  * @return  Return status
00093  */
00094 PmReturn_t tuple_replicate(pPmObj_t ptup, int16_t n, pPmObj_t *r_ptuple);
00095 
00096 /**
00097  * Gets the object in the tuple at the index.
00098  *
00099  * @param   ptup Ptr to tuple obj
00100  * @param   index Index into tuple
00101  * @param   r_pobj Return by reference; ptr to item
00102  * @return  Return status
00103  */
00104 PmReturn_t tuple_getItem(pPmObj_t ptup, int16_t index, pPmObj_t *r_pobj);
00105 
00106 #ifdef HAVE_PRINT
00107 /**
00108  * Prints out a tuple. Uses obj_print() to print elements.
00109  *
00110  * @param pobj Object to print.
00111  * @return Return status
00112  */
00113 PmReturn_t tuple_print(pPmObj_t pobj);
00114 #endif /* HAVE_PRINT */
00115 
00116 #endif /* __TUPLE_H__ */