Improve string util API

Use prefixed names and improve documentation.

app/src/util/str_util.c

@@ -13,7 +13,7 @@
 #endif
 
 size_t
-xstrncpy(char *dest, const char *src, size_t n) {
+sc_strncpy(char *dest, const char *src, size_t n) {
     size_t i;
     for (i = 0; i < n - 1 && src[i] != '\0'; ++i)
         dest[i] = src[i];
@@ -23,7 +23,7 @@ xstrncpy(char *dest, const char *src, size_t n) {
 }
 
 size_t
-xstrjoin(char *dst, const char *const tokens[], char sep, size_t n) {
+sc_str_join(char *dst, const char *const tokens[], char sep, size_t n) {
     const char *const *remaining = tokens;
     const char *token = *remaining++;
     size_t i = 0;
@@ -33,7 +33,7 @@ xstrjoin(char *dst, const char *const tokens[], char sep, size_t n) {
             if (i == n)
                 goto truncated;
         }
-        size_t w = xstrncpy(dst + i, token, n - i);
+        size_t w = sc_strncpy(dst + i, token, n - i);
         if (w >= n - i)
             goto truncated;
         i += w;
@@ -47,7 +47,7 @@ truncated:
 }
 
 char *
-strquote(const char *src) {
+sc_str_quote(const char *src) {
     size_t len = strlen(src);
     char *quoted = malloc(len + 3);
     if (!quoted) {
@@ -61,7 +61,7 @@ strquote(const char *src) {
 }
 
 bool
-parse_integer(const char *s, long *out) {
+sc_str_parse_integer(const char *s, long *out) {
     char *endptr;
     if (*s == '\0') {
         return false;
@@ -80,7 +80,8 @@ parse_integer(const char *s, long *out) {
 }
 
 size_t
-parse_integers(const char *s, const char sep, size_t max_items, long *out) {
+sc_str_parse_integers(const char *s, const char sep, size_t max_items,
+                      long *out) {
     size_t count = 0;
     char *endptr;
     do {
@@ -109,7 +110,7 @@ parse_integers(const char *s, const char sep, size_t max_items, long *out) {
 }
 
 bool
-parse_integer_with_suffix(const char *s, long *out) {
+sc_str_parse_integer_with_suffix(const char *s, long *out) {
     char *endptr;
     if (*s == '\0') {
         return false;
@@ -143,7 +144,7 @@ parse_integer_with_suffix(const char *s, long *out) {
 }
 
 bool
-strlist_contains(const char *list, char sep, const char *s) {
+sc_str_list_contains(const char *list, char sep, const char *s) {
     char *p;
     do {
         p = strchr(list, sep);
@@ -161,7 +162,7 @@ strlist_contains(const char *list, char sep, const char *s) {
 }
 
 size_t
-utf8_truncation_index(const char *utf8, size_t max_len) {
+sc_str_utf8_truncation_index(const char *utf8, size_t max_len) {
     size_t len = strlen(utf8);
     if (len <= max_len) {
         return len;
@@ -179,7 +180,7 @@ utf8_truncation_index(const char *utf8, size_t max_len) {
 #ifdef _WIN32
 
 wchar_t *
-utf8_to_wide_char(const char *utf8) {
+sc_str_to_wchars(const char *utf8) {
     int len = MultiByteToWideChar(CP_UTF8, 0, utf8, -1, NULL, 0);
     if (!len) {
         return NULL;
@@ -195,7 +196,7 @@ utf8_to_wide_char(const char *utf8) {
 }
 
 char *
-utf8_from_wide_char(const wchar_t *ws) {
+sc_str_from_wchars(const wchar_t *ws) {
     int len = WideCharToMultiByte(CP_UTF8, 0, ws, -1, NULL, 0, NULL, NULL);
     if (!len) {
         return NULL;
@@ -212,7 +213,8 @@ utf8_from_wide_char(const wchar_t *ws) {
 
 #endif
 
-char *sc_str_wrap_lines(const char *input, unsigned columns, unsigned indent) {
+char *
+sc_str_wrap_lines(const char *input, unsigned columns, unsigned indent) {
     assert(indent < columns);
 
     struct sc_strbuf buf;

app/src/util/str_util.h

@@ -1,65 +1,97 @@
-#ifndef STRUTIL_H
-#define STRUTIL_H
+#ifndef SC_STRUTIL_H
+#define SC_STRUTIL_H
 
 #include "common.h"
 
 #include <stdbool.h>
 #include <stddef.h>
 
-// like strncpy, except:
-//  - it copies at most n-1 chars
-//  - the dest string is nul-terminated
-//  - it does not write useless bytes if strlen(src) < n
-//  - it returns the number of chars actually written (max n-1) if src has
-//    been copied completely, or n if src has been truncated
+/**
+ * Like strncpy(), except:
+ *  - it copies at most n-1 chars
+ *  - the dest string is nul-terminated
+ *  - it does not write useless bytes if strlen(src) < n
+ *  - it returns the number of chars actually written (max n-1) if src has
+ *    been copied completely, or n if src has been truncated
+ */
 size_t
-xstrncpy(char *dest, const char *src, size_t n);
+sc_strncpy(char *dest, const char *src, size_t n);
 
-// join tokens by sep into dst
-// returns the number of chars actually written (max n-1) if no truncation
-// occurred, or n if truncated
+/**
+ * Join tokens by separator `sep` into `dst`
+ *
+ * Return the number of chars actually written (max n-1) if no truncation
+ * occurred, or n if truncated.
+ */
 size_t
-xstrjoin(char *dst, const char *const tokens[], char sep, size_t n);
+sc_str_join(char *dst, const char *const tokens[], char sep, size_t n);
 
-// quote a string
-// returns the new allocated string, to be freed by the caller
+/**
+ * Quote a string
+ *
+ * Return a new allocated string, surrounded with quotes (`"`).
+ */
 char *
-strquote(const char *src);
+sc_str_quote(const char *src);
 
-// parse s as an integer into value
-// returns true if the conversion succeeded, false otherwise
+/**
+ * Parse `s` as an integer into `out`
+ *
+ * Return true if the conversion succeeded, false otherwise.
+ */
 bool
-parse_integer(const char *s, long *out);
+sc_str_parse_integer(const char *s, long *out);
 
-// parse s as integers separated by sep (for example '1234:2000')
-// returns the number of integers on success, 0 on failure
+/**
+ * Parse `s` as integers separated by `sep` (for example `1234:2000`) into `out`
+ *
+ * Returns the number of integers on success, 0 on failure.
+ */
 size_t
-parse_integers(const char *s, const char sep, size_t max_items, long *out);
+sc_str_parse_integers(const char *s, const char sep, size_t max_items,
+                      long *out);
 
-// parse s as an integer into value
-// like parse_integer(), but accept 'k'/'K' (x1000) and 'm'/'M' (x1000000) as
-// suffix
-// returns true if the conversion succeeded, false otherwise
+/**
+ * Parse `s` as an integer into `out`
+ *
+ * Like `sc_str_parse_integer()`, but accept 'k'/'K' (x1000) and 'm'/'M'
+ * (x1000000) as suffixes.
+ *
+ * Return true if the conversion succeeded, false otherwise.
+ */
 bool
-parse_integer_with_suffix(const char *s, long *out);
+sc_str_parse_integer_with_suffix(const char *s, long *out);
 
-// search s in the list separated by sep
-// for example, strlist_contains("a,bc,def", ',', "bc") returns true
+/**
+ * Search `s` in the list separated by `sep`
+ *
+ * For example, sc_str_list_contains("a,bc,def", ',', "bc") returns true.
+ */
 bool
-strlist_contains(const char *list, char sep, const char *s);
+sc_str_list_contains(const char *list, char sep, const char *s);
 
-// return the index to truncate a UTF-8 string at a valid position
+/**
+ * Return the index to truncate a UTF-8 string at a valid position
+ */
 size_t
-utf8_truncation_index(const char *utf8, size_t max_len);
+sc_str_utf8_truncation_index(const char *utf8, size_t max_len);
 
 #ifdef _WIN32
-// convert a UTF-8 string to a wchar_t string
-// returns the new allocated string, to be freed by the caller
+/**
+ * Convert a UTF-8 string to a wchar_t string
+ *
+ * Return the new allocated string, to be freed by the caller.
+ */
 wchar_t *
-utf8_to_wide_char(const char *utf8);
+sc_str_to_wchars(const char *utf8);
 
+/**
+ * Convert a wchar_t string to a UTF-8 string
+ *
+ * Return the new allocated string, to be freed by the caller.
+ */
 char *
-utf8_from_wide_char(const wchar_t *s);
+sc_str_from_wchars(const wchar_t *s);
 #endif
 
 /**
@@ -68,6 +100,7 @@ utf8_from_wide_char(const wchar_t *s);
  * Break input lines at word boundaries (spaces) so that they fit in `columns`
  * columns, left-indented by `indent` spaces.
  */
-char *sc_str_wrap_lines(const char *input, unsigned columns, unsigned indent);
+char *
+sc_str_wrap_lines(const char *input, unsigned columns, unsigned indent);
 
 #endif