From: Martin Mares <mj@ucw.cz>
Date: Mon, 18 Apr 2011 21:05:21 +0000 (+0200)
Subject: Documented ucw/string.h.
X-Git-Tag: v5.0~74^2~17
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=9f4d2aa894b1ccb7c82e1bd277f51ab1bce9f288;p=libucw.git

Documented ucw/string.h.
---

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index 81ee2bcc..a61bb14c 100644
--- 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 3f625e85..df2839da 100644
--- 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
index 00000000..fe5b97db
--- /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 97bbe387..1796a704 100644
--- 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 8cb3cd42..2583a357 100644
--- 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. **/