b6b9d458 |
1 | .\" -*-nroff-*- |
2 | .de VS |
3 | .sp 1 |
4 | .in +5n |
5 | .ft B |
6 | .nf |
7 | .. |
8 | .de VE |
9 | .ft R |
10 | .in -5n |
11 | .sp 1 |
12 | .fi |
13 | .. |
14 | .TH str 3mLib "20 June 1999" mLib |
15 | .SH NAME |
16 | str \- small string utilities |
17 | .SH SYNOPSIS |
18 | .nf |
19 | .B "#include <mLib/str.h>" |
20 | |
21 | .BI "char *str_getword(char **" pp ); |
22 | .BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest ); |
23 | .BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz ); |
24 | .fi |
25 | .SH DESCRIPTION |
26 | The header file |
27 | .B <mLib/str.h> |
28 | contains a few small utility functions for manipulating null-terminated |
29 | strings. |
30 | .PP |
31 | The function |
32 | .B str_getword |
33 | extracts the next whitespace-delimited word from a string. The |
34 | function's argument, |
35 | .IR pp , |
36 | is the address of a pointer into the string: this pointer is updated by |
37 | .B str_getword |
38 | so that it can extract the following word on the next call and so on. |
39 | The return value is the address of the next word, appropriately null |
40 | terminated. A null pointer is returned if the entire remainder of the |
41 | string is whitespace. Note that |
42 | .B str_getword |
43 | modifies the string as it goes, to null-terminate the individual words. |
44 | .PP |
45 | The function |
46 | .B str_split |
47 | divides a string into whitespace-separated words. The arguments are as |
48 | follows: |
49 | .TP |
50 | .I p |
51 | The address of the string to split. The string is modified by having |
52 | null terminators written after each word extracted. |
53 | .TP |
54 | .I v |
55 | The address of an array of pointers to characters. This array will be |
56 | filled in by |
57 | .BR str_split : |
58 | the first entry will point to the first word extracted from the string, |
59 | and so on. If there aren't enough words in the string, the remaining |
60 | array elements are filled with null pointers. |
61 | .TP |
62 | .I c |
63 | The maxmimum number of words to extract; also, the number of elements in |
64 | the array |
65 | .IR v . |
66 | .TP |
67 | .I rest |
68 | The address of a pointer in which to store the address of the remainder |
69 | of the string. Leading whitespace is removed from the remainder before |
70 | storing. If the remainder string is empty, a null pointer is stored |
71 | instead. If |
72 | .I rest |
73 | is null, the remainder pointer is discarded. |
74 | .PP |
75 | The return value of |
76 | .B str_split |
77 | is the number of words extracted from the input string. |
78 | .PP |
79 | The function |
80 | .B str_sanitize |
81 | copies at most |
82 | .I sz \- 1 |
83 | characters from the string |
84 | .I p |
85 | to |
86 | .IR d . |
87 | The result string is null terminated. Any nonprinting characters in |
88 | .I p |
89 | are replaced by an underscore |
90 | .RB ` _ ' |
91 | when written to |
92 | .IR d . |
93 | .SH EXAMPLES |
94 | Given the code |
95 | .VS |
96 | char p[] = " alpha beta gamma delta "; |
97 | char *v[3]; |
98 | size_t n; |
99 | char *q; |
100 | |
101 | n = str_split(p, v, 3, &q); |
102 | .VE |
103 | following the call to |
104 | .BR str_split , |
105 | .B n |
106 | will have the value 3, |
107 | .B v[0] |
108 | will point to |
109 | .RB ` alpha ', |
110 | .B v[1] |
111 | will point to |
112 | .RB ` beta ', |
113 | .B v[2] |
114 | will point to |
115 | .RB ` gamma ' |
116 | and |
117 | .B rest |
118 | will point to |
119 | .RB ` delta\ ' |
120 | (note the trailing space). |
121 | .PP |
122 | Similarly, given the string |
123 | .B """\ alpha\ \ beta\ """ |
124 | instead, |
125 | .B n |
126 | will be assigned the value 2, |
127 | .B v[0] |
128 | and |
129 | .B v[1] |
130 | will have the same values as last time, and |
131 | .B v[2] |
132 | and |
133 | .B rest |
134 | will be null. |
135 | .SH AUTHOR |
136 | Mark Wooding, <mdw@nsict.org> |