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