Documented ucw/string.h.

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index 81ee2bcc73d05cb03dc93a221b0be4b484db5673..a61bb14cda3487e92a26411e0afc1adb881b5b13 100644 (file)
--- a/ucw/doc/Makefile
+++ b/ucw/doc/Makefile
@@ -2,7 +2,7 @@
 
 DIRS+=ucw/doc
 
-UCW_DOCS=basics log fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode prime binsearch heap binheap compress sort hashtable relnotes trans
+UCW_DOCS=basics log fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode prime binsearch heap binheap compress sort hashtable relnotes trans string
 UCW_INDEX=$(o)/ucw/doc/def_index.html
 UCW_DOCS_HTML=$(addprefix $(o)/ucw/doc/,$(addsuffix .html,$(UCW_DOCS)))
 

diff --git a/ucw/doc/index.txt b/ucw/doc/index.txt
index 3f625e8543be794c2769bff8ced61bc669e0f62c..df2839da5bc33551bf57c8d542d13e8f6883255b 100644 (file)
--- a/ucw/doc/index.txt
+++ b/ucw/doc/index.txt
@@ -36,6 +36,7 @@ Modules
 - <<binsearch:,Binary search>>
 - <<compress:,Compression>>
 - <<trans:,Transactions and resource tracking>>
+- <<string:,String operations>>
 
 Other features
 --------------
@@ -60,8 +61,6 @@ Yet undocumented modules
   * `kmp-search.h`
   * `regex.h`
   * `stkstring.h`
-  * `string.h`
-  * `str-match.h`
   * `strtonum.h`
   * `wildmatch.h`
 - File manipulation

diff --git a/ucw/doc/string.txt b/ucw/doc/string.txt
new file mode 100644 (file)
index 0000000..fe5b97d
--- /dev/null
+++ b/ucw/doc/string.txt
@@ -0,0 +1,11 @@
+String operations
+=================
+
+LibUCW contains a rich set of functions for manipulating strings.
+
+So far, only a small subset is documented.
+
+ucw/string.h
+------------
+
+!!ucw/string.h

diff --git a/ucw/str-esc.c b/ucw/str-esc.c
index 97bbe387e79a95c3c4b14ad6f07330368b7064c1..1796a7041a3c38e21a8c6f8df50edd584bc09955 100644 (file)
--- a/ucw/str-esc.c
+++ b/ucw/str-esc.c
@@ -15,8 +15,6 @@
 #include "ucw/chartype.h"
 #include <stdlib.h>
 
-/* Expands C99-like escape sequences.
- * It is safe to use the same buffer for both input and output. */
 char *
 str_unesc(char *d, const char *s)
 {

diff --git a/ucw/string.h b/ucw/string.h
index 8cb3cd423de61fc999e89ac5cabe39a76f758f49..2583a3574434ec7222c7caf0fc970f8bd7e1b04a 100644 (file)
--- a/ucw/string.h
+++ b/ucw/string.h
@@ -17,26 +17,74 @@
 uns strnlen(const char *str, uns n);
 #endif
 
+/**
+ * Format a set of flag bits. When the i-th bit of @flags is 1,
+ * set the i-th character of @dest to @fmt[i], otherwise to '-'.
+ **/
 char *str_format_flags(char *dest, const char *fmt, uns flags);
+
+/** Counts occurrences of @chr in @str. **/
 uns str_count_char(const char *str, uns chr);
 
 /* str-esc.c */
 
+/**
+ * Decode a string with backslash escape sequences as in C99 strings.
+ * It is safe to pass @dest equal to @src.
+ **/
 char *str_unesc(char *dest, const char *src);
 
 /* str-split.c */
 
+/**
+ * Split @str to at most @max fields separated by @sep. Occurrences of the
+ * separator are rewritten to string terminators, @rec[i] is set to point
+ * to the i-th field. The total number of fields is returned.
+ *
+ * When there are more than @max fields in @str, the first @max fields
+ * are processed and -1 is returned.
+ **/
 int str_sepsplit(char *str, uns sep, char **rec, uns max);
+
+/**
+ * Split @str to words separated by white-space characters. The spaces
+ * are replaced by string terminators, @rec[i] is set to point to the
+ * i-th field. The total number of fields is returned.
+ *
+ * When there are more than @max fields in @str, the first @max fields
+ * are processed and -1 is returned.
+ *
+ * Fields surrounded by double quotes are also recognized. They can contain
+ * spaces, but no mechanism for escaping embedded quotes is defined.
+ **/
 int str_wordsplit(char *str, char **rec, uns max);
 
 /* str-(i)match.c: Matching of shell patterns */
 
+/**
+ * Test whether the string @str matches the shell-like pattern @patt. Only
+ * "*" and "?" meta-characters are supported.
+ **/
 int str_match_pattern(const char *patt, const char *str);
+
+/** A case-insensitive version of @str_match_pattern(). **/
 int str_match_pattern_nocase(const char *patt, const char *str);
 
 /* str-hex.c */
 
+/**
+ * Create a hexdump of a memory block of @bytes bytes starting at @src.
+ * The @flags contain an optional separator of bytes (0 if bytes should
+ * not be separated), possibly OR-ed with `MEM_TO_HEX_UPCASE` when upper-case
+ * characters should be used.
+ **/
 void mem_to_hex(char *dest, const byte *src, uns bytes, uns flags);
+
+/**
+ * An inverse function to @mem_to_hex(). Takes a hexdump of at most @max_bytes
+ * bytes and stores the bytes to a buffer starting at @dest. Returns a pointer
+ * at the first character after the dump.
+ **/
 const char *hex_to_mem(byte *dest, const char *src, uns max_bytes, uns flags);
 
 // Bottom 8 bits of flags are an optional separator of bytes, the rest is:
@@ -53,13 +101,14 @@ int str_has_suffix(char *str, char *suffix);               /** Tests if @str ends with @suffi
  * component boundaries.
  *
  * For example, when @sep is '/' and @str is "/usr/local/bin", then:
+ *
  * - "/usr/local" is a prefix
  * - "/usr/local/" is a prefix, too
  * - "/usr/loc" is not,
  * - "/usr/local/bin" is a prefix,
  * - "/usr/local/bin/" is not,
  * - "/" is a prefix,
- * - "" is a prefix,
+ * - "" is a prefix.
  **/
 int str_hier_prefix(char *str, char *prefix, uns sep);
 int str_hier_suffix(char *str, char *suffix, uns sep); /** Like @str_hier_prefix(), but for suffixes. **/