nsprpub/lib/libc/include/plstr.h

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