str.h

Go to the documentation of this file.
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 */

Generated on Sun Dec 3 17:45:53 2006 for lucid by  doxygen 1.5.1