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 octal digit into an int.
  98  * \param[in]  c    the octal char
  99  * \return
 100  *   - 0&ndash;7 if c is a valid octal digit,
 101  *   - -1 on error.
 102  */
 103 static inline int octval(int c) {
 104     return !(c & ~127) && __m_strdigits[c] < 7 ? __m_strdigits[c] : -1;
 105 }
 106
 107 /** \brief Converts an hexadecimal digit into an int.
 108  * \param[in]  c    the hexadecimal char
 109  * \return
 110  *   - 0&ndash;15 if c is a valid hexadecimal digit,
 111  *   - -1 on error.
 112  */
 113 static inline int hexval(int c) {
 114     return !(c & ~127) && __m_strdigits[c] < 16 ? __m_strdigits[c] : -1;
 115 }
 116
 117 /** \brief Converts a base64 digit into an int.
 118  * \param[in]  c    the base64 char
 119  * \return
 120  *   - 0&ndash;15 if c is a valid base64 digit,
 121  *   - -1 on error.
 122  */
 123 static inline int base64val(int c) {
 124     return (c & ~127) ? -1 : __m_b64digits[c];
 125 }
 126
 127 /** \brief Converts a string to lowercase.
 128  * \param[in] p     the string, shall not be \c NULL.
 129  * \return a pointer to the terminating \c \\0.
 130  */
 131 __attribute__((nonnull(1)))
 132 static inline char *m_strtolower(char *p) {
 133     for (; *p; p++)
 134         *p = tolower((unsigned char)*p);
 135     return p;
 136 }
 137
 138 /** \brief Converts a lower case ascii char to upper case.
 139  * \param[in]  c    the character.
 140  * \return the upper case character.
 141  */
 142 static inline int ascii_toupper(int c) {
 143     if ('a' <= c && c <= 'z')
 144         return c & ~32;
 145
 146     return c;
 147 }
 148
 149 /** \brief Converts a upper case ascii char to lower case.
 150  * \param[in]  c    the character.
 151  * \return the lower case character.
 152  */
 153 static inline int ascii_tolower(int c) {
 154     if ('A' <= c && c <= 'Z')
 155         return c | 32;
 156
 157     return c;
 158 }
 159
 160 /****************************************************************************/
 161 /* length related                                                           */
 162 /****************************************************************************/
 163
 164 /** \brief Short hand to test if a string is empty or not.
 165  * \param[in]  s    the string.
 166  * \return \c true iff s is an empty string.
 167  */
 168 static inline int m_strisempty(const char *s) {
 169     return !s || !*s;
 170 }
 171
 172 /** \brief \c NULL resistant strlen.
 173  *
 174  * Unlinke it's libc sibling, m_strlen returns a ssize_t, and supports its
 175  * argument beeing NULL.
 176  *
 177  * \param[in]  s    the string.
 178  * \return the string length (or 0 if \c s is \c NULL).
 179  */
 180 static inline ssize_t m_strlen(const char *s) {
 181     return s ? strlen(s) : 0;
 182 }
 183
 184 /** \brief \c NULL resistant strnlen.
 185  *
 186  * Unlinke it's GNU libc sibling, m_strnlen returns a ssize_t, and supports
 187  * its argument beeing NULL.
 188  *
 189  * The m_strnlen() function returns the number of characters in the string
 190  * pointed to by \c s, not including the terminating \c \\0 character, but at
 191  * most \c n. In doing this, m_strnlen() looks only at the first \c n
 192  * characters at \c s and never beyond \c s+n.
 193  *
 194  * \param[in]  s    the string.
 195  * \param[in]  n    the maximum length to return.
 196  * \return \c m_strlen(s) if less than \c n, else \c n.
 197  */
 198 static inline ssize_t m_strnlen(const char *s, ssize_t n) {
 199     if (s) {
 200         const char *p = memchr(s, '\0', n);
 201         return p ? p - s : n;
 202     }
 203     return 0;
 204 }
 205
 206 ssize_t m_strwidth(const char *s);
 207
 208 /****************************************************************************/
 209 /* comparisons                                                              */
 210 /****************************************************************************/
 211
 212 /** \brief Tells whether s begins with p.
 213  *
 214  * \param[in]  s     the input string
 215  * \param[in]  p     the prefix
 216  * \param[out] pp    position in s
 217  *
 218  * \return 1 if a match is found, 0 otherwise.
 219  */
 220 static inline int m_strstart(const char *s, const char *p, const char **pp)
 221 {
 222     if (!s)
 223         return 0;
 224
 225     while (*p) {
 226         if (*s++ != *p++)
 227             return 0;
 228     }
 229     if (pp)
 230         *pp = s;
 231     return 1;
 232 }
 233
 234 /** \brief \c NULL resistant strcmp.
 235  * \param[in]  a     the first string.
 236  * \param[in]  b     the second string.
 237  * \return <tt>strcmp(a, b)</tt>, and treats \c NULL strings like \c "" ones.
 238  */
 239 static inline int m_strcmp(const char *a, const char *b) {
 240     return strcmp(NONULL(a), NONULL(b));
 241 }
 242
 243 /** \brief \c NULL resistant strcasecmp.
 244  * \param[in]  a     the first string.
 245  * \param[in]  b     the second string.
 246  * \return <tt>strcasecmp(a, b)</tt>, and treats \c NULL strings like \c ""
 247  * ones.
 248  */
 249 static inline int m_strcasecmp(const char *a, const char *b) {
 250     return strcasecmp(NONULL(a), NONULL(b));
 251 }
 252
 253 /** \brief \c NULL resistant strncmp.
 254  * \param[in]  a     the first string.
 255  * \param[in]  b     the second string.
 256  * \param[in]  n     the number of maximum chars to compare.
 257  * \return <tt>strncmp(a, b, n)</tt>, and treats \c NULL strings like \c ""
 258  * ones.
 259  */
 260 static inline int m_strncmp(const char *a, const char *b, ssize_t n) {
 261     return strncmp(NONULL(a), NONULL(b), n);
 262 }
 263
 264 /** \brief \c NULL resistant strncasecmp.
 265  * \param[in]  a     the first string.
 266  * \param[in]  b     the second string.
 267  * \param[in]  n     the number of maximum chars to compare.
 268  * \return <tt>strcasecmp(a, b, n)</tt>, and treats \c NULL strings like \c ""
 269  * ones.
 270  */
 271 static inline int m_strncasecmp(const char *a, const char *b, ssize_t n) {
 272     return strncasecmp(NONULL(a), NONULL(b), n);
 273 }
 274
 275 int ascii_strcasecmp(const char *a, const char *b);
 276 int ascii_strncasecmp(const char *a, const char *b, ssize_t n);
 277
 278 /****************************************************************************/
 279 /* making copies                                                            */
 280 /****************************************************************************/
 281
 282 /** \brief \c NULL resistant strdup.
 283  *
 284  * the m_strdup() function returns a pointer to a new string, which is a
 285  * duplicate of \c s. Memory should be freed using p_delete().
 286  *
 287  * \warning when s is \c "", it returns NULL !
 288  *
 289  * \param[in]  s    the string to duplicate.
 290  * \return a pointer to the duplicated string.
 291  */
 292 static inline char *m_strdup(const char *s) {
 293     ssize_t len = m_strlen(s);
 294     return len ? p_dup(s, len + 1) : NULL;
 295 }
 296
 297 /** \brief Duplicate substrings.
 298  * \deprecated API IS NOT GOOD, I WILL DEPRECATE IT IN A NEAR FUTURE.
 299  */
 300 static inline char *m_substrdup(const char *s, const char *end) {
 301     return p_dupstr(s, end ? end - s : m_strlen(s));
 302 }
 303
 304 /** \brief Replace an allocated string with another.
 305  *
 306  * Replace the string pointed by \c *p with a copy of the string \c s.
 307  * \c *p must point to a buffer allocated with p_new() or one of its alias.
 308  *
 309  * \param[in,out]  p    a pointer on a string (<tt>char **</tt>)
 310  * \param[in]      s    the string to copy into p.
 311  * \return a pointer on the duplicated string (aka \c *p).
 312  */
 313 __attribute__((nonnull(1)))
 314 static inline char *m_strreplace(char **p, const char *s) {
 315     p_delete(p);
 316     return (*p = m_strdup(s));
 317 }
 318
 319 /** \brief Puts a char in a string buffer.
 320  *
 321  * Puts a char at position 0 of a string buffer of size \c n.
 322  * Then \c \\0 terminate the buffer.
 323  *
 324  * \param[in]  dst   pointer to the buffer.
 325  * \param[in]  n     size of that buffer (negative values allowed).
 326  * \param[in]  c     the character to append.
 327  * \return always return 1.
 328  */
 329 __attribute__((nonnull(1)))
 330 static inline ssize_t m_strputc(char *dst, ssize_t n, int c) {
 331     if (n > 1) {
 332         dst[0] = c;
 333         dst[1] = '\0';
 334     }
 335     return 1;
 336 }
 337
 338 /** \brief Sets a portion of a string to a defined character, à la memset.
 339  *
 340  * \param[in]  dst  pointer to the buffer.
 341  * \param[in]  n    size of that buffer, (negative values allowed).
 342  * \param[in]  c    the char to use in the padding.
 343  * \param[in]  len  length of the padding.
 344  * \return MAX(0, len).
 345  */
 346 __attribute__((nonnull(1)))
 347 static inline ssize_t m_strpad(char *dst, ssize_t n, int c, ssize_t len)
 348 {
 349     ssize_t dlen = MIN(n - 1, len);
 350     if (dlen > 0) {
 351         memset(dst, c, dlen);
 352         dst[dlen] = '\0';
 353     }
 354     return MAX(0, len);
 355 }
 356
 357 ssize_t m_strcpy(char *dst, ssize_t n, const char *src)
 358     __attribute__((nonnull(1)));
 359
 360 ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l)
 361     __attribute__((nonnull(1)));
 362
 363 /** \brief safe strcat.
 364  *
 365  * The m_strcat() function appends the string \c src at the end of the buffer
 366  * \c dst if space is available.
 367  *
 368  * \param[in]  dst   destination buffer.
 369  * \param[in]  n     size of the buffer, Negative sizes are allowed.
 370  * \param[in]  src   the string to append.
 371  * \return <tt>m_strlen(dst) + m_strlen(src)</tt>
 372  */
 373 static inline ssize_t m_strcat(char *dst, ssize_t n, const char *src) {
 374     ssize_t dlen = m_strnlen(dst, n - 1);
 375     return dlen + m_strcpy(dst + dlen, n - dlen, src);
 376 }
 377
 378 /** \brief safe strncat.
 379  *
 380  * The m_strncat() function appends at most \c n chars from the string \c src
 381  * at the end of the buffer \c dst if space is available.
 382  *
 383  * \param[in]  dst   destination buffer.
 384  * \param[in]  n     size of the buffer, Negative sizes are allowed.
 385  * \param[in]  src   the string to append.
 386  * \param[in]  l     maximum number of chars of src to consider.
 387  * \return the smallest value between <tt>m_strlen(dst) + m_strlen(src)</tt>
 388  *         and <tt>m_strlen(dst) + l</tt>
 389  */
 390 static inline ssize_t
 391 m_strncat(char *dst, ssize_t n, const char *src, ssize_t l) {
 392     ssize_t dlen = m_strnlen(dst, n - 1);
 393     return dlen + m_strncpy(dst + dlen, n - dlen, src, l);
 394 }
 395
 396 /* flags for m_strformat() */
 397 typedef enum {
 398   M_FORMAT_FORCESUBJ   = (1 << 0),  /* print the subject even if unchanged */
 399   M_FORMAT_TREE        = (1 << 1),  /* draw the thread tree */
 400   M_FORMAT_MAKEPRINT   = (1 << 2),  /* make sure that all chars are printable */
 401   M_FORMAT_OPTIONAL    = (1 << 3),
 402   M_FORMAT_STAT_FILE   = (1 << 4),  /* used by mutt_attach_fmt */
 403   M_FORMAT_ARROWCURSOR = (1 << 5),  /* reserve space for arrow_cursor */
 404   M_FORMAT_INDEX       = (1 << 6)   /* this is a main index entry */
 405 } format_flag;
 406
 407 typedef const char *
 408 format_t(char *, ssize_t, char, const char *,
 409          const char *, const char *, const char *, anytype, format_flag);
 410
 411 ssize_t m_strformat(char *, ssize_t, int, const char *,
 412                     format_t *, anytype, format_flag);
 413
 414 /****************************************************************************/
 415 /* parsing related                                                          */
 416 /****************************************************************************/
 417
 418 __attribute__((nonnull(1)))
 419 static inline const char *m_strchrnul(const char *s, int c) {
 420     while (*s && *s != c)
 421         s++;
 422     return s;
 423 }
 424
 425 __attribute__((nonnull(1)))
 426 static inline const char *m_strnextsp(const char *s) {
 427     while (*s && !isspace((unsigned char)*s))
 428         s++;
 429     return s;
 430 }
 431
 432 __attribute__((nonnull(1)))
 433 static inline const char *skipspaces(const char *s) {
 434     while (isspace((unsigned char)*s))
 435         s++;
 436     return s;
 437 }
 438 __attribute__((nonnull(1)))
 439 static inline char *vskipspaces(const char *s) {
 440     return (char *)skipspaces(s);
 441 }
 442
 443 char *m_strrtrim(char *s);
 444
 445 /****************************************************************************/
 446 /* search                                                                   */
 447 /****************************************************************************/
 448
 449 const char *
 450 m_stristrn(const char *haystack, const char *needle, ssize_t nlen);
 451
 452 static inline const char *
 453 m_stristr(const char *haystack, const char *needle) {
 454     return m_stristrn(haystack, needle, m_strlen(needle));
 455 }
 456
 457 /*@}*/
 458 #endif /* MUTT_LIB_LIB_STR_H */