str.3 (5435B)
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, Biobuf *b) 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 A 74 .B String 75 contains a pointer to the string data, its current length, and its allocated size. 76 .SS "Comparison with libString" 77 This library differs from Plan 9's standard libString in several key ways: 78 .IP \(bu 79 .B No locking: 80 libString includes locking mechanisms for thread safety, while this library omits them for simplicity. 81 .IP \(bu 82 .B Stack allocation: 83 .I Str 84 and 85 .I Strn 86 create stack-allocated strings that reference existing data, 87 while libString requires heap allocation for all strings. 88 .IP \(bu 89 .B Direct formatting: 90 .I Strprint 91 provides direct formatted output using 92 .IR vsmprint , 93 while libString requires separate formatting steps. 94 .IP \(bu 95 .B Simpler structure: 96 Uses a 3-field structure (s, n, size) compared to libString's 97 6-field structure with reference counting and locking. 98 .PP 99 Both libraries provide similar Biobuf integration for reading operations. 100 .PP 101 .I Str 102 creates a 103 .B String 104 from a null-terminated C string. 105 The resulting string references the original data and should not be modified. 106 .PP 107 .I Strn 108 creates a 109 .B String 110 from the first 111 .I n 112 characters of a C string. 113 The resulting string references the original data and should not be modified. 114 .PP 115 .I Strinit 116 initializes a 117 .B String 118 for use as a dynamic string. 119 The string is initially empty but has space allocated for growth. 120 .PP 121 .I Strdup 122 copies string 123 .I s 124 into string 125 .IR p , 126 which must be initialized. 127 Any existing content in 128 .I p 129 is replaced. 130 The behavior is undefined if 131 .I p 132 and 133 .I s 134 refer to the same string. 135 .PP 136 .I Straddc 137 appends character 138 .I c 139 to string 140 .IR p . 141 The string grows automatically if necessary. 142 .PP 143 .I Stradds 144 appends string 145 .I s 146 to string 147 .IR p . 148 The string grows automatically if necessary. 149 .PP 150 .I Strinsert 151 inserts string 152 .I t 153 into string 154 .I s 155 at position 156 .IR p . 157 Characters after position 158 .I p 159 are shifted to make room. 160 The behavior is undefined if 161 .I s 162 and 163 .I t 164 refer to the same string. 165 .PP 166 .I Strdelete 167 deletes characters from position 168 .I p0 169 to position 170 .I p1 171 (exclusive) from string 172 .IR s . 173 Characters after the deleted range are shifted down. 174 .PP 175 .I Strdelc 176 deletes the last character from string 177 .IR s . 178 If the string is empty, it does nothing. 179 .PP 180 .I Strinsure 181 ensures that string 182 .I s 183 has space for at least 184 .I n 185 characters. 186 This can be used to preallocate space for better performance. 187 .PP 188 .I Strprint 189 appends formatted text to string 190 .I s 191 using the same format specifiers as 192 .IR print (3). 193 It returns the number of characters added. 194 .PP 195 .I Strgetf 196 reads the entire contents of file descriptor 197 .I fd 198 into string 199 .IR s . 200 Any existing content is replaced. 201 .PP 202 .I Strgets 203 reads a line from 204 .I Biobuf 205 .I b 206 into string 207 .IR s . 208 The newline character is removed if present. 209 It returns the number of characters read (excluding any newline), 210 or 0 on end of file. 211 .PP 212 .I Strtok 213 tokenizes string 214 .I str 215 using separator characters in 216 .IR sep . 217 The first token is stored in 218 .I s 219 and 220 .I last 221 is set to point to the remaining string. 222 .PP 223 .I Strzero 224 empties string 225 .I s 226 and may shrink strings larger than the initial allocation size. 227 .PP 228 .I Strclose 229 frees the memory used by string 230 .I s 231 and resets it to empty. 232 .SH EXAMPLES 233 .PP 234 Basic string operations: 235 .IP 236 .EX 237 String s; 238 239 Strinit(&s); 240 Stradds(&s, Str("Hello")); 241 Straddc(&s, ' '); 242 Stradds(&s, Str("World")); 243 print("%s\en", s.s); 244 Strclose(&s); 245 .EE 246 .PP 247 Reading a file: 248 .IP 249 .EX 250 String s; 251 int fd; 252 253 Strinit(&s); 254 fd = open("file.txt", OREAD); 255 if(fd >= 0) { 256 Strgetf(&s, fd); 257 close(fd); 258 print("File contents: %s\en", s.s); 259 } 260 Strclose(&s); 261 .EE 262 .PP 263 String formatting: 264 .IP 265 .EX 266 String s; 267 268 Strinit(&s); 269 Strprint(&s, "Number: %d, String: %s", 42, "test"); 270 print("%s\en", s.s); 271 Strclose(&s); 272 .EE 273 .PP 274 String editing: 275 .IP 276 .EX 277 String s; 278 279 Strinit(&s); 280 Stradds(&s, Str("Hello World")); 281 Strdelete(&s, 5, 6); /* Delete space */ 282 Strinsert(&s, Str("_"), 5); 283 print("%s\en", s.s); /* Prints: Hello_World */ 284 Strclose(&s); 285 .EE 286 .SH SOURCE 287 .B \*9/src/libstr 288 .SH SEE ALSO 289 .MR bio (3) , 290 .MR print (3) , 291 .MR string (3) 292 .SH DIAGNOSTICS 293 Functions call 294 .I sysfatal 295 if memory allocation fails. 296 .SH NOTES 297 Strings created with 298 .I Str 299 and 300 .I Strn 301 reference the original data and should not be modified 302 or passed to 303 .IR Strclose . 304 Use 305 .I Strdup 306 to create a modifiable copy.