+++ /dev/null
-.\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5n
-.ft B
-.nf
-..
-.de VE
-.ft R
-.in -5n
-.sp 1
-.fi
-..
-.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.
-.PP
-The function
-.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_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_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_qsplit
-divides a string into whitespace-separated words. The arguments are as
-follows:
-.TP
-.BI "char *" p
-The address of the string to split. The string is modified by having
-null terminators written after each word extracted.
-.TP
-.BI "char *" v []
-The address of an array of pointers to characters. This array will be
-filled in by
-.BR str_split :
-the first entry will point to the first word extracted from the string,
-and so on. If there aren't enough words in the string, the remaining
-array elements are filled with null pointers.
-.TP
-.BI "size_t " c
-The maximum number of words to extract; also, the number of elements in
-the array
-.IR v .
-.TP
-.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_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
-.I sz \- 1
-characters from the string
-.I p
-to
-.IR d .
-The result string is null terminated. Any nonprinting characters in
-.I p
-are replaced by an underscore
-.RB ` _ '
-when written to
-.IR d .
-.SH EXAMPLES
-Given the code
-.VS
-char p[] = " alpha beta gamma delta ";
-char *v[3];
-size_t n;
-char *q;
-
-n = str_split(p, v, 3, &q);
-.VE
-following the call to
-.BR str_split ,
-.B n
-will have the value 3,
-.B v[0]
-will point to
-.RB ` alpha ',
-.B v[1]
-will point to
-.RB ` beta ',
-.B v[2]
-will point to
-.RB ` gamma '
-and
-.B rest
-will point to
-.RB ` delta\ '
-(note the trailing space).
-.PP
-Similarly, given the string
-.B """\ alpha\ \ beta\ """
-instead,
-.B n
-will be assigned the value 2,
-.B v[0]
-and
-.B v[1]
-will have the same values as last time, and
-.B v[2]
-and
-.B rest
-will be null.
-.SH "SEE ALSO"
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff