str.h

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

Generated on Tue Jun 19 20:38:26 2007 for lucid by  doxygen 1.5.2