no more SHORT_STRING's. begin some doc.

[apps/madmutt.git] / lib-lib / str.h

diff --git a/lib-lib/str.h b/lib-lib/str.h
index 296cd55..51eeba4 100644 (file)
--- a/lib-lib/str.h
+++ b/lib-lib/str.h
@@ -16,22 +16,47 @@
  *
  *  Copyright © 2006 Pierre Habouzit
  */
+/*
+ * Copyright notice from original mutt:
+ * Copyright (C) 2001 Thomas Roessler <roessler@does-not-exist.org>
+ */
 
 #ifndef MUTT_LIB_LIB_STR_H
 #define MUTT_LIB_LIB_STR_H
 
-#include <string.h>
-#include <ctype.h>
+/** \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.
+ */
 
-#include "mem.h"
 
-#define HUGE_STRING     5120
-#define LONG_STRING     1024
-#define STRING          256
-#define SHORT_STRING    128
+#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];
@@ -57,6 +82,20 @@ static inline void m_strtolower(char *p) {
         *p = tolower((unsigned char)*p);
 }
 
+static inline int ascii_toupper(int c) {
+    if ('a' <= c && c <= 'z')
+        return c & ~32;
+
+    return c;
+}
+
+static inline int ascii_tolower(int c) {
+    if ('A' <= c && c <= 'Z')
+        return c | 32;
+
+    return c;
+}
+
 /****************************************************************************/
 /* length related                                                           */
 /****************************************************************************/
@@ -87,13 +126,16 @@ 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) {
     return strncasecmp(NONULL(a), NONULL(b), n);
 }
 
+int ascii_strcasecmp(const char *a, const char *b);
+int ascii_strncasecmp(const char *a, const char *b, ssize_t n);
+
 /****************************************************************************/
 /* making copies                                                            */
 /****************************************************************************/
@@ -112,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);
 
@@ -130,6 +180,18 @@ m_strncat(char *dst, ssize_t n, const char *src, ssize_t l) {
 /* parsing related                                                          */
 /****************************************************************************/
 
+static inline const char *m_strchrnul(const char *s, int c) {
+    while (*s && *s != c)
+        s++;
+    return s;
+}
+
+static inline const char *m_strnextsp(const char *s) {
+    while (*s && !isspace((unsigned char)*s))
+        s++;
+    return s;
+}
+
 static inline const char *skipspaces(const char *s) {
     while (*s && isspace((unsigned char)*s))
         s++;