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