14 .TH str 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
16 str \- small string utilities
26 .B "#include <mLib/str.h>"
28 .BI "char *str_qword(char **" pp ", unsigned " f );
29 .BI "size_t str_qsplit(char *" p ", char *" v "[], size_t " c ,
30 .BI " char **" rest ", unsigned " f );
31 .BI "char *str_getword(char **" pp );
32 .BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest );
33 .BI "int str_matchx(const char *" p ", const char *" s ", unsigned " f );
34 .BI "int str_match(const char *" p ", const char *" s );
35 .BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz );
40 contains a few small utility functions for manipulating null-terminated
45 extracts the next whitespace-delimited word from a string. The
48 is the address of a pointer into the string: this pointer is updated by
50 so that it can extract the following word on the next call and so on.
51 The return value is the address of the next word, appropriately null
52 terminated. A null pointer is returned if the entire remainder of the
53 string is whitespace. Note that
55 modifies the string as it goes, to null-terminate the individual words.
58 is passed, the single- and double-quote characters may be used to quote
59 whitespace within words, and the backslash can escape quote characters
64 divides a string into whitespace-separated words. The arguments are as
68 The address of the string to split. The string is modified by having
69 null terminators written after each word extracted.
72 The address of an array of pointers to characters. This array will be
75 the first entry will point to the first word extracted from the string,
76 and so on. If there aren't enough words in the string, the remaining
77 array elements are filled with null pointers.
80 The maximum number of words to extract; also, the number of elements in
85 The address of a pointer in which to store the address of the remainder
86 of the string. Leading whitespace is removed from the remainder before
87 storing. If the remainder string is empty, a null pointer is stored
90 is null, the remainder pointer is discarded.
98 is the number of words extracted from the input string.
108 respectively; they are equivalent to calls to the latter functions with
113 function does simple wildcard matching. The first argument is a
114 pattern, which may contain metacharacters:
116 matches zero or more arbitrary characters;
118 matches exactly one arbitrary characters; and
120 matches one of the characters listed. The backslash
122 escapes the following character. Within square brackets, the
125 may be used to designate ranges of characters. If the initial character
130 then the sense of the match is reversed. To literally match a
132 character, list it first; to literally match a
134 character, list it immediately after a range, or at the beginning or end
135 of the set. The return value is nonzero if the pattern
137 matches the given string
139 or zero if the pattern doesn't match. If the flag
143 returns true if it reaches the end of the target string before finding a
144 mismatch \(en i.e., if the target string is a prefix of a string which
145 might match the pattern. The function
147 is a convenient wrapper for
149 with a zero flags word, which is the normal case.
155 characters from the string
159 The result string is null terminated. Any nonprinting characters in
161 are replaced by an underscore
168 char p[] = " alpha beta gamma delta ";
173 n = str_split(p, v, 3, &q);
175 following the call to
178 will have the value 3,
192 (note the trailing space).
194 Similarly, given the string
195 .B """\ alpha\ \ beta\ """
198 will be assigned the value 2,
202 will have the same values as last time, and
210 Mark Wooding, <mdw@distorted.org.uk>