flight/libraries/PyMite/vm/strobj.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 __STRING_H__
  17 #define __STRING_H__
  18
  19
  20 /**
  21  * \file
  22  * \brief String Object Type
  23  *
  24  * String object type header.
  25  */
  26
  27
  28 /** Set to nonzero to enable string cache.  DO NOT REMOVE THE DEFINITION. */
  29 #define USE_STRING_CACHE 1
  30
  31
  32 /**
  33  * Loads a string from image
  34  *
  35  * @param ms memoryspace paddr points to
  36  * @param paddr address in memoryspace of source string
  37  * @param r_pstring Return by reference; a new string object
  38  * @return Return status
  39  */
  40 #define string_loadFromImg(ms, paddr, r_pstring) \
  41     string_create((ms), (paddr), (int16_t)-1, (int16_t)1, (r_pstring))
  42
  43 /**
  44  * Creates String object from character array in RAM
  45  *
  46  * @param paddr pointer to address of source string
  47  * @param r_pstring Return arg; addr of ptr to string
  48  */
  49 #define string_new(paddr, r_pstring) \
  50     string_create(MEMSPACE_RAM, (uint8_t const **)(paddr), 0, (int16_t)1, (r_pstring))
  51
  52 /**
  53  * Creates String object from character array in RAM which may contain
  54  * embedded null characters.
  55  *
  56  * @param paddr pointer to address of source string
  57  * @param len length of source string
  58  * @param r_pstring Return arg; addr of ptr to string
  59  */
  60 #define string_newWithLen(paddr, len, r_pstring) \
  61     string_create(MEMSPACE_RAM, (uint8_t const **)(paddr), (len), (int16_t)1, \
  62                   (r_pstring))
  63
  64 /**
  65  * Creates String object by replicating an existing C string, n times
  66  *
  67  * @param paddr pointer to address of source string
  68  * @param n number of times to replicate the source string
  69  * @param r_pstring Return arg; addr of ptr to string
  70  */
  71 #define string_replicate(paddr, n, r_pstring) \
  72     string_create(MEMSPACE_RAM, (paddr), (uint8_t)0, (n), (r_pstring))
  73
  74 /***************************************************************
  75  * Types
  76  **************************************************************/
  77
  78 /**
  79  * String obj
  80  *
  81  * Null terminated array of chars.
  82  */
  83 typedef struct PmString_s
  84 {
  85     /** Object descriptor */
  86     PmObjDesc_t od;
  87
  88     /** Length of string */
  89     uint16_t length;
  90
  91 #if USE_STRING_CACHE
  92     /** Ptr to next string in cache */
  93     struct PmString_s *next;
  94 #endif                          /* USE_STRING_CACHE */
  95
  96     /**
  97      * Null-term char array
  98      *
  99      * Use length 1 here so that string-alloc function can use
 100      * "sizeof(PmString_t) + len" and there will be room for the null-term
 101      */
 102     uint8_t val[1];
 103 } PmString_t,
 104  *pPmString_t;
 105
 106
 107 /***************************************************************
 108  * Prototypes
 109  **************************************************************/
 110
 111 /**
 112  * Creates a new String obj.
 113  * If len is less than zero, load from a String image.
 114  * If len is zero, copy from a C string (which has a null terminator)
 115  * If len is positive, copy as many chars as given in the len argument
 116  *      A string image has the following structure:
 117  *          -type:      int8 - OBJ_TYPE_STRING
 118  *          -length:    uint16 - number of bytes in the string
 119  *          -val:       uint8[] - array of chars with null term
 120  *
 121  * Returns by reference a ptr to String obj.
 122  *
 123  * Obtain space for String from the heap.
 124  * Copy string from memspace.
 125  * Leave contents of paddr pointing one byte past end of str.
 126  *
 127  * THE PROGRAMMER SHOULD NOT CALL THIS FUNCTION DIRECTLY.
 128  * Instead, use one of the two macros string_loadFromImg()
 129  * or string_new().
 130  *
 131  * @param   memspace memory space where *paddr points
 132  * @param   paddr ptr to ptr to null term character array or image.
 133  * @param   len length of the C character array
 134  *          (use -1 for string images, 0 for C strings)
 135  * @param   n Number of times to replicate the given string argument
 136  * @param   r_pstring Return by reference; ptr to String obj
 137  * @return  Return status
 138  */
 139 PmReturn_t string_create(PmMemSpace_t memspace, uint8_t const **paddr,
 140                          int16_t len, int16_t n, pPmObj_t *r_pstring);
 141
 142 /**
 143  * Creates a new String object from a single character.
 144  *
 145  * @param   c The character to become the string
 146  * @param   r_pstring Return by reference; ptr to String obj
 147  * @return  Return status
 148  */
 149 PmReturn_t string_newFromChar(uint8_t const c, pPmObj_t *r_pstring);
 150
 151 /**
 152  * Compares two String objects for equality.
 153  *
 154  * @param   pstr1 Ptr to first string
 155  * @param   pstr2 Ptr to second string
 156  * @return  C_SAME if the strings are equivalent, C_DIFFER otherwise
 157  */
 158 int8_t string_compare(pPmString_t pstr1, pPmString_t pstr2);
 159
 160 #ifdef HAVE_PRINT
 161 /**
 162  * Sends out a string object bytewise. Escaping and framing is configurable
 163  * via is_escaped.
 164  *
 165  * @param pstr Ptr to string object
 166  * @param is_escaped If 0, print out string as is. Otherwise escape unprintable
 167  *                   characters and surround string with single quotes.
 168  * @return Return status
 169  */
 170 PmReturn_t string_print(pPmObj_t pstr, uint8_t is_escaped);
 171 #endif /* HAVE_PRINT */
 172
 173 /**
 174  * Clears the string cache if one exists.
 175  * Called by heap_init()
 176  *
 177  * @return Return status
 178  */
 179 PmReturn_t string_cacheInit(void);
 180
 181
 182 /** Returns a pointer to the base of the string cache */
 183 PmReturn_t string_getCache(pPmString_t **r_ppstrcache);
 184
 185 /**
 186  * Returns a new string object that is the concatenation
 187  * of the two given strings.
 188  *
 189  * @param pstr1 First source string
 190  * @param pstr2 Second source string
 191  * @param r_pstring Return arg; ptr to new string object
 192  * @return Return status
 193  */
 194 PmReturn_t
 195 string_concat(pPmString_t pstr1, pPmString_t pstr2, pPmObj_t *r_pstring);
 196
 197 #ifdef HAVE_STRING_FORMAT
 198 /**
 199  * Returns a new string object that is created from the given format string
 200  * and the argument(s).
 201  *
 202  * @param pstr Format string object
 203  * @param parg Single argument or tuple of arguments
 204  * @param r_pstring Return arg; ptr to new string object
 205  * @return Return status
 206  */
 207 PmReturn_t string_format(pPmString_t pstr, pPmObj_t parg, pPmObj_t *r_pstring);
 208
 209 /**
 210  * Prints n bytes, formatting them if is_escaped is true
 211  *
 212  * @param pb Pointer to C bytes
 213  * @param is_escaped Boolean true if string is to be escaped
 214  * @param n Number of bytes to print
 215  * @return Return status
 216  */
 217 PmReturn_t string_printFormattedBytes(uint8_t *pb,
 218                                       uint8_t is_escaped,
 219                                       uint16_t n);
 220 #endif /* HAVE_STRING_FORMAT */
 221
 222 #endif /* __STRING_H__ */