.sp 1
.fi
..
-.TH str 3mLib "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_matchx
+.\" @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_matchx(const char *" p ", const char *" s ", unsigned " f );
+.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
The header file
.B <mLib/str.h>
contains a few small utility functions for manipulating null-terminated
-strings.
+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
-.I p
+.BI "char *" p
The address of the string to split. The string is modified by having
null terminators written after each word extracted.
.TP
-.I v
+.BI "char *" v []
The address of an array of pointers to characters. This array will be
filled in by
.BR str_split :
and so on. If there aren't enough words in the string, the remaining
array elements are filled with null pointers.
.TP
-.I c
-The maxmimum number of words to extract; also, the number of elements in
+.BI "size_t " c
+The maximum number of words to extract; also, the number of elements in
the array
.IR v .
.TP
-.I rest
+.BI "char **" rest
The address of a pointer in which to store the address of the remainder
of the string. Leading whitespace is removed from the remainder before
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_matchx
+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. If the flag
+.B STRF_PREFIX
+is passed,
+.B str_matchx
+returns true if it reaches the end of the target string before finding a
+mismatch \(en i.e., if the target string is a prefix of a string which
+might match the pattern. The function
+.B str_match
+is a convenient wrapper for
+.B str_matchx
+with a zero flags word, which is the normal case.
+.PP
The function
.B str_sanitize
copies at most
and
.B rest
will be null.
+.SH "SEE ALSO"
+.BR mLib (3).
.SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff