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