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.
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.
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,
17 * Copyright © 2006 Pierre Habouzit
20 * Copyright notice from original mutt:
21 * Copyright (C) 2001 Thomas Roessler <roessler@does-not-exist.org>
24 #ifndef MUTT_LIB_LIB_STR_H
25 #define MUTT_LIB_LIB_STR_H
27 /** \defgroup mutt_strings Madmutt string API
29 * This module contains the prefered string API to be used in Madmutt.
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
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
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.
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).
54 * \brief Madmutt string API header.
55 * \author Pierre Habouzit <madcoder@debian.org>
58 #define HUGE_STRING 5120 /**< \brief Huge buffers */
59 #define LONG_STRING 1024 /**< \brief Long buffers */
60 #define STRING 256 /**< \brief Usual buffers */
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)
67 /** \brief Convert ascii digits into ints.
69 * Convert ascii digits into its integer value in base 36.
70 * Non convertible values are converted to 255.
72 * Translating a digit \c c into its numerical value in base \c x is just doing:
74 * return !(c & ~127) && __m_strdigits[c] < x ? __m_strdigits[c] : -1;
77 extern unsigned char const __m_strdigits[128];
78 /** \brief Convert an ascii base64 digit into ints.
80 * Convert an a char base64 digit into its int value.
81 * Used by base64val(). Unlike #__m_strdigits, the invalid values are set to
84 extern signed char const __m_b64digits[128];
86 /** \brief Convert ints from 0–64 into the corresponding base64 digit. */
87 extern char const __m_b64chars[64];
88 /** \brief Convert ints from 0–36 into a base36 lowercase digit. */
89 extern char const __m_b36chars_lower[36];
90 /** \brief Convert ints from 0–36 into a base36 uppercase digit. */
91 extern char const __m_b36chars_upper[36];
93 /****************************************************************************/
95 /****************************************************************************/
97 /** \brief Converts an hexadecimal digit into an int.
98 * \param[in] c the hexadecimal char
100 * - 0–15 if c is a valid hexadecimal digit,
103 static inline int hexval(int c) {
104 return !(c & ~127) && __m_strdigits[c] < 16 ? __m_strdigits[c] : -1;
107 /** \brief Converts a base64 digit into an int.
108 * \param[in] c the base64 char
110 * - 0–15 if c is a valid base64 digit,
113 static inline int base64val(int c) {
114 return (c & ~127) ? -1 : __m_b64digits[c];
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.
121 __attribute__((nonnull(1)))
122 static inline char *m_strtolower(char *p) {
124 *p = tolower((unsigned char)*p);
128 /** \brief Converts a lower case ascii char to upper case.
129 * \param[in] c the character.
130 * \return the upper case character.
132 static inline int ascii_toupper(int c) {
133 if ('a' <= c && c <= 'z')
139 /** \brief Converts a upper case ascii char to lower case.
140 * \param[in] c the character.
141 * \return the lower case character.
143 static inline int ascii_tolower(int c) {
144 if ('A' <= c && c <= 'Z')
150 /****************************************************************************/
152 /****************************************************************************/
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.
158 static inline int m_strisempty(const char *s) {
162 /** \brief \c NULL resistant strlen.
164 * Unlinke it's libc sibling, m_strlen returns a ssize_t, and supports its
165 * argument beeing NULL.
167 * \param[in] s the string.
168 * \return the string length (or 0 if \c s is \c NULL).
170 static inline ssize_t m_strlen(const char *s) {
171 return s ? strlen(s) : 0;
174 /** \brief \c NULL resistant strnlen.
176 * Unlinke it's GNU libc sibling, m_strnlen returns a ssize_t, and supports
177 * its argument beeing NULL.
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.
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.
188 static inline ssize_t m_strnlen(const char *s, ssize_t n) {
190 const char *p = memchr(s, '\0', n);
191 return p ? p - s : n;
196 /****************************************************************************/
198 /****************************************************************************/
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.
205 static inline int m_strcmp(const char *a, const char *b) {
206 return strcmp(NONULL(a), NONULL(b));
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 ""
215 static inline int m_strcasecmp(const char *a, const char *b) {
216 return strcasecmp(NONULL(a), NONULL(b));
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 ""
226 static inline int m_strncmp(const char *a, const char *b, ssize_t n) {
227 return strncmp(NONULL(a), NONULL(b), n);
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 ""
237 static inline int m_strncasecmp(const char *a, const char *b, ssize_t n) {
238 return strncasecmp(NONULL(a), NONULL(b), n);
241 int ascii_strcasecmp(const char *a, const char *b);
242 int ascii_strncasecmp(const char *a, const char *b, ssize_t n);
244 /****************************************************************************/
246 /****************************************************************************/
248 /** \brief \c NULL resistant strdup.
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().
253 * \warning when s is \c "", it returns NULL !
255 * \param[in] s the string to duplicate.
256 * \return a pointer to the duplicated string.
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;
263 /** \brief Duplicate substrings.
264 * \deprecated API IS NOT GOOD, I WILL DEPRECATE IT IN A NEAR FUTURE.
266 static inline char *m_substrdup(const char *s, const char *end) {
267 return p_dupstr(s, end ? end - s : m_strlen(s));
270 /** \brief Replace an allocated string with another.
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.
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).
279 __attribute__((nonnull(1)))
280 static inline char *m_strreplace(char **p, const char *s) {
282 return (*p = m_strdup(s));
285 /** \brief Puts a char in a string buffer.
287 * Puts a char at position 0 of a string buffer of size \c n.
288 * Then \c \\0 terminate the buffer.
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.
295 __attribute__((nonnull(1)))
296 static inline ssize_t m_strputc(char *dst, ssize_t n, int c) {
304 /** \brief Sets a portion of a string to a defined character, à la memset.
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).
312 __attribute__((nonnull(1)))
313 static inline ssize_t m_strpad(char *dst, ssize_t n, int c, ssize_t len)
315 ssize_t dlen = MIN(n - 1, len);
317 memset(dst, c, dlen);
323 ssize_t m_strcpy(char *dst, ssize_t n, const char *src)
324 __attribute__((nonnull(1)));
326 ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l)
327 __attribute__((nonnull(1)));
329 /** \brief safe strcat.
331 * The m_strcat() function appends the string \c src at the end of the buffer
332 * \c dst if space is available.
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>
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);
344 /** \brief safe strncat.
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.
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>
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);
362 /****************************************************************************/
363 /* parsing related */
364 /****************************************************************************/
366 __attribute__((nonnull(1)))
367 static inline const char *m_strchrnul(const char *s, int c) {
368 while (*s && *s != c)
373 __attribute__((nonnull(1)))
374 static inline const char *m_strnextsp(const char *s) {
375 while (*s && !isspace((unsigned char)*s))
380 __attribute__((nonnull(1)))
381 static inline const char *skipspaces(const char *s) {
382 while (isspace((unsigned char)*s))
386 __attribute__((nonnull(1)))
387 static inline char *vskipspaces(const char *s) {
388 return (char *)skipspaces(s);
391 char *m_strrtrim(char *s);
393 /****************************************************************************/
395 /****************************************************************************/
398 m_stristrn(const char *haystack, const char *needle, ssize_t nlen);
400 static inline const char *
401 m_stristr(const char *haystack, const char *needle) {
402 return m_stristrn(haystack, needle, m_strlen(needle));
406 #endif /* MUTT_LIB_LIB_STR_H */