00001 // Copyright (C) 2006-2007 Benedikt Böhm <hollow@gentoo.org> 00002 // 00003 // This program is free software; you can redistribute it and/or 00004 // modify it under the terms of the GNU General Public License 00005 // as published by the Free Software Foundation; either version 2 00006 // of the License, or (at your option) any later version. 00007 // 00008 // This program 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. See the 00011 // GNU General Public License for more details. 00012 // 00013 // You should have received a copy of the GNU General Public License 00014 // along with this program; if not, write to the Free Software 00015 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 00016 00017 /*! 00018 * @defgroup str String classification and conversion 00019 * 00020 * The str_check family of functions extend the classification of single 00021 * characters to strings. The str_check() function checks the string pointed to 00022 * by str for a set of allowed character classes. As soon as a character is 00023 * found that is not allowed checking stops and 0 is returned. 00024 * 00025 * The str_cmp() function compares the string pointed to by str1 to the string 00026 * pointed to by str2. It returns an integer less than, equal to, or greater 00027 * than zero if str1 is found, respectively, to be less than, to match, or be 00028 * greater than str2. 00029 * 00030 * The strcpy() function copies the string pointed to by src (including the 00031 * terminating `\\0' character) to the array pointed to by dst. The strings may 00032 * not overlap, and the destination string dst must be large enough to receive 00033 * the copy. The strncpy() function is similar, except that not more than n 00034 * bytes of src are copied. Thus, if there is no null byte among the first n 00035 * bytes of src, the result will not be null-terminated. 00036 * 00037 * The str_dup() function returns a pointer to a new string which is a duplicate 00038 * of the string str. The str_dupn() function is similar, but only copies at 00039 * most n characters. If s is longer than n, only n characters are copied, and a 00040 * terminating null byte is added. 00041 * 00042 * The str_index() returns a pointer to the first occurence of the character c 00043 * in the string pointed to by str. 00044 * 00045 * The str_len() function calculates the length of the string str, not including 00046 * the terminating `\\0' character. 00047 * 00048 * The str_path_concat() function concatenates the directory name pointed to by 00049 * dirname and file name pointed to by basename and checks that the latter does 00050 * not contain any dot entries. 00051 * 00052 * The str_path_isabs() and str_path_isdot() functions check if the file path 00053 * pointed to by str is absolute or contains dots, respectively. 00054 * 00055 * The str_toupper() and str_tolower() functions map lower-case to upper case 00056 * and vice-versa, respectively. 00057 * 00058 * The str_zero() function sets the first n bytes of the byte area starting at s 00059 * to zero (bytes containing '\\0'). 00060 * 00061 * The str_toumax() function converts the string pointed to by str to an 00062 * unsigned long long int val using base as conversion base. 00063 * 00064 * @{ 00065 */ 00066 00067 #ifndef _LUCID_STR_H 00068 #define _LUCID_STR_H 00069 00070 /*! @brief class for alpha-numerical characters */ 00071 #define CC_ALNUM (1 << 1) 00072 00073 /*! @brief class for upper- or lower-case characters */ 00074 #define CC_ALPHA (1 << 2) 00075 00076 /*! @brief class for ASCII characters */ 00077 #define CC_ASCII (1 << 3) 00078 00079 /*! @brief class for blank characters */ 00080 #define CC_BLANK (1 << 4) 00081 00082 /*! @brief class for ASCII control characters */ 00083 #define CC_CNTRL (1 << 5) 00084 00085 /*! @brief class for digit characters */ 00086 #define CC_DIGIT (1 << 6) 00087 00088 /*! @brief class for graphable characters */ 00089 #define CC_GRAPH (1 << 7) 00090 00091 /*! @brief class for lower-case characters */ 00092 #define CC_LOWER (1 << 8) 00093 00094 /*! @brief class for printable characters */ 00095 #define CC_PRINT (1 << 9) 00096 00097 /*! @brief class for punctuation characters */ 00098 #define CC_PUNCT (1 << 10) 00099 00100 /*! @brief class for white space characters */ 00101 #define CC_SPACE (1 << 11) 00102 00103 /*! @brief class for upper-case characters */ 00104 #define CC_UPPER (1 << 12) 00105 00106 /*! @brief class for hexadecimal characters */ 00107 #define CC_XDIGIT (1 << 13) 00108 00109 /*! 00110 * @brief check string against classes of allowed characters 00111 * 00112 * @param[in] str string to check 00113 * @param[in] allowed allowed classes of characters (multiple classes by ORing) 00114 * 00115 * @return 1 if all characters are valid, 0 otherwise 00116 */ 00117 int str_check(const char *str, int allowed); 00118 00119 /*! @brief check if string is empty */ 00120 #define str_isempty(str) (!str || str_check(str, CC_BLANK)) 00121 00122 /*! @brief check string for alpha-numerical characters */ 00123 #define str_isalnum(str) str_check(str, CC_ALNUM) 00124 00125 /*! @brief check string for upper- or lower-case characters */ 00126 #define str_isalpha(str) str_check(str, CC_ALPHA) 00127 00128 /*! @brief check string for ASCII characters */ 00129 #define str_isascii(str) str_check(str, CC_ASCII) 00130 00131 /*! @brief check string for digit characters */ 00132 #define str_isdigit(str) str_check(str, CC_DIGIT) 00133 00134 /*! @brief check string for graphable characters */ 00135 #define str_isgraph(str) str_check(str, CC_GRAPH) 00136 00137 /*! @brief check string for lower-case characters */ 00138 #define str_islower(str) str_check(str, CC_LOWER) 00139 00140 /*! @brief check string for printable characters */ 00141 #define str_isprint(str) str_check(str, CC_PRINT) 00142 00143 /*! @brief check string for upper-case characters */ 00144 #define str_isupper(str) str_check(str, CC_UPPER) 00145 00146 /*! @brief check string for hexadecimal characters */ 00147 #define str_isxdigit(str) str_check(str, CC_XDIGIT) 00148 00149 00150 /*! 00151 * @brief compare two strings 00152 * 00153 * @param[in] str1 first string 00154 * @param[in] str2 second string 00155 * 00156 * @return An integer greater than, equal to, or less than 0, if the string 00157 * pointed to by str1 is greater than, equal to, or less than the string 00158 * pointed to by str2, respectively. 00159 */ 00160 int str_cmp(const char *str1, const char *str2); 00161 00162 /*! 00163 * @brief compare two strings 00164 * 00165 * @param[in] str1 first string 00166 * @param[in] str2 second string 00167 * @param[in] n compare first n bytes 00168 * 00169 * @return An integer greater than, equal to, or less than 0, if the string 00170 * pointed to by str1 is greater than, equal to, or less than the string 00171 * pointed to by str2, respectively. 00172 */ 00173 int str_cmpn(const char *str1, const char *str2, int n); 00174 00175 /*! 00176 * @brief compare two strings 00177 * 00178 * @param[in] str1 first string 00179 * @param[in] str2 second string 00180 * 00181 * @return 1 if both strings are equal, 0 otherwise. 00182 */ 00183 int str_equal(const char *str1, const char *str2); 00184 00185 /*! 00186 * @brief copy a string 00187 * 00188 * @param[out] dst destination string 00189 * @param[in] src source string 00190 * 00191 * @return A pointer to dst. 00192 */ 00193 char *str_cpy(char *dst, const char *src); 00194 00195 /*! 00196 * @brief copy a string 00197 * 00198 * @param[out] dst destination string 00199 * @param[in] src source string 00200 * @param[in] n copy at most n bytes 00201 * 00202 * @return A pointer to dst. 00203 */ 00204 char *str_cpyn(char *dst, const char *src, int n); 00205 00206 /*! 00207 * @brief duplicate a string 00208 * 00209 * @param[in] str source string 00210 * 00211 * @return A pointer to the duplicated string, or NULL if insufficient memory 00212 * was available. 00213 */ 00214 char *str_dup(const char *str); 00215 00216 /*! 00217 * @brief scan string for character 00218 * 00219 * @param[in] str string to scan 00220 * @param[in] c character to look for 00221 * @param[in] n scan first n bytes 00222 * 00223 * @return A pointer to the matched character or NULL if the character is not 00224 * found. 00225 */ 00226 char *str_chr(const char *str, int c, int n); 00227 00228 /*! 00229 * @brief scan string for character beginning at the end 00230 * 00231 * @param[in] str string to scan 00232 * @param[in] c character to look for 00233 * @param[in] n scan first n bytes 00234 * 00235 * @return A pointer to the matched character or NULL if the character is not 00236 * found. 00237 */ 00238 char *str_rchr(const char *str, int c, int n); 00239 00240 /*! 00241 * @brief locate a substring 00242 * 00243 * @param[in] str string to scan 00244 * @param[in] needle string to look for 00245 * 00246 * @return A pointer to the matched substring or NULL if the substring is not 00247 * found. 00248 */ 00249 char *str_str(const char *str, const char *needle); 00250 00251 /*! 00252 * @brief calculate the length of a string 00253 * 00254 * @param[in] str source string 00255 * 00256 * @return number of characters in str 00257 */ 00258 int str_len(const char *str); 00259 00260 00261 /*! 00262 * @brief parse directory component 00263 * 00264 * @param[in] path path to parse 00265 * 00266 * @return A pointer to the newly allocated string or NULL if insufficent memory 00267 * was available. 00268 */ 00269 char *str_path_dirname(const char *path); 00270 00271 /*! 00272 * @brief parse basename component 00273 * 00274 * @param[in] path path to parse 00275 * 00276 * @return A pointer to the newly allocated string or NULL if insufficent memory 00277 * was available. 00278 */ 00279 char *str_path_basename(const char *path); 00280 00281 /*! 00282 * @brief concatenate dirname and basename 00283 * 00284 * @param[in] dirname directory part 00285 * @param[in] basename basename part 00286 * 00287 * @return A pointer to the newly allocated string or NULL if insufficent memory 00288 * was available. 00289 */ 00290 char *str_path_concat(const char *dirname, const char *basename); 00291 00292 /*! 00293 * @brief check if path is absolute and contains no dot entries or ungraphable characters 00294 * 00295 * @param[in] str path to check 00296 * 00297 * @return 1 if str is an absolute pathname, 0 otherwise 00298 * 00299 * @note this function does not check if the path exists 00300 */ 00301 int str_path_isabs(const char *str); 00302 00303 /*! 00304 * @brief check if given path contains . or .. entries 00305 * 00306 * @param[in] str path to check 00307 * 00308 * @return 1 if str has dot entries, 0 otherwise 00309 */ 00310 int str_path_isdot(const char *str); 00311 00312 00313 /*! 00314 * @brief convert string to lower-case 00315 * 00316 * @param[out] str string to convert 00317 * 00318 * @return pointer to str 00319 */ 00320 char *str_tolower(char *str); 00321 00322 /*! 00323 * @brief convert string to upper-case 00324 * 00325 * @param[out] str string to convert 00326 * 00327 * @return pointer to str 00328 */ 00329 char *str_toupper(char *str); 00330 00331 00332 /*! 00333 * @brief convert string to integer 00334 * 00335 * @param[in] str source string 00336 * @param[out] val destination integer 00337 * @param[in] base conversion base 00338 * @param[in] n convert first n bytes 00339 * 00340 * @return Number of bytes read from str 00341 */ 00342 int str_toumax(const char *str, unsigned long long int *val, int base, int n); 00343 00344 00345 /*! bytes read at a time */ 00346 #define CHUNKSIZE 4096 00347 00348 /*! 00349 * @brief read a line of input 00350 * 00351 * @param[in] fd file descriptor to read from 00352 * @param[out] line pointer to a string 00353 * 00354 * @return bytes on success, -1 on error with errno set 00355 * 00356 * @note The caller should free obtained memory for line using free(3) 00357 * 00358 * @see malloc(3) 00359 * @see free(3) 00360 * @see read(2) 00361 */ 00362 int str_readline(int fd, char **str); 00363 00364 /*! 00365 * @brief read until end of file 00366 * 00367 * @param[in] fd file descriptor to read from 00368 * @param[out] file pointer to a string 00369 * 00370 * @return bytes on success, -1 on error with errno set 00371 * 00372 * @note The caller should free obtained memory for file using free(3) 00373 * 00374 * @see malloc(3) 00375 * @see free(3) 00376 * @see read(2) 00377 */ 00378 int str_readfile(int fd, char **str); 00379 00380 /*! 00381 * @brief read exact number of bytes 00382 * 00383 * @param[in] fd file descriptor to read from 00384 * @param[out] str pointer to a string 00385 * @param[in] len bytes to be read 00386 * 00387 * @return bytes read on success, -1 on error with errno set 00388 * 00389 * @note The caller should free obtained memory for str using free(3) 00390 * 00391 * @see malloc(3) 00392 * @see free(3) 00393 * @see read(2) 00394 */ 00395 int str_read(int fd, char **str, int len); 00396 00397 #endif 00398 00399 /*! @} str */