14 .TH str 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
16 str \- small string utilities
25 .B "#include <mLib/str.h>"
27 .BI "char *str_qword(char **" pp ", unsigned " f );
28 .BI "size_t str_qsplit(char *" p ", char *" v "[], size_t " c ,
29 .BI " char **" rest ", unsigned " f );
30 .BI "char *str_getword(char **" pp );
31 .BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest );
32 .BI "int str_match(const char *" p ", const char *" s );
33 .BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz );
38 contains a few small utility functions for manipulating null-terminated
43 extracts the next whitespace-delimited word from a string. The
46 is the address of a pointer into the string: this pointer is updated by
48 so that it can extract the following word on the next call and so on.
49 The return value is the address of the next word, appropriately null
50 terminated. A null pointer is returned if the entire remainder of the
51 string is whitespace. Note that
53 modifies the string as it goes, to null-terminate the individual words.
56 is passed, the single- and double-quote characters may be used to quote
57 whitespace within words, and the backslash can escape quote characters
62 divides a string into whitespace-separated words. The arguments are as
66 The address of the string to split. The string is modified by having
67 null terminators written after each word extracted.
70 The address of an array of pointers to characters. This array will be
73 the first entry will point to the first word extracted from the string,
74 and so on. If there aren't enough words in the string, the remaining
75 array elements are filled with null pointers.
78 The maximum number of words to extract; also, the number of elements in
83 The address of a pointer in which to store the address of the remainder
84 of the string. Leading whitespace is removed from the remainder before
85 storing. If the remainder string is empty, a null pointer is stored
88 is null, the remainder pointer is discarded.
96 is the number of words extracted from the input string.
106 respectively; they are equivalent to calls to the latter functions with
111 function does simple wildcard matching. The first argument is a
112 pattern, which may contain metacharacters:
114 matches zero or more arbitrary characters;
116 matches exactly one arbitrary characters; and
118 matches one of the characters listed. The backslash
120 escapes the following character. Within square brackets, the
123 may be used to designate ranges of characters. If the initial character
128 then the sense of the match is reversed. To literally match a
130 character, list it first; to literally match a
132 character, list it immediately after a range, or at the beginning or end
133 of the set. The return value is nonzero if the pattern
135 matches the given string
137 or zero if the pattern doesn't match.
143 characters from the string
147 The result string is null terminated. Any nonprinting characters in
149 are replaced by an underscore
156 char p[] = " alpha beta gamma delta ";
161 n = str_split(p, v, 3, &q);
163 following the call to
166 will have the value 3,
180 (note the trailing space).
182 Similarly, given the string
183 .B """\ alpha\ \ beta\ """
186 will be assigned the value 2,
190 will have the same values as last time, and
198 Mark Wooding, <mdw@nsict.org>