New hex encoding stuff. Rename test programs.

[mLib] / man / str.3

diff --git a/man/str.3 b/man/str.3
index 1484fb576fd0f60b852cb578c534ef421a466db8..355bd8c2be5649a61253de6a7400f84eea094874 100644 (file)
--- a/man/str.3
+++ b/man/str.3
@@ -11,18 +11,25 @@
 .sp 1
 .fi
 ..
-.TH str 3 "20 June 1999" mLib
+.TH str 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
 .SH NAME
 str \- small string utilities
+.\" @str_qword
+.\" @str_qsplit
 .\" @str_getword
 .\" @str_split
+.\" @str_match
 .\" @str_sanitize
 .SH SYNOPSIS
 .nf
 .B "#include <mLib/str.h>"
 
+.BI "char *str_qword(char **" pp ", unsigned " f );
+.BI "size_t str_qsplit(char *" p ", char *" v "[], size_t " c ,
+.BI "                  char **" rest ", unsigned " f );
 .BI "char *str_getword(char **" pp );
 .BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest );
+.BI "int str_match(const char *" p ", const char *" s );
 .BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz );
 .fi
 .SH DESCRIPTION
@@ -32,21 +39,26 @@ contains a few small utility functions for manipulating null-terminated
 strings.  
 .PP
 The function
-.B str_getword
+.B str_qword
 extracts the next whitespace-delimited word from a string.  The
 function's argument,
 .IR pp ,
 is the address of a pointer into the string: this pointer is updated by
-.B str_getword
+.B str_qword
 so that it can extract the following word on the next call and so on.
 The return value is the address of the next word, appropriately null
 terminated.  A null pointer is returned if the entire remainder of the
 string is whitespace.  Note that
-.B str_getword
+.B str_qword
 modifies the string as it goes, to null-terminate the individual words.
+If the flag
+.B STRF_QUOTE
+is passed, the single- and double-quote characters may be used to quote
+whitespace within words, and the backslash can escape quote characters
+and whitespace.
 .PP
 The function
-.B str_split
+.B str_qsplit
 divides a string into whitespace-separated words.  The arguments are as
 follows:
 .TP
@@ -74,11 +86,56 @@ storing.  If the remainder string is empty, a null pointer is stored
 instead.  If
 .I rest
 is null, the remainder pointer is discarded.
+.TP
+.BI "unsigned " f
+Flags, as for
+.BR str_qsplit .
 .PP
 The return value of
-.B str_split
+.B str_qsplit
 is the number of words extracted from the input string.
 .PP
+The functions
+.B str_getword
+and
+.B str_split
+are veneers over
+.B str_qword
+and
+.B str_qsplit
+respectively; they are equivalent to calls to the latter functions with
+flags words of zero.
+.PP
+The
+.B str_match
+function does simple wildcard matching.  The first argument is a
+pattern, which may contain metacharacters:
+.RB ` * '
+matches zero or more arbitrary characters;
+.RB ` ? '
+matches exactly one arbitrary characters; and
+.RB ` [ ... ] '
+matches one of the characters listed.  The backslash
+.RB ` \e '
+escapes the following character.  Within square brackets, the
+hyphen
+.RB ` \- '
+may be used to designate ranges of characters.  If the initial character
+is
+.RB ` ! '
+or
+.RB ` ^ '
+then the sense of the match is reversed.  To literally match a
+.RB ` ] '
+character, list it first; to literally match a
+.RB ` \- '
+character, list it immediately after a range, or at the beginning or end
+of the set.  The return value is nonzero if the pattern
+.I p
+matches the given string
+.IR s ,
+or zero if the pattern doesn't match.
+.PP
 The function
 .B str_sanitize
 copies at most