X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;ds=sidebyside;f=ucw%2Fstring.h;h=9e9df4faa1ee054cbfd3aa746aeaeba8e859564e;hb=5de81f1debc4341fb3af4e756b0a18e196d5ba13;hp=8cb3cd423de61fc999e89ac5cabe39a76f758f49;hpb=521609b4721376161eabe89c9431aa221e87e263;p=libucw.git

diff --git a/ucw/string.h b/ucw/string.h
index 8cb3cd42..9e9df4fa 100644
--- a/ucw/string.h
+++ b/ucw/string.h
@@ -2,7 +2,7 @@
  *	UCW Library -- String Routines
  *
  *	(c) 2006 Pavel Charvat <pchar@ucw.cz>
- *	(c) 2007--2011 Martin Mares <mj@ucw.cz>
+ *	(c) 2007--2012 Martin Mares <mj@ucw.cz>
  *
  *	This software may be freely distributed and used according to the terms
  *	of the GNU Lesser General Public License.
@@ -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:
@@ -44,8 +92,8 @@ const char *hex_to_mem(byte *dest, const char *src, uns max_bytes, uns flags);
 
 /* str-fix.c */
 
-int str_has_prefix(char *str, char *prefix);		/** Tests if @str starts with @prefix. **/
-int str_has_suffix(char *str, char *suffix);		/** Tests if @str ends with @suffix. **/
+int str_has_prefix(const char *str, const char *prefix); /** Tests if @str starts with @prefix. **/
+int str_has_suffix(const char *str, const char *suffix); /** Tests if @str ends with @suffix. **/
 
 /**
  * Let @str and @prefix be hierarchical names with components separated by
@@ -53,15 +101,16 @@ 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. **/
+int str_hier_prefix(const char *str, const char *prefix, uns sep);
+int str_hier_suffix(const char *str, const char *suffix, uns sep); /** Like @str_hier_prefix(), but for suffixes. **/
 
 #endif