1 cfa37a7b 2004-04-10 devnull .TH STRING 3
3 cfa37a7b 2004-04-10 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 \- 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>
12 cfa37a7b 2004-04-10 devnull String* s_new(void)
15 cfa37a7b 2004-04-10 devnull void s_free(String *s)
18 cfa37a7b 2004-04-10 devnull String* s_newalloc(int n)
21 cfa37a7b 2004-04-10 devnull String* s_array(char *p, int n)
24 cfa37a7b 2004-04-10 devnull String* s_grow(String *s, int n)
27 cfa37a7b 2004-04-10 devnull void s_putc(String *s, int c)
30 cfa37a7b 2004-04-10 devnull void s_terminate(String *s)
33 cfa37a7b 2004-04-10 devnull String* s_reset(String *s)
36 cfa37a7b 2004-04-10 devnull String* s_restart(String *s)
39 cfa37a7b 2004-04-10 devnull String* s_append(String *s, char *p)
42 cfa37a7b 2004-04-10 devnull String* s_nappend(String *s, char *p, int n)
45 cfa37a7b 2004-04-10 devnull String* s_memappend(String *s, char *p, int n)
48 cfa37a7b 2004-04-10 devnull String* s_copy(char *p)
51 cfa37a7b 2004-04-10 devnull String* s_parse(String *s1, String *s2)
55 cfa37a7b 2004-04-10 devnull void s_tolower(String *s)
58 cfa37a7b 2004-04-10 devnull String* s_incref(String *s)
61 cfa37a7b 2004-04-10 devnull String* s_unique(String *s)
64 cfa37a7b 2004-04-10 devnull #include <bio.h>
67 cfa37a7b 2004-04-10 devnull int s_read(Biobuf *b, String *s, int n)
70 cfa37a7b 2004-04-10 devnull char* s_read_line(Biobuf *b, String *s)
73 cfa37a7b 2004-04-10 devnull char* s_getline(Biobuf *b, String *s)
74 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
76 cfa37a7b 2004-04-10 devnull These routines manipulate extensible strings.
77 cfa37a7b 2004-04-10 devnull The basic type is
78 cfa37a7b 2004-04-10 devnull .BR String ,
79 cfa37a7b 2004-04-10 devnull which points to an array of characters. The string
80 cfa37a7b 2004-04-10 devnull maintains pointers to the beginning and end of the allocated
81 cfa37a7b 2004-04-10 devnull array. In addition a finger pointer keeps track of where
82 cfa37a7b 2004-04-10 devnull parsing will start (for
83 cfa37a7b 2004-04-10 devnull .IR s_parse )
84 cfa37a7b 2004-04-10 devnull or new characters will be added (for
85 cfa37a7b 2004-04-10 devnull .IR s_putc ,
86 cfa37a7b 2004-04-10 devnull .IR s_append ,
88 cfa37a7b 2004-04-10 devnull .IR s_nappend ).
89 cfa37a7b 2004-04-10 devnull The structure, and a few useful macros are:
92 cfa37a7b 2004-04-10 devnull typedef struct String {
94 cfa37a7b 2004-04-10 devnull char *base; /* base of String */
95 cfa37a7b 2004-04-10 devnull char *end; /* end of allocated space+1 */
96 cfa37a7b 2004-04-10 devnull char *ptr; /* ptr into String */
98 cfa37a7b 2004-04-10 devnull } String;
100 cfa37a7b 2004-04-10 devnull #define s_to_c(s) ((s)->base)
101 cfa37a7b 2004-04-10 devnull #define s_len(s) ((s)->ptr-(s)->base)
102 cfa37a7b 2004-04-10 devnull #define s_clone(s) s_copy((s)->base)
105 cfa37a7b 2004-04-10 devnull .I S_to_c
106 cfa37a7b 2004-04-10 devnull is used when code needs a reference to the character array.
108 cfa37a7b 2004-04-10 devnull .B s->base
109 cfa37a7b 2004-04-10 devnull directly is frowned upon since it exposes too much of the implementation.
110 cfa37a7b 2004-04-10 devnull .SS "allocation and freeing
112 cfa37a7b 2004-04-10 devnull A string must be allocated before it can be used.
113 cfa37a7b 2004-04-10 devnull One normally does this using
114 cfa37a7b 2004-04-10 devnull .IR s_new ,
115 cfa37a7b 2004-04-10 devnull giving the string an initial allocation of
116 cfa37a7b 2004-04-10 devnull 128 bytes.
117 cfa37a7b 2004-04-10 devnull If you know that the string will need to grow much
118 cfa37a7b 2004-04-10 devnull longer, you can use
119 cfa37a7b 2004-04-10 devnull .I s_newalloc
120 cfa37a7b 2004-04-10 devnull instead, specifying the number of bytes in the
121 cfa37a7b 2004-04-10 devnull initial allocation.
123 cfa37a7b 2004-04-10 devnull .I S_free
124 cfa37a7b 2004-04-10 devnull causes both the string and its character array to be freed.
126 cfa37a7b 2004-04-10 devnull .I S_grow
127 cfa37a7b 2004-04-10 devnull grows a string's allocation by a fixed amount. It is useful if
128 cfa37a7b 2004-04-10 devnull you are reading directly into a string's character array but should
129 cfa37a7b 2004-04-10 devnull be avoided if possible.
131 cfa37a7b 2004-04-10 devnull .I S_array
132 cfa37a7b 2004-04-10 devnull is used to create a constant array, that is, one whose contents
133 cfa37a7b 2004-04-10 devnull won't change. It points directly to the character array
134 cfa37a7b 2004-04-10 devnull given as an argument. Tread lightly when using this call.
135 cfa37a7b 2004-04-10 devnull .SS "Filling the string
136 cfa37a7b 2004-04-10 devnull After its initial allocation, the string points to the beginning
137 cfa37a7b 2004-04-10 devnull of an allocated array of characters starting with
138 cfa37a7b 2004-04-10 devnull .SM NUL.
140 cfa37a7b 2004-04-10 devnull .I S_putc
141 cfa37a7b 2004-04-10 devnull writes a character into the string at the
142 cfa37a7b 2004-04-10 devnull pointer and advances the pointer to point after it.
144 cfa37a7b 2004-04-10 devnull .I S_terminate
145 cfa37a7b 2004-04-10 devnull writes a
147 cfa37a7b 2004-04-10 devnull at the pointer but doesn't advance it.
149 cfa37a7b 2004-04-10 devnull .I S_restart
150 cfa37a7b 2004-04-10 devnull resets the pointer to the begining of the string but doesn't change the contents.
152 cfa37a7b 2004-04-10 devnull .I S_reset
153 cfa37a7b 2004-04-10 devnull is equivalent to
154 cfa37a7b 2004-04-10 devnull .I s_restart
155 cfa37a7b 2004-04-10 devnull followed by
156 cfa37a7b 2004-04-10 devnull .IR s_terminate .
158 cfa37a7b 2004-04-10 devnull .I S_append
160 cfa37a7b 2004-04-10 devnull .I s_nappend
161 cfa37a7b 2004-04-10 devnull copy characters into the string at the pointer and
162 cfa37a7b 2004-04-10 devnull advance the pointer. They also write a
165 cfa37a7b 2004-04-10 devnull the pointer without advancing the pointer beyond it.
166 cfa37a7b 2004-04-10 devnull Both routines stop copying on encountering a
167 cfa37a7b 2004-04-10 devnull .SM NUL.
168 cfa37a7b 2004-04-10 devnull .I S_memappend
170 cfa37a7b 2004-04-10 devnull .I s_nappend
171 cfa37a7b 2004-04-10 devnull but doesn't stop at a
172 cfa37a7b 2004-04-10 devnull .SM NUL.
174 cfa37a7b 2004-04-10 devnull If you know the initial character array to be copied into a string,
175 cfa37a7b 2004-04-10 devnull you can allocate a string and copy in the bytes using
176 cfa37a7b 2004-04-10 devnull .IR s_copy .
177 cfa37a7b 2004-04-10 devnull This is the equivalent of a
178 cfa37a7b 2004-04-10 devnull .I s_new
179 cfa37a7b 2004-04-10 devnull followed by an
180 cfa37a7b 2004-04-10 devnull .IR s_append .
182 cfa37a7b 2004-04-10 devnull .I S_parse
183 cfa37a7b 2004-04-10 devnull copies the next white space terminated token from
186 cfa37a7b 2004-04-10 devnull the end of
187 cfa37a7b 2004-04-10 devnull .IR s2 .
188 cfa37a7b 2004-04-10 devnull White space is defined as space, tab,
189 cfa37a7b 2004-04-10 devnull and newline. Both single and double quoted strings are treated as
190 cfa37a7b 2004-04-10 devnull a single token. The bounding quotes are not copied.
191 cfa37a7b 2004-04-10 devnull There is no escape mechanism.
193 cfa37a7b 2004-04-10 devnull .I S_tolower
194 cfa37a7b 2004-04-10 devnull converts all
195 cfa37a7b 2004-04-10 devnull .SM ASCII
196 cfa37a7b 2004-04-10 devnull characters in the string to lower case.
197 cfa37a7b 2004-04-10 devnull .SS Multithreading
199 cfa37a7b 2004-04-10 devnull .I S_incref
200 cfa37a7b 2004-04-10 devnull is used by multithreaded programs to avoid having the string memory
201 cfa37a7b 2004-04-10 devnull released until the last user of the string performs an
202 cfa37a7b 2004-04-10 devnull .IR s_free .
203 cfa37a7b 2004-04-10 devnull .I S_unique
204 cfa37a7b 2004-04-10 devnull returns a unique copy of the string: if the reference count it
205 cfa37a7b 2004-04-10 devnull 1 it returns the string, otherwise it returns an
206 cfa37a7b 2004-04-10 devnull .I s_clone
207 cfa37a7b 2004-04-10 devnull of the string.
208 cfa37a7b 2004-04-10 devnull .SS "Bio interaction
210 cfa37a7b 2004-04-10 devnull .I S_read
211 cfa37a7b 2004-04-10 devnull reads the requested number of characters through a
212 cfa37a7b 2004-04-10 devnull .I Biobuf
213 cfa37a7b 2004-04-10 devnull into a string. The string is grown as necessary.
214 cfa37a7b 2004-04-10 devnull An eof or error terminates the read.
215 cfa37a7b 2004-04-10 devnull The number of bytes read is returned.
216 cfa37a7b 2004-04-10 devnull The string is null terminated.
218 cfa37a7b 2004-04-10 devnull .I S_read_line
219 cfa37a7b 2004-04-10 devnull reads up to and including the next newline and returns
220 cfa37a7b 2004-04-10 devnull a pointer to the beginning of the bytes read.
221 cfa37a7b 2004-04-10 devnull An eof or error terminates the read.
222 cfa37a7b 2004-04-10 devnull The string is null terminated.
224 cfa37a7b 2004-04-10 devnull .I S_getline
225 cfa37a7b 2004-04-10 devnull reads up to the next newline and returns
226 cfa37a7b 2004-04-10 devnull a pointer to the beginning of the bytes read. Leading
227 cfa37a7b 2004-04-10 devnull spaces and tabs and the trailing newline are all discarded.
228 cfa37a7b 2004-04-10 devnull .I S_getline
229 cfa37a7b 2004-04-10 devnull will recursively read through files included with
230 cfa37a7b 2004-04-10 devnull .B #include
231 cfa37a7b 2004-04-10 devnull and discard all other lines beginning with
233 cfa37a7b 2004-04-10 devnull .SH SOURCE
234 cfa37a7b 2004-04-10 devnull .B /sys/src/libString
235 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
236 bf8a59fa 2004-04-11 devnull .IR bio (3)
