1 #ifndef STR__H__ 2 #define STR__H__ 3 4 #include <stdarg.h> 5 #include "sysdeps.h" 6 7 /** \defgroup str str: Dynamically allocated string library. 8 9 \par Calling Convention 10 The standard calling convention to \c str functions is to pass the 11 string being examined or modified as the first argument. For most 12 functions, the return value will be \c 0 (false) if an error occurred 13 (ie memory allocation failed) and non-zero (true) otherwise. 14 15 @{ */ 16 17 /** The block size in which string memory is allocated. 18 * 19 * \c STR_BLOCKSIZE should be set to at least the size at which the 20 * allocator (ie \c malloc) will align the data it returns. String data 21 * will be allocated in steps of this number. Values smaller than the 22 * alignment will only cause a small amount of space to be wasted, and 23 * will not trigger bugs. 24 */ 25 #define STR_BLOCKSIZE 16 26 27 /** The basic string structure. 28 \note Initialize to <tt>{0,0,0}</tt>. 29 */ 30 struct str 31 { 32 /** The pointer to the allocated data. This string will always be 33 * terminated with a \c NUL byte to ensure compatibility with standard 34 * C string functions. May be used directly by programs, but should 35 * not be assigned. */ 36 char* s; 37 /** The length of the string data inside the above block. May be used 38 * directly by programs, but should not be assigned a non-zero 39 * value.*/ 40 unsigned len; 41 /** The size of the above block. */ 42 unsigned size; 43 }; 44 /** String structure typedef. */ 45 typedef struct str str; 46 47 /** 48 This struct is used to serve in lists of pointers into a string for sorting. 49 Only used as parameters to the comparison function in \c str_sort 50 */ 51 struct str_sortentry 52 { 53 /** Pointer to the string data to compare. */ 54 const char* str; 55 /** Length of the string data to compare. */ 56 unsigned long len; 57 }; 58 /** String sort entry typedef. */ 59 typedef struct str_sortentry str_sortentry; 60 61 /** \name Globals 62 * @{ */ 63 extern const char str_lcase_digits[36] __DEPRECATED__; 64 extern const char str_ucase_digits[36] __DEPRECATED__; 65 /** @} */ 66 67 /** \name Overhead Functions 68 * @{ */ 69 int str_init(str* s); 70 int str_alloc(str* s, unsigned size, int copy); 71 /** Make sure string S has at least SZ bytes ready (no copy) */ 72 #define str_ready(S,SZ) str_alloc(S,SZ,0) 73 /** Reallocate string S to size SZ bytes, copying the existing string */ 74 #define str_realloc(S,SZ) str_alloc(S,SZ,1) 75 void str_free(str* s); 76 int str_truncate(str* s, unsigned len); 77 /** @} */ 78 79 /** \name Assignment Functions 80 * @{ */ 81 int str_copy(str* s, const str* in); 82 int str_copys(str* s, const char* in); 83 int str_copyb(str* s, const char* in, unsigned len); 84 int str_copyf(str* s, const char* format, ...); 85 int str_copyfv(str* s, const char* format, va_list ap); 86 int str_copyns(str* s, unsigned int count, ...); 87 int str_copy2s(str* s, const char* a, const char* b); 88 int str_copy3s(str* s, const char* a, const char* b, const char* c); 89 int str_copy4s(str* s, const char* a, const char* b, const char* c, const char* d); 90 int str_copy5s(str* s, const char* a, const char* b, const char* c, const char* d, const char* e); 91 int str_copy6s(str* s, const char* a, const char* b, const char* c, const char* d, const char* e, const char* f); 92 /** @} */ 93 94 /** \name Appending Functions 95 * @{ */ 96 int str_cat(str* s, const str* in); 97 int str_cats(str* s, const char* in); 98 int str_catc(str* s, char in); 99 int str_catb(str* s, const char* in, unsigned len); 100 int str_catf(str* s, const char* format, ...); 101 int str_catfv(str* s, const char* format, va_list ap); 102 int str_cati(str* s, long in); 103 int str_catiw(str* s, long in, unsigned width, char pad); 104 int str_catu(str* s, unsigned long in); 105 int str_catuw(str* s, unsigned long in, unsigned width, char pad); 106 int str_catx(str* s, unsigned long in); 107 int str_catxw(str* s, unsigned long in, unsigned width, char pad); 108 int str_catill(str* s, long long in); 109 int str_catiwll(str* s, long long in, unsigned width, char pad); 110 int str_catull(str* s, unsigned long long in); 111 int str_catuwll(str* s, unsigned long long in, unsigned width, char pad); 112 int str_catxll(str* s, unsigned long long in); 113 int str_catxwll(str* s, unsigned long long in, unsigned width, char pad); 114 int str_catsnumw(str* s, long in, unsigned width, char pad, 115 unsigned base, const char* digits); 116 int str_catunumw(str* s, unsigned long in, unsigned width, char pad, 117 unsigned base, const char* digits); 118 int str_catsllnumw(str* s, long long in, unsigned width, char pad, 119 unsigned base, const char* digits); 120 int str_catullnumw(str* s, unsigned long long in, unsigned width, char pad, 121 unsigned base, const char* digits); 122 int str_catns(str* s, unsigned int count, ...); 123 int str_cat2s(str* s, const char* a, const char* b); 124 int str_cat3s(str* s, const char* a, const char* b, const char* c); 125 int str_cat4s(str* s, const char* a, const char* b, const char* c, const char* d); 126 int str_cat5s(str* s, const char* a, const char* b, const char* c, const char* d, const char* e); 127 int str_cat6s(str* s, const char* a, const char* b, const char* c, const char* d, const char* e, const char* f); 128 129 int str_join(str* s, char sep, const str* t); 130 int str_joins(str* s, char sep, const char* in); 131 int str_joinb(str* s, char sep, const char* in, unsigned len); 132 /** @} */ 133 134 /** \name In-place Modification Functions */ 135 /* @{ */ 136 void str_lower(str* s); 137 void str_upper(str* s); 138 long str_subst(str* s, char from, char to); 139 void str_lstrip(str* s); 140 void str_rstrip(str* s); 141 #define str_strip(S) (str_rstrip(S), str_lstrip(S)) 142 void str_lcut(str* s, unsigned count); 143 void str_rcut(str* s, unsigned count); 144 int str_sort(str* s, char sep, long count, 145 int (*fn)(const str_sortentry* a, const str_sortentry* b)); 146 int str_splice(str* s, unsigned start, unsigned len, const str* r); 147 int str_splices(str* s, unsigned start, unsigned len, const char* r); 148 int str_spliceb(str* s, unsigned start, unsigned len, 149 const char* r, unsigned rlen); 150 long str_xlate(str* s, const char* from, const char* to, unsigned nchars); 151 /** @} */ 152 153 /** \name Comparison Functions 154 * @{ */ 155 int str_cmp(const str* a, unsigned aoffset, const str* b, unsigned boffset); 156 int str_cmps(const str* a, unsigned offset, const char* b); 157 int str_cmpb(const str* a, unsigned offset, const char* b, unsigned len); 158 159 int str_diff(const str* a, const str* b); 160 int str_diffs(const str* a, const char* b); 161 int str_diffb(const str* a, const char* b, unsigned len); 162 163 int str_start(const str* a, const str* b); 164 int str_starts(const str* a, const char* b); 165 int str_startb(const str* a, const char* b, unsigned len); 166 167 int str_case_start(const str* a, const str* b); 168 int str_case_starts(const str* a, const char* b); 169 int str_case_startb(const str* a, const char* b, unsigned len); 170 171 int str_end(const str* a, const str* b); 172 int str_ends(const str* a, const char* b); 173 int str_endb(const str* a, const char* b, unsigned len); 174 175 int str_case_end(const str* a, const str* b); 176 int str_case_ends(const str* a, const char* b); 177 int str_case_endb(const str* a, const char* b, unsigned len); 178 /** @} */ 179 180 /** \name Searching Functions 181 * @{ */ 182 void str_buildmap(int map[256], const char* list); 183 unsigned str_count(const str* s, char ch); 184 unsigned str_countof(const str* s, const char* list); 185 #define str_findfirst(S,C) str_findnext(S,C,0) 186 #define str_findfirstof(S,L) str_findnextof(S,L,0) 187 #define str_findfirstnot(S,L) str_findnextnot(S,L,0) 188 #define str_findlast(S,C) str_findprev(S,C,-1) 189 #define str_findlastof(S,L) str_findprevof(S,L,-1) 190 #define str_findlastnot(S,L) str_findprevof(S,L,-1) 191 int str_findnext(const str* s, char ch, unsigned pos); 192 int str_findnextof(const str* s, const char* list, unsigned pos); 193 int str_findnextnot(const str* s, const char* list, unsigned pos); 194 int str_findprev(const str* s, char ch, unsigned pos); 195 int str_findprevof(const str* s, const char* list, unsigned pos); 196 int str_findprevnot(const str* s, const char* list, unsigned pos); 197 /** @} */ 198 199 /** \name Pattern Matching Functions 200 * @{ */ 201 int str_match(const str* s, const str* pattern); 202 int str_matchb(const str* s, const char* pptr, unsigned plen); 203 int str_matchs(const str* s, const char* pattern); 204 int str_case_match(const str* s, const str* pattern); 205 int str_case_matchb(const str* s, const char* pptr, unsigned plen); 206 int str_case_matchs(const str* s, const char* pattern); 207 int str_glob(const str* s, const str* pattern); 208 int str_globb(const str* s, const char* pptr, unsigned plen); 209 int str_globs(const str* s, const char* pattern); 210 int str_case_glob(const str* s, const str* pattern); 211 int str_case_globb(const str* s, const char* pptr, unsigned plen); 212 int str_case_globs(const str* s, const char* pattern); 213 /** @} */ 214 215 /** @} */ 216 217 #endif 218