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