1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
<head>
<title>string(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>STRING(3)</b><td align=right><b>STRING(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref,
s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart,
s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line,
s_getline, s_allocinstack, s_freeinstack, s_rdinstack – extensible
strings<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include <u.h><br>
#include <libc.h><br>
#include <String.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>String* s_new(void)<br>
void s_free(String *s)<br>
String* s_newalloc(int n)<br>
String* s_array(char *p, int n)<br>
String* s_grow(String *s, int n)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void s_putc(String *s, int c)<br>
void s_terminate(String *s)<br>
String* s_reset(String *s)<br>
String* s_restart(String *s)<br>
String* s_append(String *s, char *p)<br>
String* s_nappend(String *s, char *p, int n)<br>
String* s_memappend(String *s, char *p, int n)<br>
String* s_copy(char *p)<br>
String* s_parse(String *s1, String *s2)<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void s_tolower(String *s)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>String* s_incref(String *s)<br>
String* s_unique(String *s)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Sinstack* s_allocinstack(char *file)<br>
void s_freeinstack(Sinstack *stack)<br>
char* s_rdinstack(Sinstack *stack, String *s)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>#include <bio.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int s_read(Biobuf *b, String *s, int n)<br>
char* s_read_line(Biobuf *b, String *s)<br>
char* s_getline(Biobuf *b, String *s)<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
These routines manipulate extensible strings. The basic type is
<tt><font size=+1>String</font></tt>, which points to an array of characters. The string maintains
pointers to the beginning and end of the allocated array. In addition
a finger pointer keeps track of where parsing will start (for
<i>s_parse</i>) or new characters will be added (for <i>s_putc</i>,
<i>s_append</i>, and <i>s_nappend</i>). The structure, and a few useful macros
are:<br>
<tt><font size=+1>typedef struct String {<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
Lock;<br>
char*base;/* base of String */<br>
char*end;/* end of allocated space+1 */<br>
char*ptr;/* ptr into String */<br>
...<br>
</table>
</table>
} String;<br>
#define s_to_c(s) ((s)−>base)<br>
#define s_len(s) ((s)−>ptr−(s)−>base)<br>
#define s_clone(s) s_copy((s)−>base)<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<i>S_to_c</i> is used when code needs a reference to the character array.
Using <tt><font size=+1>s−>base</font></tt> directly is frowned upon since it exposes too much
of the implementation.<br>
<p><font size=+1><b>Allocation and freeing </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A string must be allocated before it can be used. One normally
does this using <i>s_new</i>, giving the string an initial allocation
of 128 bytes. If you know that the string will need to grow much
longer, you can use <i>s_newalloc</i> instead, specifying the number
of bytes in the initial allocation.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_free</i> causes both the string and its character array to be freed.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_grow</i> grows a string’s allocation by a fixed amount. It is useful
if you are reading directly into a string’s character array but
should be avoided if possible.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_array</i> is used to create a constant array, that is, one whose
contents won’t change. It points directly to the character array
given as an argument. Tread lightly when using this call.<br>
<p><font size=+1><b>Filling the string </b></font><br>
After its initial allocation, the string points to the beginning
of an allocated array of characters starting with NUL.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_putc</i> writes a character into the string at the pointer and advances
the pointer to point after it.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_terminate</i> writes a NUL at the pointer but doesn’t advance it.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_restart</i> resets the pointer to the begining of the string but
doesn’t change the contents.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_reset</i> is equivalent to <i>s_restart</i> followed by <i>s_terminate</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_append</i> and <i>s_nappend</i> copy characters into the string at the
pointer and advance the pointer. They also write a NUL at the
pointer without advancing the pointer beyond it. Both routines
stop copying on encountering a NUL. <i>S_memappend</i> is like <i>s_nappend</i>
but doesn’t stop at a NUL.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
If you know the initial character array to be copied into a string,
you can allocate a string and copy in the bytes using <i>s_copy</i>.
This is the equivalent of a <i>s_new</i> followed by an <i>s_append</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_parse</i> copies the next white space terminated token from <i>s1</i> to
the end of <i>s2</i>. White space is defined as space, tab, and newline.
Both single and double quoted strings are treated as a single
token. The bounding quotes are not copied. There is no escape
mechanism.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_tolower</i> converts all ASCII characters in the string to lower
case.<br>
<p><font size=+1><b>Multithreading </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_incref</i> is used by multithreaded programs to avoid having the
string memory released until the last user of the string performs
an <i>s_free</i>. <i>S_unique</i> returns a unique copy of the string: if the
reference count it 1 it returns the string, otherwise it returns
an <i>s_clone</i> of the string.<br>
<p><font size=+1><b>Bio interaction </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_read</i> reads the requested number of characters through a <i>Biobuf</i>
into a string. The string is grown as necessary. An eof or error
terminates the read. The number of bytes read is returned. The
string is null terminated.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_read_line</i> reads up to and including the next newline and returns
a pointer to the beginning of the bytes read. An eof or error
terminates the read. The string is null terminated.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_getline</i> reads up to the next newline, appends the input to <i>s</i>,
and returns a pointer to the beginning of the bytes read. Leading
spaces and tabs and the trailing newline are all discarded. <i>S_getline</i>
discards blank lines and lines beginning with <tt><font size=+1>#</font></tt>. <i>S_getline</i> ignores
newlines escaped by immediately-preceding
backslashes.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>S_allocinstack</i> allocates an input stack with the single file <i>file</i>
open for reading. <i>S_freeinstack</i> frees an input stack. <i>S_rdinstack</i>
reads a line from an input stack. It follows the same rules as
<i>s_getline</i> except that when it encounters a line of the form <tt><font size=+1>#include</font></tt>
<i>newfile</i>, <i>s_getline</i> pushes <i>newfile</i> onto the input stack,
postponing further reading of the current file until <i>newfile</i> has
been read. The input stack has a maximum depth of 32 nested include
files.<br>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/libString<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/bio.html"><i>bio</i>(3)</a><br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>
|