string.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)