From 9f4d2aa894b1ccb7c82e1bd277f51ab1bce9f288 Mon Sep 17 00:00:00 2001 From: Martin Mares Date: Mon, 18 Apr 2011 23:05:21 +0200 Subject: [PATCH] Documented ucw/string.h. --- ucw/doc/Makefile | 2 +- ucw/doc/index.txt | 3 +-- ucw/doc/string.txt | 11 ++++++++++ ucw/str-esc.c | 2 -- ucw/string.h | 51 +++++++++++++++++++++++++++++++++++++++++++++- 5 files changed, 63 insertions(+), 6 deletions(-) create mode 100644 ucw/doc/string.txt 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 - <> - <> - <> +- <> 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 -/* 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. **/ -- 2.39.5