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

diff --git a/lib-lib/str.h b/lib-lib/str.h
index d62dc0a..51eeba4 100644
--- a/lib-lib/str.h
+++ b/lib-lib/str.h
@@ -24,13 +24,39 @@
 #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
+/** \file str.h.
+ * \brief Madmutt string API.
+ *
+ * \author Pierre Habouzit <madcoder@debian.org>
+ *
+ * This header 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 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.
+ */
+
+
+#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 */
 
-#define NONULL(x) (x?x:"")
-#define ISSPACE(c) isspace((unsigned char)c)
 
 extern unsigned char const __m_strdigits[128];
 extern signed char const __m_b64digits[128];
@@ -100,7 +126,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,6 +154,14 @@ static inline char *m_strreplace(char **p, const char *s) {
     return (*p = m_strdup(s));
 }
 
+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);
 ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l);
 
@@ -181,12 +215,4 @@ 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 */