1 /******************************************************************************/
2 /* pfixtools: a collection of postfix related tools */
4 /* ________________________________________________________________________ */
6 /* Redistribution and use in source and binary forms, with or without */
7 /* modification, are permitted provided that the following conditions */
10 /* 1. Redistributions of source code must retain the above copyright */
11 /* notice, this list of conditions and the following disclaimer. */
12 /* 2. Redistributions in binary form must reproduce the above copyright */
13 /* notice, this list of conditions and the following disclaimer in the */
14 /* documentation and/or other materials provided with the distribution. */
15 /* 3. The names of its contributors may not be used to endorse or promote */
16 /* products derived from this software without specific prior written */
19 /* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND */
20 /* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE */
21 /* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR */
22 /* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS */
23 /* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR */
24 /* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF */
25 /* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS */
26 /* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN */
27 /* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) */
28 /* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF */
29 /* THE POSSIBILITY OF SUCH DAMAGE. */
30 /******************************************************************************/
33 * Copyright © 2006 Pierre Habouzit
36 #ifndef PFIXTOOLS_STR_H
37 #define PFIXTOOLS_STR_H
41 /** \defgroup mutt_strings Madmutt string API
43 * This module contains the prefered string API to be used in Madmutt.
45 * Those function reimplement many usual calls (strlen, strcpy, strcat, …)
46 * It's intended to provide a uniform and consistent API to deal with usual C
49 * The strong point that have to be followed are:
50 * - strings are always \c \\0 terminated, meaning that we don't have
51 * stupid semantics à la strncpy.
52 * - function try to always work on buffers with its size (including the
53 * ending \c \\0) to prevent buffer overflows.
54 * - string and buffers sizes are \c ssize_t, negative values are allowed and
56 * - functions use a à la sprintf semantics (for those that produce strings)
57 * meaning that they all return the len that could have fit in the buffer
58 * if it would have been big enough. We never try to reallocate the
59 * buffers, it's up to the caller if it's needed.
61 * Many of the function do no difference between \c NULL and \c "" and will
62 * behave the same when you pass either the former or the latter (m_strlen(),
63 * m_strcpy(), ... to cite a few).
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 octal digit into an int.
98 * \param[in] c the octal char
100 * - 0–7 if c is a valid octal digit,
103 static inline int octval(int c) {
104 return !(c & ~127) && __m_strdigits[c] < 7 ? __m_strdigits[c] : -1;
107 /** \brief Converts an hexadecimal digit into an int.
108 * \param[in] c the hexadecimal char
110 * - 0–15 if c is a valid hexadecimal digit,
113 static inline int hexval(int c) {
114 return !(c & ~127) && __m_strdigits[c] < 16 ? __m_strdigits[c] : -1;
117 /** \brief Converts a base64 digit into an int.
118 * \param[in] c the base64 char
120 * - 0–15 if c is a valid base64 digit,
123 static inline int base64val(int c) {
124 return (c & ~127) ? -1 : __m_b64digits[c];
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.
131 __attribute__((nonnull(1)))
132 static inline char *m_strtolower(char *p) {
134 *p = tolower((unsigned char)*p);
138 /** \brief Converts a lower case ascii char to upper case.
139 * \param[in] c the character.
140 * \return the upper case character.
142 static inline int ascii_toupper(int c) {
143 if ('a' <= c && c <= 'z')
149 /** \brief Converts a upper case ascii char to lower case.
150 * \param[in] c the character.
151 * \return the lower case character.
153 static inline int ascii_tolower(int c) {
154 if ('A' <= c && c <= 'Z')
160 /****************************************************************************/
162 /****************************************************************************/
164 /** \brief \c NULL resistant strlen.
166 * Unlinke it's libc sibling, m_strlen returns a ssize_t, and supports its
167 * argument beeing NULL.
169 * \param[in] s the string.
170 * \return the string length (or 0 if \c s is \c NULL).
172 static inline ssize_t m_strlen(const char *s) {
173 return s ? strlen(s) : 0;
176 /** \brief \c NULL resistant strnlen.
178 * Unlinke it's GNU libc sibling, m_strnlen returns a ssize_t, and supports
179 * its argument beeing NULL.
181 * The m_strnlen() function returns the number of characters in the string
182 * pointed to by \c s, not including the terminating \c \\0 character, but at
183 * most \c n. In doing this, m_strnlen() looks only at the first \c n
184 * characters at \c s and never beyond \c s+n.
186 * \param[in] s the string.
187 * \param[in] n the maximum length to return.
188 * \return \c m_strlen(s) if less than \c n, else \c n.
190 static inline ssize_t m_strnlen(const char *s, ssize_t n) {
192 const char *p = memchr(s, '\0', n);
193 return p ? p - s : n;
198 /****************************************************************************/
200 /****************************************************************************/
202 int ascii_strcasecmp(const char *a, const char *b);
203 int ascii_strncasecmp(const char *a, const char *b, ssize_t n);
205 /****************************************************************************/
207 /****************************************************************************/
209 /** \brief \c NULL resistant strdup.
211 * the m_strdup() function returns a pointer to a new string, which is a
212 * duplicate of \c s. Memory should be freed using p_delete().
214 * \warning when s is \c "", it returns NULL !
216 * \param[in] s the string to duplicate.
217 * \return a pointer to the duplicated string.
219 static inline char *m_strdup(const char *s) {
220 ssize_t len = m_strlen(s);
221 return len ? p_dup(s, len + 1) : NULL;
224 /** \brief Duplicate substrings.
225 * \deprecated API IS NOT GOOD, I WILL DEPRECATE IT IN A NEAR FUTURE.
227 static inline char *m_substrdup(const char *s, const char *end) {
228 return p_dupstr(s, end ? end - s : m_strlen(s));
231 /** \brief Replace an allocated string with another.
233 * Replace the string pointed by \c *p with a copy of the string \c s.
234 * \c *p must point to a buffer allocated with p_new() or one of its alias.
236 * \param[in,out] p a pointer on a string (<tt>char **</tt>)
237 * \param[in] s the string to copy into p.
238 * \return a pointer on the duplicated string (aka \c *p).
240 __attribute__((nonnull(1)))
241 static inline char *m_strreplace(char **p, const char *s) {
243 return (*p = m_strdup(s));
246 /** \brief Puts a char in a string buffer.
248 * Puts a char at position 0 of a string buffer of size \c n.
249 * Then \c \\0 terminate the buffer.
251 * \param[in] dst pointer to the buffer.
252 * \param[in] n size of that buffer (negative values allowed).
253 * \param[in] c the character to append.
254 * \return always return 1.
256 __attribute__((nonnull(1)))
257 static inline ssize_t m_strputc(char *dst, ssize_t n, int c) {
265 /** \brief Sets a portion of a string to a defined character, à la memset.
267 * \param[in] dst pointer to the buffer.
268 * \param[in] n size of that buffer, (negative values allowed).
269 * \param[in] c the char to use in the padding.
270 * \param[in] len length of the padding.
271 * \return MAX(0, len).
273 __attribute__((nonnull(1)))
274 static inline ssize_t m_strpad(char *dst, ssize_t n, int c, ssize_t len)
276 ssize_t dlen = MIN(n - 1, len);
278 memset(dst, c, dlen);
284 ssize_t m_strcpy(char *dst, ssize_t n, const char *src)
285 __attribute__((nonnull(1)));
287 ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l)
288 __attribute__((nonnull(1)));
290 /** \brief safe strcat.
292 * The m_strcat() function appends the string \c src at the end of the buffer
293 * \c dst if space is available.
295 * \param[in] dst destination buffer.
296 * \param[in] n size of the buffer, Negative sizes are allowed.
297 * \param[in] src the string to append.
298 * \return <tt>m_strlen(dst) + m_strlen(src)</tt>
300 static inline ssize_t m_strcat(char *dst, ssize_t n, const char *src) {
301 ssize_t dlen = m_strnlen(dst, n - 1);
302 return dlen + m_strcpy(dst + dlen, n - dlen, src);
305 /** \brief safe strncat.
307 * The m_strncat() function appends at most \c n chars from the string \c src
308 * at the end of the buffer \c dst if space is available.
310 * \param[in] dst destination buffer.
311 * \param[in] n size of the buffer, Negative sizes are allowed.
312 * \param[in] src the string to append.
313 * \param[in] l maximum number of chars of src to consider.
314 * \return the smallest value between <tt>m_strlen(dst) + m_strlen(src)</tt>
315 * and <tt>m_strlen(dst) + l</tt>
317 static inline ssize_t
318 m_strncat(char *dst, ssize_t n, const char *src, ssize_t l) {
319 ssize_t dlen = m_strnlen(dst, n - 1);
320 return dlen + m_strncpy(dst + dlen, n - dlen, src, l);
323 /****************************************************************************/
324 /* parsing related */
325 /****************************************************************************/
327 __attribute__((nonnull(1)))
328 static inline const char *m_strchrnul(const char *s, int c) {
329 while (*s && *s != c)
334 __attribute__((nonnull(1)))
335 static inline const char *m_strnextsp(const char *s) {
336 while (*s && !isspace((unsigned char)*s))
341 __attribute__((nonnull(1)))
342 static inline char *m_vstrnextsp(char *s) {
343 while (*s && !isspace((unsigned char)*s))
349 __attribute__((nonnull(1)))
350 static inline const char *skipspaces(const char *s) {
351 while (isspace((unsigned char)*s))
355 __attribute__((nonnull(1)))
356 static inline char *vskipspaces(const char *s) {
357 return (char *)skipspaces(s);
360 char *m_strrtrim(char *s);
362 /****************************************************************************/
364 /****************************************************************************/
367 m_stristrn(const char *haystack, const char *needle, ssize_t nlen);
369 static inline const char *
370 m_stristr(const char *haystack, const char *needle) {
371 return m_stristrn(haystack, needle, m_strlen(needle));
375 #endif /* PFIXTOOLS_STR_H */