From: Ralph Corderoy <ralph@inputplus.co.uk>
Date: Mon, 25 Sep 2017 10:36:36 +0000 (+0100)
Subject: utils.c: Improve comment describing add().  Suggest mh_xstrdup().
X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/6285556019a54b5c6e306d502591cf901ae08233?hp=14ac4332fa909bb10b37f9542b07f607ba4eda9f

utils.c: Improve comment describing add().  Suggest mh_xstrdup().
---

diff --git a/sbr/utils.c b/sbr/utils.c
index 8debe1aa..dd875325 100644
--- a/sbr/utils.c
+++ b/sbr/utils.c
@@ -117,13 +117,15 @@ pwd(void)
     return curwd;
 }
 
-/*
- * add   -- If "s1" is NULL, this routine just creates a
- *       -- copy of "s2" into newly malloc'ed memory.
- *       --
- *       -- If "s1" is not NULL, then copy the concatenation
- *       -- of "s1" and "s2" (note the order) into newly
- *       -- malloc'ed memory.  Then free "s1".
+/* add returns a newly malloc'd string, exiting on failure.  The order
+ * of the parameters is unusual.  A NULL parameter is treated as an
+ * empty string.  s1 is free'd.  Use mh_xstrdup(s) rather than add(s,
+ * NULL), with FENDNULL() if s might be NULL.
+ *
+ *     add(NULL, NULL) -> ""
+ *     add(NULL, "foo") -> "foo"
+ *     add("bar", NULL) -> "bar"
+ *     add("bar", "foo") -> "foobar"
  */
 char *
 add (const char *s2, char *s1)