oops :)
[apps/madmutt.git] / 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 ssize_t m_strwidth(const char *s);
197
198 /****************************************************************************/
199 /* comparisons                                                              */
200 /****************************************************************************/
201
202 /** \brief \c NULL resistant strcmp.
203  * \param[in]  a     the first string.
204  * \param[in]  b     the second string.
205  * \return <tt>strcmp(a, b)</tt>, and treats \c NULL strings like \c "" ones.
206  */
207 static inline int m_strcmp(const char *a, const char *b) {
208     return strcmp(NONULL(a), NONULL(b));
209 }
210
211 /** \brief \c NULL resistant strcasecmp.
212  * \param[in]  a     the first string.
213  * \param[in]  b     the second string.
214  * \return <tt>strcasecmp(a, b)</tt>, and treats \c NULL strings like \c ""
215  * ones.
216  */
217 static inline int m_strcasecmp(const char *a, const char *b) {
218     return strcasecmp(NONULL(a), NONULL(b));
219 }
220
221 /** \brief \c NULL resistant strncmp.
222  * \param[in]  a     the first string.
223  * \param[in]  b     the second string.
224  * \param[in]  n     the number of maximum chars to compare.
225  * \return <tt>strncmp(a, b, n)</tt>, and treats \c NULL strings like \c ""
226  * ones.
227  */
228 static inline int m_strncmp(const char *a, const char *b, ssize_t n) {
229     return strncmp(NONULL(a), NONULL(b), n);
230 }
231
232 /** \brief \c NULL resistant strncasecmp.
233  * \param[in]  a     the first string.
234  * \param[in]  b     the second string.
235  * \param[in]  n     the number of maximum chars to compare.
236  * \return <tt>strcasecmp(a, b, n)</tt>, and treats \c NULL strings like \c ""
237  * ones.
238  */
239 static inline int m_strncasecmp(const char *a, const char *b, ssize_t n) {
240     return strncasecmp(NONULL(a), NONULL(b), n);
241 }
242
243 int ascii_strcasecmp(const char *a, const char *b);
244 int ascii_strncasecmp(const char *a, const char *b, ssize_t n);
245
246 /****************************************************************************/
247 /* making copies                                                            */
248 /****************************************************************************/
249
250 /** \brief \c NULL resistant strdup.
251  *
252  * the m_strdup() function returns a pointer to a new string, which is a
253  * duplicate of \c s. Memory should be freed using p_delete().
254  *
255  * \warning when s is \c "", it returns NULL !
256  *
257  * \param[in]  s    the string to duplicate.
258  * \return a pointer to the duplicated string.
259  */
260 static inline char *m_strdup(const char *s) {
261     ssize_t len = m_strlen(s);
262     return len ? p_dup(s, len + 1) : NULL;
263 }
264
265 /** \brief Duplicate substrings.
266  * \deprecated API IS NOT GOOD, I WILL DEPRECATE IT IN A NEAR FUTURE.
267  */
268 static inline char *m_substrdup(const char *s, const char *end) {
269     return p_dupstr(s, end ? end - s : m_strlen(s));
270 }
271
272 /** \brief Replace an allocated string with another.
273  *
274  * Replace the string pointed by \c *p with a copy of the string \c s.
275  * \c *p must point to a buffer allocated with p_new() or one of its alias.
276  *
277  * \param[in,out]  p    a pointer on a string (<tt>char **</tt>)
278  * \param[in]      s    the string to copy into p.
279  * \return a pointer on the duplicated string (aka \c *p).
280  */
281 __attribute__((nonnull(1)))
282 static inline char *m_strreplace(char **p, const char *s) {
283     p_delete(p);
284     return (*p = m_strdup(s));
285 }
286
287 /** \brief Puts a char in a string buffer.
288  *
289  * Puts a char at position 0 of a string buffer of size \c n.
290  * Then \c \\0 terminate the buffer.
291  *
292  * \param[in]  dst   pointer to the buffer.
293  * \param[in]  n     size of that buffer (negative values allowed).
294  * \param[in]  c     the character to append.
295  * \return always return 1.
296  */
297 __attribute__((nonnull(1)))
298 static inline ssize_t m_strputc(char *dst, ssize_t n, int c) {
299     if (n > 1) {
300         dst[0] = c;
301         dst[1] = '\0';
302     }
303     return 1;
304 }
305
306 /** \brief Sets a portion of a string to a defined character, à la memset.
307  *
308  * \param[in]  dst  pointer to the buffer.
309  * \param[in]  n    size of that buffer, (negative values allowed).
310  * \param[in]  c    the char to use in the padding.
311  * \param[in]  len  length of the padding.
312  * \return MAX(0, len).
313  */
314 __attribute__((nonnull(1)))
315 static inline ssize_t m_strpad(char *dst, ssize_t n, int c, ssize_t len)
316 {
317     ssize_t dlen = MIN(n - 1, len);
318     if (dlen > 0) {
319         memset(dst, c, dlen);
320         dst[dlen] = '\0';
321     }
322     return MAX(0, len);
323 }
324
325 ssize_t m_strcpy(char *dst, ssize_t n, const char *src)
326     __attribute__((nonnull(1)));
327
328 ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l)
329     __attribute__((nonnull(1)));
330
331 /** \brief safe strcat.
332  *
333  * The m_strcat() function appends the string \c src at the end of the buffer
334  * \c dst if space is available.
335  *
336  * \param[in]  dst   destination buffer.
337  * \param[in]  n     size of the buffer, Negative sizes are allowed.
338  * \param[in]  src   the string to append.
339  * \return <tt>m_strlen(dst) + m_strlen(src)</tt>
340  */
341 static inline ssize_t m_strcat(char *dst, ssize_t n, const char *src) {
342     ssize_t dlen = m_strnlen(dst, n - 1);
343     return dlen + m_strcpy(dst + dlen, n - dlen, src);
344 }
345
346 /** \brief safe strncat.
347  *
348  * The m_strncat() function appends at most \c n chars from the string \c src
349  * at the end of the buffer \c dst if space is available.
350  *
351  * \param[in]  dst   destination buffer.
352  * \param[in]  n     size of the buffer, Negative sizes are allowed.
353  * \param[in]  src   the string to append.
354  * \param[in]  l     maximum number of chars of src to consider.
355  * \return the smallest value between <tt>m_strlen(dst) + m_strlen(src)</tt>
356  *         and <tt>m_strlen(dst) + l</tt>
357  */
358 static inline ssize_t
359 m_strncat(char *dst, ssize_t n, const char *src, ssize_t l) {
360     ssize_t dlen = m_strnlen(dst, n - 1);
361     return dlen + m_strncpy(dst + dlen, n - dlen, src, l);
362 }
363
364 /* flags for m_strformat() */
365 typedef enum {
366   M_FORMAT_FORCESUBJ   = (1 << 0),  /* print the subject even if unchanged */
367   M_FORMAT_TREE        = (1 << 1),  /* draw the thread tree */
368   M_FORMAT_MAKEPRINT   = (1 << 2),  /* make sure that all chars are printable */
369   M_FORMAT_OPTIONAL    = (1 << 3),
370   M_FORMAT_STAT_FILE   = (1 << 4),  /* used by mutt_attach_fmt */
371   M_FORMAT_ARROWCURSOR = (1 << 5),  /* reserve space for arrow_cursor */
372   M_FORMAT_INDEX       = (1 << 6)   /* this is a main index entry */
373 } format_flag;
374
375 typedef const char *
376 format_t(char *, ssize_t, char, const char *,
377          const char *, const char *, const char *, anytype, format_flag);
378
379 ssize_t m_strformat(char *, ssize_t, int, const char *,
380                     format_t *, anytype, format_flag);
381
382 /****************************************************************************/
383 /* parsing related                                                          */
384 /****************************************************************************/
385
386 __attribute__((nonnull(1)))
387 static inline const char *m_strchrnul(const char *s, int c) {
388     while (*s && *s != c)
389         s++;
390     return s;
391 }
392
393 __attribute__((nonnull(1)))
394 static inline const char *m_strnextsp(const char *s) {
395     while (*s && !isspace((unsigned char)*s))
396         s++;
397     return s;
398 }
399
400 __attribute__((nonnull(1)))
401 static inline const char *skipspaces(const char *s) {
402     while (isspace((unsigned char)*s))
403         s++;
404     return s;
405 }
406 __attribute__((nonnull(1)))
407 static inline char *vskipspaces(const char *s) {
408     return (char *)skipspaces(s);
409 }
410
411 char *m_strrtrim(char *s);
412
413 /****************************************************************************/
414 /* search                                                                   */
415 /****************************************************************************/
416
417 const char *
418 m_stristrn(const char *haystack, const char *needle, ssize_t nlen);
419
420 static inline const char *
421 m_stristr(const char *haystack, const char *needle) {
422     return m_stristrn(haystack, needle, m_strlen(needle));
423 }
424
425 /*@}*/
426 #endif /* MUTT_LIB_LIB_STR_H */