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 \- extensible strings
15 void s_free(String *s)
18 String* s_newalloc(int n)
21 String* s_array(char *p, int n)
24 String* s_grow(String *s, int n)
27 void s_putc(String *s, int c)
30 void s_terminate(String *s)
33 String* s_reset(String *s)
36 String* s_restart(String *s)
39 String* s_append(String *s, char *p)
42 String* s_nappend(String *s, char *p, int n)
45 String* s_memappend(String *s, char *p, int n)
48 String* s_copy(char *p)
51 String* s_parse(String *s1, String *s2)
55 void s_tolower(String *s)
58 String* s_incref(String *s)
61 String* s_unique(String *s)
67 int s_read(Biobuf *b, String *s, int n)
70 char* s_read_line(Biobuf *b, String *s)
73 char* s_getline(Biobuf *b, String *s)
76 These routines manipulate extensible strings.
79 which points to an array of characters. The string
80 maintains pointers to the beginning and end of the allocated
81 array. In addition a finger pointer keeps track of where
82 parsing will start (for
84 or new characters will be added (for
89 The structure, and a few useful macros are:
92 typedef struct String {
94 char *base; /* base of String */
95 char *end; /* end of allocated space+1 */
96 char *ptr; /* ptr into String */
100 #define s_to_c(s) ((s)->base)
101 #define s_len(s) ((s)->ptr-(s)->base)
102 #define s_clone(s) s_copy((s)->base)
106 is used when code needs a reference to the character array.
109 directly is frowned upon since it exposes too much of the implementation.
110 .SS "allocation and freeing
112 A string must be allocated before it can be used.
113 One normally does this using
115 giving the string an initial allocation of
117 If you know that the string will need to grow much
120 instead, specifying the number of bytes in the
124 causes both the string and its character array to be freed.
127 grows a string's allocation by a fixed amount. It is useful if
128 you are reading directly into a string's character array but should
129 be avoided if possible.
132 is used to create a constant array, that is, one whose contents
133 won't change. It points directly to the character array
134 given as an argument. Tread lightly when using this call.
135 .SS "Filling the string
136 After its initial allocation, the string points to the beginning
137 of an allocated array of characters starting with
141 writes a character into the string at the
142 pointer and advances the pointer to point after it.
147 at the pointer but doesn't advance it.
150 resets the pointer to the begining of the string but doesn't change the contents.
161 copy characters into the string at the pointer and
162 advance the pointer. They also write a
165 the pointer without advancing the pointer beyond it.
166 Both routines stop copying on encountering a
171 but doesn't stop at a
174 If you know the initial character array to be copied into a string,
175 you can allocate a string and copy in the bytes using
177 This is the equivalent of a
183 copies the next white space terminated token from
188 White space is defined as space, tab,
189 and newline. Both single and double quoted strings are treated as
190 a single token. The bounding quotes are not copied.
191 There is no escape mechanism.
196 characters in the string to lower case.
200 is used by multithreaded programs to avoid having the string memory
201 released until the last user of the string performs an
204 returns a unique copy of the string: if the reference count it
205 1 it returns the string, otherwise it returns an
211 reads the requested number of characters through a
213 into a string. The string is grown as necessary.
214 An eof or error terminates the read.
215 The number of bytes read is returned.
216 The string is null terminated.
219 reads up to and including the next newline and returns
220 a pointer to the beginning of the bytes read.
221 An eof or error terminates the read.
222 The string is null terminated.
225 reads up to the next newline and returns
226 a pointer to the beginning of the bytes read. Leading
227 spaces and tabs and the trailing newline are all discarded.
229 will recursively read through files included with
231 and discard all other lines beginning with
234 .B /sys/src/libString
