X-Git-Url: http://git.madism.org/?a=blobdiff_plain;ds=sidebyside;f=lib-lib%2Fstr.h;h=8c793fb77d2578626a299d71d65631d13a534ed3;hb=4dbc0e4a9d573611d4f521400a2e16f47c176639;hp=d62dc0ad86435736cc93a229f11e37b7a9043660;hpb=c8b8b9539aaf11b48c4c1e5baba434db09722111;p=apps%2Fmadmutt.git

diff --git a/lib-lib/str.h b/lib-lib/str.h
index d62dc0a..8c793fb 100644
--- a/lib-lib/str.h
+++ b/lib-lib/str.h
@@ -24,19 +24,65 @@
 #ifndef MUTT_LIB_LIB_STR_H
 #define MUTT_LIB_LIB_STR_H
 
-#define HUGE_STRING     5120
-#define LONG_STRING     1024
-#define STRING          256
-#define SHORT_STRING    128
+/** \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.
+ */
+/*@{*/
+
+/** \file str.h
+ * \brief Madmutt string API header.
+ * \author Pierre Habouzit <madcoder@debian.org>
+ */
 
-#define NONULL(x) (x?x:"")
-#define ISSPACE(c) isspace((unsigned char)c)
+#define HUGE_STRING     5120   /**< \brief Huge buffers */
+#define LONG_STRING     1024   /**< \brief Long buffers */
+#define STRING          256    /**< \brief Usual buffers */
 
+#define NONULL(x)       (x ? x : "")  /**< \brief replace \c NULL strings
+                                                  with emtpy strings */
+#define ISSPACE(c)      isspace((unsigned char)c) /**< \brief safe isspace */
+
+/** \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];
-extern char const __m_b64chars[64];
 
+/** \brief Convert ints from 0&ndash;64 into the corresponding base64 digit. */
+extern char const __m_b64chars[64];
+/** \brief Convert ints from 0&ndash;36 into a base36 lowercase digit. */
 extern char const __m_b36chars_lower[36];
+/** \brief Convert ints from 0&ndash;36 into a base36 uppercase digit. */
 extern char const __m_b36chars_upper[36];
 
 /****************************************************************************/
@@ -100,7 +146,7 @@ static inline int m_strcasecmp(const char *a, const char *b) {
 }
 
 static inline int m_strncmp(const char *a, const char *b, ssize_t n) {
-    return strncmp (NONULL(a), NONULL(b), n);
+    return strncmp(NONULL(a), NONULL(b), n);
 }
 
 static inline int m_strncasecmp(const char *a, const char *b, ssize_t n) {
@@ -128,8 +174,19 @@ static inline char *m_strreplace(char **p, const char *s) {
     return (*p = m_strdup(s));
 }
 
-ssize_t m_strcpy(char *dst, ssize_t n, const char *src);
-ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l);
+static inline ssize_t m_strputc(char *dst, ssize_t n, int c) {
+    if (n > 1) {
+        dst[0] = c;
+        dst[1] = '\0';
+    }
+    return 1;
+}
+
+ssize_t m_strcpy(char *dst, ssize_t n, const char *src)
+    __attribute__((nonnull(1)));
+
+ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l)
+    __attribute__((nonnull(1)));
 
 static inline ssize_t m_strcat(char *dst, ssize_t n, const char *src) {
     ssize_t dlen = m_strnlen(dst, n - 1);
@@ -181,12 +238,5 @@ m_stristr(const char *haystack, const char *needle) {
     return m_stristrn(haystack, needle, m_strlen(needle));
 }
 
-
-/****************************************************************************/
-/* misc functions                                                           */
-/****************************************************************************/
-
-/* replace any %s with src, or appends " $src" */
-ssize_t m_snsubst(char *dst, ssize_t n, const char *fmt, const char *src);
-
+/*@}*/
 #endif /* MUTT_LIB_LIB_STR_H */