strobj.h

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