+/** \defgroup mutt_strings Madmutt string API
+ *
+ * This module contains the prefered string API to be used in Madmutt.
+ *
+ * Those function reimplement many usual calls (strlen, strcpy, strcat, …)
+ * It's intended to provide a uniform and consistent API to deal with usual C
+ * strings.
+ *
+ * The strong point that have to be followed are:
+ * - strings are always \c \\0 terminated, meaning that we don't have
+ * stupid semantics à la strncpy.
+ * - function try to always work on buffers with its size (including the
+ * ending \c \\0) to prevent buffer overflows.
+ * - string and buffers sizes are \c ssize_t, negative values are allowed and
+ * supported.
+ * - functions use a à la sprintf semantics (for those that produce strings)
+ * meaning that they all return the len that could have fit in the buffer
+ * if it would have been big enough. We never try to reallocate the
+ * buffers, it's up to the caller if it's needed.
+ *
+ * Many of the function do no difference between \c NULL and \c "" and will
+ * behave the same when you pass either the former or the latter (m_strlen(),
+ * m_strcpy(), ... to cite a few).
+ */
+/*@{*/
+
+/** \file str.h
+ * \brief Madmutt string API header.
+ * \author Pierre Habouzit <madcoder@debian.org>
+ */
+
+#define HUGE_STRING 5120 /**< \brief Huge buffers */
+#define LONG_STRING 1024 /**< \brief Long buffers */
+#define STRING 256 /**< \brief Usual buffers */
+
+/** \brief replace \c NULL strings with emtpy strings */
+#define NONULL(x) (x ? x : "")
+/** \brief safe isspace */
+#define ISSPACE(c) isspace((unsigned char)c)
+
+/** \brief Convert ascii digits into ints.
+ *
+ * Convert ascii digits into its integer value in base 36.
+ * Non convertible values are converted to 255.
+ *
+ * Translating a digit \c c into its numerical value in base \c x is just doing:
+ * \code
+ * return !(c & ~127) && __m_strdigits[c] < x ? __m_strdigits[c] : -1;
+ * \endcode
+ */
+extern unsigned char const __m_strdigits[128];
+/** \brief Convert an ascii base64 digit into ints.
+ *
+ * Convert an a char base64 digit into its int value.
+ * Used by base64val(). Unlike #__m_strdigits, the invalid values are set to
+ * -1 instead of 255.
+ */
+extern signed char const __m_b64digits[128];
+
+/** \brief Convert ints from 0–64 into the corresponding base64 digit. */
+extern char const __m_b64chars[64];
+/** \brief Convert ints from 0–36 into a base36 lowercase digit. */
+extern char const __m_b36chars_lower[36];
+/** \brief Convert ints from 0–36 into a base36 uppercase digit. */
+extern char const __m_b36chars_upper[36];
+
+/****************************************************************************/
+/* conversions */
+/****************************************************************************/
+
+/** \brief Converts an octal digit into an int.
+ * \param[in] c the octal char
+ * \return
+ * - 0–7 if c is a valid octal digit,
+ * - -1 on error.
+ */
+static inline int octval(int c) {
+ return !(c & ~127) && __m_strdigits[c] < 7 ? __m_strdigits[c] : -1;
+}
+
+/** \brief Converts an hexadecimal digit into an int.
+ * \param[in] c the hexadecimal char
+ * \return
+ * - 0–15 if c is a valid hexadecimal digit,
+ * - -1 on error.
+ */
+static inline int hexval(int c) {
+ return !(c & ~127) && __m_strdigits[c] < 16 ? __m_strdigits[c] : -1;
+}
+
+/** \brief Converts a base64 digit into an int.
+ * \param[in] c the base64 char
+ * \return
+ * - 0–15 if c is a valid base64 digit,
+ * - -1 on error.
+ */
+static inline int base64val(int c) {
+ return (c & ~127) ? -1 : __m_b64digits[c];
+}