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