plstr.h (13426B)
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #ifndef _plstr_h 7 #define _plstr_h 8 9 /* 10 * plstr.h 11 * 12 * This header file exports the API to the NSPR portable library or string- 13 * handling functions. 14 * 15 * This API was not designed as an "optimal" or "ideal" string library; it 16 * was based on the good ol' unix string.3 functions, and was written to 17 * 18 * 1) replace the libc functions, for cross-platform consistency, 19 * 2) complete the API on platforms lacking common functions (e.g., 20 * strcase*), and 21 * 3) to implement some obvious "closure" functions that I've seen 22 * people hacking around in our code. 23 * 24 * Point number three largely means that most functions have an "strn" 25 * limited-length version, and all comparison routines have a non-case- 26 * sensitive version available. 27 */ 28 29 #include "prtypes.h" 30 31 PR_BEGIN_EXTERN_C 32 /* 33 * PL_strlen 34 * 35 * Returns the length of the provided string, not including the trailing '\0'. 36 */ 37 38 PR_EXTERN(PRUint32) 39 PL_strlen(const char *str); 40 41 /* 42 * PL_strnlen 43 * 44 * Returns the length of the provided string, not including the trailing '\0', 45 * up to the indicated maximum. The string will not be examined beyond the 46 * maximum; if no terminating '\0' is found, the maximum will be returned. 47 */ 48 49 PR_EXTERN(PRUint32) 50 PL_strnlen(const char *str, PRUint32 max); 51 52 /* 53 * PL_strcpy 54 * 55 * Copies the source string, up to and including the trailing '\0', into the 56 * destination buffer. It does not (can not) verify that the destination 57 * buffer is large enough. It returns the "dest" argument. 58 */ 59 60 PR_EXTERN(char *) 61 PL_strcpy(char *dest, const char *src); 62 63 /* 64 * PL_strncpy 65 * 66 * Copies the source string into the destination buffer, up to and including 67 * the trailing '\0' or up to and including the max'th character, whichever 68 * comes first. It does not (can not) verify that the destination buffer is 69 * large enough. If the source string is longer than the maximum length, 70 * the result will *not* be null-terminated (JLRU). 71 */ 72 73 PR_EXTERN(char *) 74 PL_strncpy(char *dest, const char *src, PRUint32 max); 75 76 /* 77 * PL_strncpyz 78 * 79 * Copies the source string into the destination buffer, up to and including 80 * the trailing '\0' or up but not including the max'th character, whichever 81 * comes first. It does not (can not) verify that the destination buffer is 82 * large enough. The destination string is always terminated with a '\0', 83 * unlike the traditional libc implementation. It returns the "dest" argument. 84 * 85 * NOTE: If you call this with a source "abcdefg" and a max of 5, the 86 * destination will end up with "abcd\0" (i.e., its strlen length will be 4)! 87 * 88 * This means you can do this: 89 * 90 * char buffer[ SOME_SIZE ]; 91 * PL_strncpyz(buffer, src, sizeof(buffer)); 92 * 93 * and the result will be properly terminated. 94 */ 95 96 PR_EXTERN(char *) 97 PL_strncpyz(char *dest, const char *src, PRUint32 max); 98 99 /* 100 * PL_strdup 101 * 102 * Returns a pointer to a malloc'd extent of memory containing a duplicate 103 * of the argument string. The size of the allocated extent is one greater 104 * than the length of the argument string, because of the terminator. A 105 * null argument, like a zero-length argument, will result in a pointer to 106 * a one-byte extent containing the null value. This routine returns null 107 * upon malloc failure. 108 */ 109 110 PR_EXTERN(char *) 111 PL_strdup(const char *s); 112 113 /* 114 * PL_strfree 115 * 116 * Free memory allocated by PL_strdup 117 */ 118 119 PR_EXTERN(void) 120 PL_strfree(char *s); 121 122 /* 123 * PL_strndup 124 * 125 * Returns a pointer to a malloc'd extent of memory containing a duplicate 126 * of the argument string, up to the maximum specified. If the argument 127 * string has a length greater than the value of the specified maximum, the 128 * return value will be a pointer to an extent of memory of length one 129 * greater than the maximum specified. A null string, a zero-length string, 130 * or a zero maximum will all result in a pointer to a one-byte extent 131 * containing the null value. This routine returns null upon malloc failure. 132 */ 133 134 PR_EXTERN(char *) 135 PL_strndup(const char *s, PRUint32 max); 136 137 /* 138 * PL_strcat 139 * 140 * Appends a copy of the string pointed to by the second argument to the 141 * end of the string pointed to by the first. The destination buffer is 142 * not (can not be) checked for sufficient size. A null destination 143 * argument returns null; otherwise, the first argument is returned. 144 */ 145 146 PR_EXTERN(char *) 147 PL_strcat(char *dst, const char *src); 148 149 /* 150 * PL_strncat 151 * 152 * Appends a copy of the string pointed to by the second argument, up to 153 * the maximum size specified, to the end of the string pointed to by the 154 * first. The destination buffer is not (can not be) checked for sufficient 155 * size. A null destination argument returns null; otherwise, the first 156 * argument is returned. If the maximum size limits the copy, then the 157 * result will *not* be null-terminated (JLRU). A null destination 158 * returns null; otherwise, the destination argument is returned. 159 */ 160 161 PR_EXTERN(char *) 162 PL_strncat(char *dst, const char *src, PRUint32 max); 163 164 /* 165 * PL_strcatn 166 * 167 * Appends a copy of the string pointed to by the third argument, to the 168 * end of the string pointed to by the first. The second argument specifies 169 * the maximum size of the destination buffer, including the null termination. 170 * If the existing string in dst is longer than the max, no action is taken. 171 * The resulting string will be null-terminated. A null destination returns 172 * null; otherwise, the destination argument is returned. 173 */ 174 175 PR_EXTERN(char *) 176 PL_strcatn(char *dst, PRUint32 max, const char *src); 177 178 /* 179 * PL_strcmp 180 * 181 * Returns an integer, the sign of which -- positive, zero, or negative -- 182 * reflects the lexical sorting order of the two strings indicated. The 183 * result is positive if the first string comes after the second. The 184 * NSPR implementation is not i18n. 185 */ 186 187 PR_EXTERN(PRIntn) 188 PL_strcmp(const char *a, const char *b); 189 190 /* 191 * PL_strncmp 192 * 193 * Returns an integer, the sign of which -- positive, zero, or negative -- 194 * reflects the lexical sorting order of the two strings indicated, up to 195 * the maximum specified. The result is positive if the first string comes 196 * after the second. The NSPR implementation is not i18n. If the maximum 197 * is zero, only the existance or non-existance (pointer is null) of the 198 * strings is compared. 199 */ 200 201 PR_EXTERN(PRIntn) 202 PL_strncmp(const char *a, const char *b, PRUint32 max); 203 204 /* 205 * PL_strcasecmp 206 * 207 * Returns an integer, the sign of which -- positive, zero or negative -- 208 * reflects the case-insensitive lexical sorting order of the two strings 209 * indicated. The result is positive if the first string comes after the 210 * second. The NSPR implementation is not i18n. 211 */ 212 213 PR_EXTERN(PRIntn) 214 PL_strcasecmp(const char *a, const char *b); 215 216 /* 217 * PL_strncasecmp 218 * 219 * Returns an integer, the sign of which -- positive, zero or negative -- 220 * reflects the case-insensitive lexical sorting order of the first n characters 221 * of the two strings indicated. The result is positive if the first string comes 222 * after the second. The NSPR implementation is not i18n. 223 */ 224 225 PR_EXTERN(PRIntn) 226 PL_strncasecmp(const char *a, const char *b, PRUint32 max); 227 228 /* 229 * PL_strchr 230 * 231 * Returns a pointer to the first instance of the specified character in the 232 * provided string. It returns null if the character is not found, or if the 233 * provided string is null. The character may be the null character. 234 */ 235 236 PR_EXTERN(char *) 237 PL_strchr(const char *s, char c); 238 239 /* 240 * PL_strrchr 241 * 242 * Returns a pointer to the last instance of the specified character in the 243 * provided string. It returns null if the character is not found, or if the 244 * provided string is null. The character may be the null character. 245 */ 246 247 PR_EXTERN(char *) 248 PL_strrchr(const char *s, char c); 249 250 /* 251 * PL_strnchr 252 * 253 * Returns a pointer to the first instance of the specified character within the 254 * first n characters of the provided string. It returns null if the character 255 * is not found, or if the provided string is null. The character may be the 256 * null character. 257 */ 258 259 PR_EXTERN(char *) 260 PL_strnchr(const char *s, char c, PRUint32 n); 261 262 /* 263 * PL_strnrchr 264 * 265 * Returns a pointer to the last instance of the specified character within the 266 * first n characters of the provided string. It returns null if the character is 267 * not found, or if the provided string is null. The character may be the null 268 * character. 269 */ 270 271 PR_EXTERN(char *) 272 PL_strnrchr(const char *s, char c, PRUint32 n); 273 274 /* 275 * NOTE: Looking for strcasechr, strcaserchr, strncasechr, or strncaserchr? 276 * Use strpbrk, strprbrk, strnpbrk or strnprbrk. 277 */ 278 279 /* 280 * PL_strpbrk 281 * 282 * Returns a pointer to the first instance in the first string of any character 283 * (not including the terminating null character) of the second string. It returns 284 * null if either string is null. 285 */ 286 287 PR_EXTERN(char *) 288 PL_strpbrk(const char *s, const char *list); 289 290 /* 291 * PL_strprbrk 292 * 293 * Returns a pointer to the last instance in the first string of any character 294 * (not including the terminating null character) of the second string. It returns 295 * null if either string is null. 296 */ 297 298 PR_EXTERN(char *) 299 PL_strprbrk(const char *s, const char *list); 300 301 /* 302 * PL_strnpbrk 303 * 304 * Returns a pointer to the first instance (within the first n characters) of any 305 * character (not including the terminating null character) of the second string. 306 * It returns null if either string is null. 307 */ 308 309 PR_EXTERN(char *) 310 PL_strnpbrk(const char *s, const char *list, PRUint32 n); 311 312 /* 313 * PL_strnprbrk 314 * 315 * Returns a pointer to the last instance (within the first n characters) of any 316 * character (not including the terminating null character) of the second string. 317 * It returns null if either string is null. 318 */ 319 320 PR_EXTERN(char *) 321 PL_strnprbrk(const char *s, const char *list, PRUint32 n); 322 323 /* 324 * PL_strstr 325 * 326 * Returns a pointer to the first instance of the little string within the 327 * big one. It returns null if either string is null. 328 */ 329 330 PR_EXTERN(char *) 331 PL_strstr(const char *big, const char *little); 332 333 /* 334 * PL_strrstr 335 * 336 * Returns a pointer to the last instance of the little string within the big one. 337 * It returns null if either string is null. 338 */ 339 340 PR_EXTERN(char *) 341 PL_strrstr(const char *big, const char *little); 342 343 /* 344 * PL_strnstr 345 * 346 * Returns a pointer to the first instance of the little string within the first 347 * n characters of the big one. It returns null if either string is null. It 348 * returns null if the length of the little string is greater than n. 349 */ 350 351 PR_EXTERN(char *) 352 PL_strnstr(const char *big, const char *little, PRUint32 n); 353 354 /* 355 * PL_strnrstr 356 * 357 * Returns a pointer to the last instance of the little string within the first 358 * n characters of the big one. It returns null if either string is null. It 359 * returns null if the length of the little string is greater than n. 360 */ 361 362 PR_EXTERN(char *) 363 PL_strnrstr(const char *big, const char *little, PRUint32 max); 364 365 /* 366 * PL_strcasestr 367 * 368 * Returns a pointer to the first instance of the little string within the big one, 369 * ignoring case. It returns null if either string is null. 370 */ 371 372 PR_EXTERN(char *) 373 PL_strcasestr(const char *big, const char *little); 374 375 /* 376 * PL_strcaserstr 377 * 378 * Returns a pointer to the last instance of the little string within the big one, 379 * ignoring case. It returns null if either string is null. 380 */ 381 382 PR_EXTERN(char *) 383 PL_strcaserstr(const char *big, const char *little); 384 385 /* 386 * PL_strncasestr 387 * 388 * Returns a pointer to the first instance of the little string within the first 389 * n characters of the big one, ignoring case. It returns null if either string is 390 * null. It returns null if the length of the little string is greater than n. 391 */ 392 393 PR_EXTERN(char *) 394 PL_strncasestr(const char *big, const char *little, PRUint32 max); 395 396 /* 397 * PL_strncaserstr 398 * 399 * Returns a pointer to the last instance of the little string within the first 400 * n characters of the big one, ignoring case. It returns null if either string is 401 * null. It returns null if the length of the little string is greater than n. 402 */ 403 404 PR_EXTERN(char *) 405 PL_strncaserstr(const char *big, const char *little, PRUint32 max); 406 407 /* 408 * PL_strtok_r 409 * 410 * Splits the string s1 into tokens, separated by one or more characters 411 * from the separator string s2. The argument lasts points to a 412 * user-supplied char * pointer in which PL_strtok_r stores information 413 * for it to continue scanning the same string. 414 * 415 * In the first call to PL_strtok_r, s1 points to a string and the value 416 * of *lasts is ignored. PL_strtok_r returns a pointer to the first 417 * token, writes '\0' into the character following the first token, and 418 * updates *lasts. 419 * 420 * In subsequent calls, s1 is null and lasts must stay unchanged from the 421 * previous call. The separator string s2 may be different from call to 422 * call. PL_strtok_r returns a pointer to the next token in s1. When no 423 * token remains in s1, PL_strtok_r returns null. 424 */ 425 426 PR_EXTERN(char *) 427 PL_strtok_r(char *s1, const char *s2, char **lasts); 428 429 /* 430 * Things not (yet?) included: strspn/strcspn, strsep. 431 * memchr, memcmp, memcpy, memccpy, index, rindex, bcmp, bcopy, bzero. 432 * Any and all i18n/l10n stuff. 433 */ 434 435 PR_END_EXTERN_C 436 437 #endif /* _plstr_h */