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