lib-lib/str.h

   1 /*
   2  *  This program is free software; you can redistribute it and/or modify
   3  *  it under the terms of the GNU General Public License as published by
   4  *  the Free Software Foundation; either version 2 of the License, or (at
   5  *  your option) any later version.
   6  *
   7  *  This program is distributed in the hope that it will be useful, but
   8  *  WITHOUT ANY WARRANTY; without even the implied warranty of
   9  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  10  *  General Public License for more details.
  11  *
  12  *  You should have received a copy of the GNU General Public License
  13  *  along with this program; if not, write to the Free Software
  14  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  15  *  MA 02110-1301, USA.
  16  *
  17  *  Copyright © 2006 Pierre Habouzit
  18  */
  19 /*
  20  * Copyright notice from original mutt:
  21  * Copyright (C) 2001 Thomas Roessler <roessler@does-not-exist.org>
  22  */
  23
  24 #ifndef MUTT_LIB_LIB_STR_H
  25 #define MUTT_LIB_LIB_STR_H
  26
  27 /** \defgroup mutt_strings Madmutt string API
  28  *
  29  * This module contains the prefered string API to be used in Madmutt.
  30  *
  31  * Those function reimplement many usual calls (strlen, strcpy, strcat, …)
  32  * It's intended to provide a uniform and consistent API to deal with usual C
  33  * strings.
  34  *
  35  * The strong point that have to be followed are:
  36  *  - strings are always \c \\0 terminated, meaning that we don't have
  37  *    stupid semantics à la strncpy.
  38  *  - function try to always work on buffers with its size (including the
  39  *    ending \c \\0) to prevent buffer overflows.
  40  *  - string and buffers sizes are \c ssize_t, negative values are allowed and
  41  *    supported.
  42  *  - functions use a à la sprintf semantics (for those that produce strings)
  43  *    meaning that they all return the len that could have fit in the buffer
  44  *    if it would have been big enough. We never try to reallocate the
  45  *    buffers, it's up to the caller if it's needed.
  46  *
  47  * Many of the function do no difference between \c NULL and \c "" and will
  48  * behave the same when you pass either the former or the latter (m_strlen(),
  49  * m_strcpy(), ... to cite a few).
  50  */
  51 /*@{*/
  52
  53 /** \file str.h
  54  * \brief Madmutt string API header.
  55  * \author Pierre Habouzit <madcoder@debian.org>
  56  */
  57
  58 #define HUGE_STRING     5120   /**< \brief Huge buffers */
  59 #define LONG_STRING     1024   /**< \brief Long buffers */
  60 #define STRING          256    /**< \brief Usual buffers */
  61
  62 /** \brief replace \c NULL strings with emtpy strings */
  63 #define NONULL(x)       (x ? x : "")
  64 /** \brief safe isspace */
  65 #define ISSPACE(c)      isspace((unsigned char)c)
  66
  67 /** \brief Convert ascii digits into ints.
  68  *
  69  * Convert ascii digits into its integer value in base 36.
  70  * Non convertible values are converted to 255.
  71  *
  72  * Translating a digit \c c into its numerical value in base \c x is just doing:
  73  * \code
  74  *   return !(c & ~127) && __m_strdigits[c] < x ? __m_strdigits[c] : -1;
  75  * \endcode
  76  */
  77 extern unsigned char const __m_strdigits[128];
  78 /** \brief Convert an ascii base64 digit into ints.
  79  *
  80  * Convert an a char base64 digit into its int value.
  81  * Used by base64val(). Unlike #__m_strdigits, the invalid values are set to
  82  * -1 instead of 255.
  83  */
  84 extern signed char const __m_b64digits[128];
  85
  86 /** \brief Convert ints from 0&ndash;64 into the corresponding base64 digit. */
  87 extern char const __m_b64chars[64];
  88 /** \brief Convert ints from 0&ndash;36 into a base36 lowercase digit. */
  89 extern char const __m_b36chars_lower[36];
  90 /** \brief Convert ints from 0&ndash;36 into a base36 uppercase digit. */
  91 extern char const __m_b36chars_upper[36];
  92
  93 /****************************************************************************/
  94 /* conversions                                                              */
  95 /****************************************************************************/
  96
  97 /** \brief Converts an hexadecimal digit into an int.
  98  * \param[in]  c    the hexadecimal char
  99  * \return
 100  *   - 0&ndash;15 if c is a valid hexadecimal digit,
 101  *   - -1 on error.
 102  */
 103 static inline int hexval(int c) {
 104     return !(c & ~127) && __m_strdigits[c] < 16 ? __m_strdigits[c] : -1;
 105 }
 106
 107 /** \brief Converts a base64 digit into an int.
 108  * \param[in]  c    the base64 char
 109  * \return
 110  *   - 0&ndash;15 if c is a valid base64 digit,
 111  *   - -1 on error.
 112  */
 113 static inline int base64val(int c) {
 114     return (c & ~127) ? -1 : __m_b64digits[c];
 115 }
 116
 117 /** \brief Converts a string to lowercase.
 118  * \param[in] p     the string, shall not be \c NULL.
 119  * \return a pointer to the terminating \c \\0.
 120  */
 121 __attribute__((nonnull(1)))
 122 static inline char *m_strtolower(char *p) {
 123     for (; *p; p++)
 124         *p = tolower((unsigned char)*p);
 125     return p;
 126 }
 127
 128 /** \brief Converts a lower case ascii char to upper case.
 129  * \param[in]  c    the character.
 130  * \return the upper case character.
 131  */
 132 static inline int ascii_toupper(int c) {
 133     if ('a' <= c && c <= 'z')
 134         return c & ~32;
 135
 136     return c;
 137 }
 138
 139 /** \brief Converts a upper case ascii char to lower case.
 140  * \param[in]  c    the character.
 141  * \return the lower case character.
 142  */
 143 static inline int ascii_tolower(int c) {
 144     if ('A' <= c && c <= 'Z')
 145         return c | 32;
 146
 147     return c;
 148 }
 149
 150 /****************************************************************************/
 151 /* length related                                                           */
 152 /****************************************************************************/
 153
 154 /** \brief Short hand to test if a string is empty or not.
 155  * \param[in]  s    the string.
 156  * \return \c true iff s is an empty string.
 157  */
 158 static inline int m_strisempty(const char *s) {
 159     return !s || !*s;
 160 }
 161
 162 /** \brief \c NULL resistant strlen.
 163  *
 164  * Unlinke it's libc sibling, m_strlen returns a ssize_t, and supports its
 165  * argument beeing NULL.
 166  *
 167  * \param[in]  s    the string.
 168  * \return the string length (or 0 if \c s is \c NULL).
 169  */
 170 static inline ssize_t m_strlen(const char *s) {
 171     return s ? strlen(s) : 0;
 172 }
 173
 174 /** \brief \c NULL resistant strnlen.
 175  *
 176  * Unlinke it's GNU libc sibling, m_strnlen returns a ssize_t, and supports
 177  * its argument beeing NULL.
 178  *
 179  * The m_strnlen() function returns the number of characters in the string
 180  * pointed to by \c s, not including the terminating \c \\0 character, but at
 181  * most \c n. In doing this, m_strnlen() looks only at the first \c n
 182  * characters at \c s and never beyond \c s+n.
 183  *
 184  * \param[in]  s    the string.
 185  * \param[in]  n    the maximum length to return.
 186  * \return \c m_strlen(s) if less than \c n, else \c n.
 187  */
 188 static inline ssize_t m_strnlen(const char *s, ssize_t n) {
 189     if (s) {
 190         const char *p = memchr(s, '\0', n);
 191         return p ? p - s : n;
 192     }
 193     return 0;
 194 }
 195
 196 /****************************************************************************/
 197 /* comparisons                                                              */
 198 /****************************************************************************/
 199
 200 /** \brief \c NULL resistant strcmp.
 201  * \param[in]  a     the first string.
 202  * \param[in]  b     the second string.
 203  * \return <tt>strcmp(a, b)</tt>, and treats \c NULL strings like \c "" ones.
 204  */
 205 static inline int m_strcmp(const char *a, const char *b) {
 206     return strcmp(NONULL(a), NONULL(b));
 207 }
 208
 209 /** \brief \c NULL resistant strcasecmp.
 210  * \param[in]  a     the first string.
 211  * \param[in]  b     the second string.
 212  * \return <tt>strcasecmp(a, b)</tt>, and treats \c NULL strings like \c ""
 213  * ones.
 214  */
 215 static inline int m_strcasecmp(const char *a, const char *b) {
 216     return strcasecmp(NONULL(a), NONULL(b));
 217 }
 218
 219 /** \brief \c NULL resistant strncmp.
 220  * \param[in]  a     the first string.
 221  * \param[in]  b     the second string.
 222  * \param[in]  n     the number of maximum chars to compare.
 223  * \return <tt>strncmp(a, b, n)</tt>, and treats \c NULL strings like \c ""
 224  * ones.
 225  */
 226 static inline int m_strncmp(const char *a, const char *b, ssize_t n) {
 227     return strncmp(NONULL(a), NONULL(b), n);
 228 }
 229
 230 /** \brief \c NULL resistant strncasecmp.
 231  * \param[in]  a     the first string.
 232  * \param[in]  b     the second string.
 233  * \param[in]  n     the number of maximum chars to compare.
 234  * \return <tt>strcasecmp(a, b, n)</tt>, and treats \c NULL strings like \c ""
 235  * ones.
 236  */
 237 static inline int m_strncasecmp(const char *a, const char *b, ssize_t n) {
 238     return strncasecmp(NONULL(a), NONULL(b), n);
 239 }
 240
 241 int ascii_strcasecmp(const char *a, const char *b);
 242 int ascii_strncasecmp(const char *a, const char *b, ssize_t n);
 243
 244 /****************************************************************************/
 245 /* making copies                                                            */
 246 /****************************************************************************/
 247
 248 /** \brief \c NULL resistant strdup.
 249  *
 250  * the m_strdup() function returns a pointer to a new string, which is a
 251  * duplicate of \c s. Memory should be freed using p_delete().
 252  *
 253  * \warning when s is \c "", it returns NULL !
 254  *
 255  * \param[in]  s    the string to duplicate.
 256  * \return a pointer to the duplicated string.
 257  */
 258 static inline char *m_strdup(const char *s) {
 259     ssize_t len = m_strlen(s);
 260     return len ? p_dup(s, len + 1) : NULL;
 261 }
 262
 263 /** \brief Duplicate substrings.
 264  * \deprecated API IS NOT GOOD, I WILL DEPRECATE IT IN A NEAR FUTURE.
 265  */
 266 static inline char *m_substrdup(const char *s, const char *end) {
 267     return p_dupstr(s, end ? end - s : m_strlen(s));
 268 }
 269
 270 /** \brief Replace an allocated string with another.
 271  *
 272  * Replace the string pointed by \c *p with a copy of the string \c s.
 273  * \c *p must point to a buffer allocated with p_new() or one of its alias.
 274  *
 275  * \param[in,out]  p    a pointer on a string (<tt>char **</tt>)
 276  * \param[in]      s    the string to copy into p.
 277  * \return a pointer on the duplicated string (aka \c *p).
 278  */
 279 __attribute__((nonnull(1)))
 280 static inline char *m_strreplace(char **p, const char *s) {
 281     p_delete(p);
 282     return (*p = m_strdup(s));
 283 }
 284
 285 /** \brief Puts a char in a string buffer.
 286  *
 287  * Puts a char at position 0 of a string buffer of size \c n.
 288  * Then \c \\0 terminate the buffer.
 289  *
 290  * \param[in]  dst   pointer to the buffer.
 291  * \param[in]  n     size of that buffer (negative values allowed).
 292  * \param[in]  c     the character to append.
 293  * \return always return 1.
 294  */
 295 __attribute__((nonnull(1)))
 296 static inline ssize_t m_strputc(char *dst, ssize_t n, int c) {
 297     if (n > 1) {
 298         dst[0] = c;
 299         dst[1] = '\0';
 300     }
 301     return 1;
 302 }
 303
 304 /** \brief Sets a portion of a string to a defined character, à la memset.
 305  *
 306  * \param[in]  dst  pointer to the buffer.
 307  * \param[in]  n    size of that buffer, (negative values allowed).
 308  * \param[in]  c    the char to use in the padding.
 309  * \param[in]  len  length of the padding.
 310  * \return MAX(0, len).
 311  */
 312 __attribute__((nonnull(1)))
 313 static inline ssize_t m_strpad(char *dst, ssize_t n, int c, ssize_t len)
 314 {
 315     ssize_t dlen = MIN(n - 1, len);
 316     if (dlen > 0) {
 317         memset(dst, c, dlen);
 318         dst[dlen] = '\0';
 319     }
 320     return MAX(0, len);
 321 }
 322
 323 ssize_t m_strcpy(char *dst, ssize_t n, const char *src)
 324     __attribute__((nonnull(1)));
 325
 326 ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l)
 327     __attribute__((nonnull(1)));
 328
 329 /** \brief safe strcat.
 330  *
 331  * The m_strcat() function appends the string \c src at the end of the buffer
 332  * \c dst if space is available.
 333  *
 334  * \param[in]  dst   destination buffer.
 335  * \param[in]  n     size of the buffer, Negative sizes are allowed.
 336  * \param[in]  src   the string to append.
 337  * \return <tt>m_strlen(dst) + m_strlen(src)</tt>
 338  */
 339 static inline ssize_t m_strcat(char *dst, ssize_t n, const char *src) {
 340     ssize_t dlen = m_strnlen(dst, n - 1);
 341     return dlen + m_strcpy(dst + dlen, n - dlen, src);
 342 }
 343
 344 /** \brief safe strncat.
 345  *
 346  * The m_strncat() function appends at most \c n chars from the string \c src
 347  * at the end of the buffer \c dst if space is available.
 348  *
 349  * \param[in]  dst   destination buffer.
 350  * \param[in]  n     size of the buffer, Negative sizes are allowed.
 351  * \param[in]  src   the string to append.
 352  * \param[in]  l     maximum number of chars of src to consider.
 353  * \return the smallest value between <tt>m_strlen(dst) + m_strlen(src)</tt>
 354  *         and <tt>m_strlen(dst) + l</tt>
 355  */
 356 static inline ssize_t
 357 m_strncat(char *dst, ssize_t n, const char *src, ssize_t l) {
 358     ssize_t dlen = m_strnlen(dst, n - 1);
 359     return dlen + m_strncpy(dst + dlen, n - dlen, src, l);
 360 }
 361
 362 /****************************************************************************/
 363 /* parsing related                                                          */
 364 /****************************************************************************/
 365
 366 __attribute__((nonnull(1)))
 367 static inline const char *m_strchrnul(const char *s, int c) {
 368     while (*s && *s != c)
 369         s++;
 370     return s;
 371 }
 372
 373 __attribute__((nonnull(1)))
 374 static inline const char *m_strnextsp(const char *s) {
 375     while (*s && !isspace((unsigned char)*s))
 376         s++;
 377     return s;
 378 }
 379
 380 __attribute__((nonnull(1)))
 381 static inline const char *skipspaces(const char *s) {
 382     while (isspace((unsigned char)*s))
 383         s++;
 384     return s;
 385 }
 386 __attribute__((nonnull(1)))
 387 static inline char *vskipspaces(const char *s) {
 388     return (char *)skipspaces(s);
 389 }
 390
 391 char *m_strrtrim(char *s);
 392
 393 /****************************************************************************/
 394 /* search                                                                   */
 395 /****************************************************************************/
 396
 397 const char *
 398 m_stristrn(const char *haystack, const char *needle, ssize_t nlen);
 399
 400 static inline const char *
 401 m_stristr(const char *haystack, const char *needle) {
 402     return m_stristrn(haystack, needle, m_strlen(needle));
 403 }
 404
 405 /*@}*/
 406 #endif /* MUTT_LIB_LIB_STR_H */