strobj.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 __STRING_H__
00017 #define __STRING_H__
00018 
00019 
00020 /**
00021  * \file
00022  * \brief String Object Type
00023  *
00024  * String object type header.
00025  */
00026 
00027 
00028 /** Set to nonzero to enable string cache.  DO NOT REMOVE THE DEFINITION. */
00029 #define USE_STRING_CACHE 1
00030 
00031 
00032 /**
00033  * Loads a string from image
00034  *
00035  * @param ms memoryspace paddr points to
00036  * @param paddr address in memoryspace of source string
00037  * @param r_pstring Return by reference; a new string object
00038  * @return Return status
00039  */
00040 #define string_loadFromImg(ms, paddr, r_pstring) \
00041     string_create((ms), (paddr), (int16_t)-1, (int16_t)1, (r_pstring))
00042 
00043 /**
00044  * Creates String object from character array in RAM
00045  *
00046  * @param paddr pointer to address of source string
00047  * @param r_pstring Return arg; addr of ptr to string
00048  */
00049 #define string_new(paddr, r_pstring) \
00050     string_create(MEMSPACE_RAM, (uint8_t const **)(paddr), 0, (int16_t)1, (r_pstring))
00051 
00052 /**
00053  * Creates String object from character array in RAM which may contain
00054  * embedded null characters.
00055  *
00056  * @param paddr pointer to address of source string
00057  * @param len length of source string
00058  * @param r_pstring Return arg; addr of ptr to string
00059  */
00060 #define string_newWithLen(paddr, len, r_pstring) \
00061     string_create(MEMSPACE_RAM, (uint8_t const **)(paddr), (len), (int16_t)1, \
00062                   (r_pstring))
00063 
00064 /**
00065  * Creates String object by replicating an existing C string, n times
00066  *
00067  * @param paddr pointer to address of source string
00068  * @param n number of times to replicate the source string
00069  * @param r_pstring Return arg; addr of ptr to string
00070  */
00071 #define string_replicate(paddr, n, r_pstring) \
00072     string_create(MEMSPACE_RAM, (paddr), (uint8_t)0, (n), (r_pstring))
00073 
00074 /***************************************************************
00075  * Types
00076  **************************************************************/
00077 
00078 /**
00079  * String obj
00080  *
00081  * Null terminated array of chars.
00082  */
00083 typedef struct PmString_s
00084 {
00085     /** Object descriptor */
00086     PmObjDesc_t od;
00087 
00088     /** Length of string */
00089     uint16_t length;
00090 
00091 #if USE_STRING_CACHE
00092     /** Ptr to next string in cache */
00093     struct PmString_s *next;
00094 #endif                          /* USE_STRING_CACHE */
00095 
00096     /**
00097      * Null-term char array
00098      *
00099      * Use length 1 here so that string-alloc function can use
00100      * "sizeof(PmString_t) + len" and there will be room for the null-term
00101      */
00102     uint8_t val[1];
00103 } PmString_t,
00104  *pPmString_t;
00105 
00106 
00107 /***************************************************************
00108  * Prototypes
00109  **************************************************************/
00110 
00111 /**
00112  * Creates a new String obj.
00113  * If len is less than zero, load from a String image.
00114  * If len is zero, copy from a C string (which has a null terminator)
00115  * If len is positive, copy as many chars as given in the len argument
00116  *      A string image has the following structure:
00117  *          -type:      int8 - OBJ_TYPE_STRING
00118  *          -length:    uint16 - number of bytes in the string
00119  *          -val:       uint8[] - array of chars with null term
00120  *
00121  * Returns by reference a ptr to String obj.
00122  *
00123  * Obtain space for String from the heap.
00124  * Copy string from memspace.
00125  * Leave contents of paddr pointing one byte past end of str.
00126  *
00127  * THE PROGRAMMER SHOULD NOT CALL THIS FUNCTION DIRECTLY.
00128  * Instead, use one of the two macros string_loadFromImg()
00129  * or string_new().
00130  *
00131  * @param   memspace memory space where *paddr points
00132  * @param   paddr ptr to ptr to null term character array or image.
00133  * @param   len length of the C character array
00134  *          (use -1 for string images, 0 for C strings)
00135  * @param   n Number of times to replicate the given string argument
00136  * @param   r_pstring Return by reference; ptr to String obj
00137  * @return  Return status
00138  */
00139 PmReturn_t string_create(PmMemSpace_t memspace, uint8_t const **paddr,
00140                          int16_t len, int16_t n, pPmObj_t *r_pstring);
00141 
00142 /**
00143  * Creates a new String object from a single character.
00144  *
00145  * @param   c The character to become the string
00146  * @param   r_pstring Return by reference; ptr to String obj
00147  * @return  Return status
00148  */
00149 PmReturn_t string_newFromChar(uint8_t const c, pPmObj_t *r_pstring);
00150 
00151 /**
00152  * Compares two String objects for equality.
00153  *
00154  * @param   pstr1 Ptr to first string
00155  * @param   pstr2 Ptr to second string
00156  * @return  C_SAME if the strings are equivalent, C_DIFFER otherwise
00157  */
00158 int8_t string_compare(pPmString_t pstr1, pPmString_t pstr2);
00159 
00160 #ifdef HAVE_PRINT
00161 /**
00162  * Sends out a string object bytewise. Escaping and framing is configurable
00163  * via marshall.
00164  *
00165  * @param pobj Ptr to string object
00166  * @param marshall If 0, print out string as is. Otherwise escape unprintable
00167  *                 characters and surround string with single quotes.
00168  * @return Return status
00169  */
00170 PmReturn_t string_print(pPmObj_t pstr, uint8_t marshall);
00171 #endif /* HAVE_PRINT */
00172 
00173 /**
00174  * Clears the string cache if one exists.
00175  * Called by heap_init()
00176  *
00177  * @return Return status
00178  */
00179 PmReturn_t string_cacheInit(void);
00180 
00181 
00182 /** Returns a pointer to the base of the string cache */
00183 PmReturn_t string_getCache(pPmString_t **r_ppstrcache);
00184 
00185 /**
00186  * Returns a new string object that is the concatenation
00187  * of the two given strings.
00188  *
00189  * @param pstr1 First source string
00190  * @param pstr2 Second source string
00191  * @param r_pstring Return arg; ptr to new string object
00192  * @return Return status
00193  */
00194 PmReturn_t
00195 string_concat(pPmString_t pstr1, pPmString_t pstr2, pPmObj_t *r_pstring);
00196 
00197 #ifdef HAVE_STRING_FORMAT
00198 /**
00199  * Returns a new string object that is created from the given format string
00200  * and the argument(s).
00201  *
00202  * @param pstr Format string object
00203  * @param parg Single argument or tuple of arguments
00204  * @param r_pstring Return arg; ptr to new string object
00205  * @return Return status
00206  */
00207 PmReturn_t string_format(pPmString_t pstr, pPmObj_t parg, pPmObj_t *r_pstring);
00208 
00209 /**
00210  * Prints n bytes, formatting them if marshall is true
00211  *
00212  * @param pb Pointer to C bytes
00213  * @param marshall Boolean true if bytes are to be formatted
00214  * @param n Number of bytes to print
00215  * @return Return status
00216  */
00217 PmReturn_t string_printFormattedBytes(uint8_t *pb,
00218                                       uint8_t marshall,
00219                                       uint16_t n);
00220 #endif /* HAVE_STRING_FORMAT */
00221 
00222 #endif /* __STRING_H__ */