str.3 (5127B)
1 .TH STR 3 2 .SH NAME 3 Str, Strn, Straddc, Stradds, Strclose, Strdelc, Strdelete, Strdup, Strgetf, Strgets, Strinit, Strinsert, Strinsure, Strprint, Strtok, Strzero \- dynamic string library 4 .SH SYNOPSIS 5 .B #include <u.h> 6 .br 7 .B #include <libc.h> 8 .br 9 .B #include <str.h> 10 .PP 11 .ft L 12 .nf 13 .ta \w'\fL 'u +\w'\fLulong 'u 14 typedef struct { 15 char *s; 16 ulong n; 17 ulong size; 18 } String; 19 .fi 20 .PP 21 .ta \w'\fLString 'u 22 .B 23 String Str(char *s) 24 .PP 25 .B 26 String Strn(char *s, ulong n) 27 .PP 28 .B 29 void Straddc(String *p, int c) 30 .PP 31 .B 32 void Stradds(String *p, String s) 33 .PP 34 .B 35 void Strclose(String *s) 36 .PP 37 .B 38 void Strdelc(String *s) 39 .PP 40 .B 41 void Strdelete(String *s, Posn p0, Posn p1) 42 .PP 43 .B 44 void Strdup(String *p, String s) 45 .PP 46 .B 47 void Strgetf(String *s, int fd) 48 .PP 49 .B 50 int Strgets(String *s, int fd) 51 .PP 52 .B 53 void Strinit(String *s) 54 .PP 55 .B 56 void Strinsert(String *s, String t, Posn p0) 57 .PP 58 .B 59 void Strinsure(String *s, ulong n) 60 .PP 61 .B 62 int Strprint(String *s, char *fmt, ...) 63 .PP 64 .B 65 void Strtok(String *s, char *str, char *sep, char **last) 66 .PP 67 .B 68 void Strzero(String *s) 69 .SH DESCRIPTION 70 This library provides a dynamic string implementation that is 71 mutually exclusive with Plan 9's standard libString. 72 It offers a simpler, more lightweight alternative focused on ease of use. 73 .PP 74 A 75 .B String 76 contains a pointer to the string data, its current length, and its allocated size. 77 .PP 78 When 79 .I size 80 is 0, the string cannot be shrunk or grown. 81 .SS "Comparison with libString" 82 This library differs from Plan 9's standard libString in several key ways: 83 .IP - 84 .B No locking: 85 libString includes locking mechanisms for thread safety, while this library omits them for simplicity. 86 .IP - 87 .B Stack allocation: 88 .I Str 89 and 90 .I Strn 91 create stack-allocated strings that reference existing data, 92 while libString requires heap allocation for all strings. 93 .IP - 94 .B Direct formatting: 95 .I Strprint 96 provides direct formatted output using 97 .IR vsmprint , 98 while libString requires separate formatting steps. 99 .IP - 100 .B Simpler structure: 101 Uses a 3-field structure (s, n, size) compared to libString's 102 6-field structure with reference counting and locking. 103 .PP 104 Both libraries provide similar Biobuf integration for reading operations. 105 .PP 106 .I Str 107 creates a 108 .B String 109 that references a null-terminated C string, with size set to 0. 110 .PP 111 .I Strn 112 creates a 113 .B String 114 that references 115 .I n 116 characters of a C string, with size set to 0. 117 It does not modify the data to guarantee a valid C string, but libstr 118 functions will respect the length it claims to have. 119 .PP 120 .I Strinit 121 initializes a 122 .B String 123 for use as a dynamic string. 124 .PP 125 .I Strdup 126 copies string 127 .I s 128 into string 129 .IR p , 130 which must be initialized. 131 Any existing content in 132 .I p 133 is replaced. 134 The behavior is undefined if 135 .I p 136 and 137 .I s 138 refer to the same string. 139 .PP 140 .I Straddc 141 appends character 142 .I c 143 to string 144 .IR p . 145 .PP 146 .I Stradds 147 appends string 148 .I s 149 to string 150 .IR p . 151 .PP 152 .I Strinsert 153 inserts string 154 .I t 155 into string 156 .I s 157 at position 158 .IR p . 159 The behavior is undefined if 160 .I s 161 and 162 .I t 163 refer to the same string. 164 .PP 165 .I Strdelete 166 deletes characters from position 167 .I p0 168 to position 169 .I p1 170 (exclusive) from string 171 .IR s . 172 Characters after the deleted range are shifted down. 173 .PP 174 .I Strdelc 175 deletes the last character from string 176 .IR s . 177 If the string is empty, it does nothing. 178 .PP 179 .I Strinsure 180 ensures that string 181 .I s 182 has space for at least 183 .I n 184 characters. 185 .PP 186 .I Strprint 187 appends formatted text to string 188 .I s 189 using the same format specifiers as 190 .IR print (3). 191 It returns the number of characters added. 192 .PP 193 .I Strgetf 194 reads the entire contents of file descriptor 195 .I fd 196 into string 197 .IR s . 198 Any existing content is replaced. 199 .PP 200 .I Strgets 201 reads a line from an open file descriptor 202 .IR fd 203 into string 204 .IR s . 205 The newline character is removed if present. 206 It returns the number of characters read, or 0 on end of file. 207 Any existing content is replaced. 208 .PP 209 .I Strtok 210 tokenizes string 211 .I str 212 using separator characters in 213 .IR sep . 214 The first token is stored in 215 .I s 216 and 217 .I last 218 is set to point to the remaining string. 219 .PP 220 .I Strzero 221 empties string 222 .I s 223 and may shrink strings larger than the initial allocation size. 224 .PP 225 .I Strclose 226 frees the memory used by string 227 .I s 228 and resets it to empty. 229 .SH EXAMPLES 230 .PP 231 Basic string operations: 232 .IP 233 .EX 234 String s; 235 236 Strinit(&s); 237 Stradds(&s, Str("Hello")); 238 Straddc(&s, ' '); 239 Stradds(&s, Str("World")); 240 print("%s\en", s.s); 241 Strclose(&s); 242 .EE 243 .PP 244 Reading a file: 245 .IP 246 .EX 247 String s; 248 int fd; 249 250 Strinit(&s); 251 fd = open("file.txt", OREAD); 252 if(fd >= 0) { 253 Strgetf(&s, fd); 254 close(fd); 255 print("File contents: %s\en", s.s); 256 } 257 Strclose(&s); 258 .EE 259 .PP 260 String formatting: 261 .IP 262 .EX 263 String s; 264 265 Strinit(&s); 266 Strprint(&s, "Number: %d, String: %s", 42, "test"); 267 print("%s\en", s.s); 268 Strclose(&s); 269 .EE 270 .PP 271 String editing: 272 .IP 273 .EX 274 String s; 275 276 Strinit(&s); 277 Stradds(&s, Str("Hello World")); 278 Strdelete(&s, 5, 6); /* Delete space */ 279 Strinsert(&s, Str("_"), 5); 280 print("%s\en", s.s); /* Prints: Hello_World */ 281 Strclose(&s); 282 .EE 283 .SH SOURCE 284 .B \*9/src/libstr 285 .SH SEE ALSO 286 .MR bio (3) , 287 .MR print (3) , 288 .MR string (3) 289 .SH DIAGNOSTICS 290 Functions call 291 .I sysfatal 292 if memory allocation fails. 293 .PP 294 Strinsure calls 295 .I sysfatal 296 when size is 0.