src/Headers/cstring.h

   1 /*
   2 ** Copyright (C) University of Virginia, Massachusetts Institue of Technology 1994-2001.
   3 ** See ../LICENSE for license information.
   4 **
   5 */
   6 /*
   7 ** cstring.h
   8 */
   9
  10 # ifndef CSTRING_H
  11 # define CSTRING_H
  12
  13 /* does this cause problems on Solaris?  linux?  */
  14 /* sgi's don't like it */
  15 # ifndef IRIX
  16 # ifdef NULL   /* hack so <strings.h> works */
  17 # undef NULL
  18 # endif
  19 # endif
  20
  21 /* typedefs in forwardTypes */
  22
  23 extern /*@notnull@*/ cstring cstring_create (size_t p_n) /*@*/ /*@ensures maxSet(result) == p_n @*/ ;
  24 extern /*@only@*/ /*@notnull@*/  cstring cstring_newEmpty (void) ;
  25 extern /*@notnull@*/ cstring cstring_appendChar (/*@only@*/ cstring p_s1, char p_c);
  26
  27 extern cstring cstring_concatLength (/*@only@*/ cstring p_s1, char *p_s2, size_t p_len)
  28   /*@*/
  29   /*@requires maxSet(p_s2) >= (p_len - 1) @*/ ;
  30
  31 extern /*@notnull@*/ cstring cstring_prependChar (char p_c, /*@temp@*/ cstring p_s1);
  32 extern /*@notnull@*/ cstring cstring_prependCharO (char p_c, /*@only@*/ cstring p_s1);
  33 extern cstring cstring_downcase (cstring p_s) /*@*/ ;
  34 extern cstring cstring_copy (cstring p_s) /*@*/  /*@ensures maxSet(result) == maxRead(p_s) /\ maxRead(result) == maxRead(p_s) @*/ ;
  35 extern cstring cstring_copyLength (char *p_s, size_t p_len) /*@*/  /*@requires maxSet(p_s) >= (p_len - 1) @*/;
  36
  37 extern int cstring_toPosInt (cstring p_s) /*@*/ ;
  38
  39 typedef enum {
  40   CGE_SAME,     /* no differences */
  41   CGE_DISTINCT, /* significant differences */
  42   CGE_CASE,     /* case differences */
  43   CGE_LOOKALIKE /* lookalike differences */
  44 } cmpcode;
  45
  46 extern cmpcode cstring_genericEqual (cstring p_s, cstring p_t,
  47                                      size_t p_nchars,
  48                                      bool p_caseinsensitive,
  49                                      bool p_lookalike) /*@*/
  50   /*@requires maxRead(p_s) >= p_nchars /\ maxRead(p_t) >= p_nchars @*/ ;
  51
  52 /* evans 2001-09-09 - removed conditional compilation on this (for WIN32, OS2) */
  53 extern void cstring_replaceAll (cstring p_s, char p_old, char p_snew) /*@modifies p_s@*/ ;
  54
  55 extern void cstring_replaceLit (/*@unique@*/ cstring p_s, char *p_old, char *p_snew)
  56    /*@modifies p_s@*/
  57    /*@requires maxRead(p_snew) >= 0 /\ maxRead(p_old) >= 0 /\ maxRead(p_old) >= maxRead(p_snew) @*/;
  58
  59 extern char cstring_firstChar (cstring p_s) /*@*/ ;
  60 extern char cstring_secondChar (cstring p_s) /*@*/ ;
  61 extern char cstring_lastChar (cstring p_s) /*@*/ ;
  62 extern char cstring_getChar (cstring p_s, size_t p_n);
  63
  64 extern void cstring_setChar (cstring p_s, size_t p_n, char p_c)
  65    /*@requires maxRead(p_s) >= (p_n - 1) /\ maxSet(p_s) >= (p_n - 1) @*/ ;
  66
  67 # define cstring_secondChar(s) cstring_getChar (s, 2)
  68
  69 extern /*@exposed@*/ /*@notnull@*/ /*@untainted@*/ char *
  70   cstring_toCharsSafe (/*@temp@*/ /*@exposed@*/ /*@returned@*/ cstring p_s)
  71      /*@*/ ;
  72
  73 extern size_t cstring_length (cstring p_s) /*@*/ /*@ensures result == maxRead(p_s) @*/;
  74
  75 extern bool cstring_contains (/*@unique@*/ cstring p_c, cstring p_sub) /*@*/ ;
  76 extern bool cstring_containsChar (cstring p_c, char p_ch) /*@*/ ;
  77 extern bool cstring_equal (cstring p_c1, cstring p_c2) /*@*/ ;
  78 extern bool cstring_equalCaseInsensitive (cstring p_c1, cstring p_c2) /*@*/ ;
  79 extern bool cstring_equalLen (cstring p_c1, cstring p_c2, size_t p_len) /*@*/ ;
  80 extern bool cstring_equalLenCaseInsensitive (cstring p_c1, cstring p_c2, size_t p_len) /*@*/ ;
  81 extern bool cstring_equalPrefix (cstring p_c1, cstring p_c2) /*@*/ ;
  82 extern bool cstring_equalPrefixLit (cstring p_c1, /*@observer@*/ const char *p_c2) /*@*/ ;
  83 extern bool cstring_equalLit (cstring p_c1, char *p_c2) /*@*/ ;
  84 extern int cstring_compare (cstring p_c1, cstring p_c2) /*@*/ ;
  85 extern int cstring_xcompare (cstring *p_c1, cstring *p_c2) /*@*/ ;
  86
  87 # ifndef NOLCL
  88 extern bool cstring_hasNonAlphaNumBar (cstring p_s) /*@*/ ;
  89 # endif
  90
  91 extern cstring cstring_elide (cstring p_s, size_t p_len) /*@*/ ;
  92
  93 extern cstring cstring_clip (/*@returned@*/ cstring p_s, size_t p_len)
  94    /*@modifies p_s@*/ ;
  95
  96 extern void cstring_stripChars (cstring p_s, const char *p_clist) /*@modifies p_s@*/ ;
  97
  98 extern /*@dependent@*/ cstring
  99   cstring_bsearch (cstring p_key,
 100                    char **p_table,
 101                    int p_nentries);
 102
 103 extern bool cstring_lessthan (cstring p_s1, cstring p_s2) /*@*/ ;
 104 # define cstring_lessthan(s1, s2) (cstring_compare (s1, s2) < 0)
 105
 106 # define cstring_equalLit(s, lit) \
 107   (mstring_equal (cstring_toCharsSafe (s), lit))
 108
 109 extern bool cstring_equalFree (/*@only@*/ cstring p_c1, /*@only@*/ cstring p_c2);
 110
 111 /* really exposed! */
 112
 113 /*
 114 ** Don't allow tainted cstring's
 115 */
 116
 117 extern /*@untained@*/ cstring
 118   cstring_fromChars (/*@returned@*/ /*@null@*/
 119                      const /*:untainted@*/ /*@exposed@*/ /*@temp@*/ char *p_cp) /*@*/ ;
 120
 121 extern cstring
 122    cstring_fromCharsO (/*@null@*/ /*:untainted@*/ /*@only@*/ char *p_cp) /*@*/ ;
 123 /*@-mustfree@*/
 124 # define cstring_fromCharsO(s) cstring_fromChars(s)
 125 /*@=mustfree@*/
 126
 127 extern cstring cstring_fromCharsNew (/*:untainted@*/ /*@null@*/ char *p_s) /*@*/ ;
 128 # define cstring_fromCharsNew(s) cstring_copy(cstring_fromChars(s))
 129
 130 # ifndef NOLCL
 131 extern /*@exposed@*/ /*@notnull@*/ /*@untainted@*/
 132   char *cstring_toCharsSafeO (/*@only@*/ /*@exposed@*/ /*@returned@*/ cstring p_s);
 133 /*@-mustfree@*/
 134 # define cstring_toCharsSafeO(s) cstring_toCharsSafe(s)
 135 /*@=mustfree@*/
 136 # endif
 137
 138 extern void cstring_free (/*@only@*/ cstring p_s);
 139
 140 /*@constant null cstring cstring_undefined;@*/
 141 # define cstring_undefined     ((cstring)NULL)
 142
 143 extern /*@falsewhennull@*/ bool cstring_isDefined (cstring p_s) /*@*/ ;
 144 extern /*@nullwhentrue@*/ bool cstring_isUndefined (cstring p_s) /*@*/ ;
 145
 146 extern /*@nullwhentrue@*/ bool cstring_isEmpty (cstring p_s) /*@*/ ;
 147 extern /*@falsewhennull@*/ bool cstring_isNonEmpty (cstring p_s) /*@*/ ;
 148
 149 # define cstring_isDefined(s)   ((s) != cstring_undefined)
 150 # define cstring_isUndefined(s) (!cstring_isDefined(s))
 151
 152 # define cstring_isEmpty(s)     (cstring_length(s) == 0)
 153 # define cstring_isNonEmpty(s)  (!cstring_isEmpty(s))
 154
 155 extern cstring cstring_makeLiteral (char *) /*@*/ ;
 156 extern /*@observer@*/ /*@dependent@*/ cstring
 157   cstring_makeLiteralTemp (char *) /*@*/ ;
 158
 159 # define cstring_makeLiteral(s) (cstring_copy (cstring_fromChars (s)))
 160 # define cstring_makeLiteralTemp(s) (cstring_fromChars (s))
 161
 162 extern cstring cstring_capitalize (cstring p_s) /*@*/  /*@requires maxSet(p_s) >= 0 @*/ ;
 163 extern cstring cstring_capitalizeFree (/*@only@*/ cstring p_s) /*@modifies p_s@*/  /*@requires maxSet(p_s) >= 0 /\ maxRead(p_s) >= 0 @*/ ;
 164
 165 extern cstring cstring_fill (cstring p_s, size_t p_n) /*@*/ /*@requires p_n >= 0 @*/;
 166
 167 extern cstring cstring_prefix (cstring p_s, size_t p_n)
 168    /*@*/
 169    /*@requires maxRead(p_s) >= p_n /\ maxSet(p_s) >= p_n @*/
 170    /*@ensures maxRead(result) == p_n /\ maxSet(result) == p_n @*/ ;
 171
 172 extern /*@observer@*/ cstring cstring_suffix (cstring p_s, size_t p_n) /*@*/ ;
 173 extern cstring cstring_concat (cstring p_s, cstring p_t) /*@*/ /*@requires maxSet(p_s) >= 0 @*/;
 174
 175 extern cstring
 176   cstring_concatFree (/*@only@*/ cstring p_s, /*@only@*/ cstring p_t)
 177   /*@modifies p_s, p_t@*/ ;
 178
 179 extern cstring
 180   cstring_concatFree1 (/*@only@*/ cstring p_s, cstring p_t)
 181   /*@modifies p_s@*/ ;
 182
 183 # ifndef NOLCL
 184 extern cstring
 185   cstring_concatChars (/*@only@*/ cstring p_s, char *p_t)
 186   /*@modifies p_s@*/ ;
 187
 188 extern lsymbol cstring_toSymbol (/*@only@*/ cstring p_s) /*@*/ ;
 189 # endif
 190
 191 extern void cstring_markOwned (/*@owned@*/ cstring p_s) /*@modifies p_s@*/ ;
 192
 193 extern cstring cstring_beforeChar (cstring p_s, char p_c) /*@*/ ;
 194 extern /*@exposed@*/ cstring cstring_afterChar (cstring p_s, char p_c) /*@*/ ;
 195
 196 /*@iter cstring_chars (sef cstring s, yield char c);@*/
 197 # define cstring_chars(s, m_c) \
 198   if (cstring_isDefined (s)) \
 199     { char *m_current = (char *) (s); \
 200       char m_c; \
 201       for (; (m_c = *m_current) != '\0'; m_current++) {
 202 # define end_cstring_chars }}
 203
 204 extern /*@observer@*/ cstring cstring_advanceWhiteSpace (cstring) /*@*/ ;
 205
 206 extern /*@only@*/ /*@notnull@*/ cstring
 207 cstring_copySegment (cstring p_s, size_t p_findex, size_t p_tindex) /*@*/ ;
 208
 209 /*drl added 01/22/2001  Expands the escape squences i.e "\\n\\t\\000"
 210  becomes "\n\t0"  */
 211 extern /*@notnull@*/ cstring  cstring_expandEscapes (cstring p_s);
 212
 213 /*drl added 01/23/2001  Gives you the number of characters in an
 214   expanded escape squences.  This can be different from strlen bc/ of
 215   escaped nulls.  */
 216 int  cstring_lengthExpandEscapes (cstring p_s);
 217
 218
 219 extern bool cstring_containsLit (/*@unique@*/ cstring p_c, char *p_sub) /*@*/ ;
 220 # define cstring_containsLit(c,sub) \
 221   (cstring_contains (c, cstring_fromChars (sub)))
 222
 223 /*drl added July 2, 001 */
 224 extern int cstring_compareLit (/*@unique@*/ cstring p_c, char *p_sub) /*@*/ ;
 225 # define cstring_compareLit(c,sub) \
 226   (cstring_compare (c, cstring_fromChars (sub)))
 227
 228 /*drl added 2/4/2002*/
 229 /*replaces every instance of the character old with the character new
 230   old can not be '\0'
 231 */
 232 cstring cstring_replaceChar(/*@returned@*/ cstring p_c, char p_oldChar, char p_newChar);
 233
 234 # else
 235 # error "Multiple include"
 236 # endif
 237
 238
 239