Back to index

lightning-sunbird  0.9+nobinonly
plstr.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *   Roland Mainz <roland mainz@informatik.med.uni-giessen.de>
00024  *
00025  * Alternatively, the contents of this file may be used under the terms of
00026  * either the GNU General Public License Version 2 or later (the "GPL"), or
00027  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00028  * in which case the provisions of the GPL or the LGPL are applicable instead
00029  * of those above. If you wish to allow use of your version of this file only
00030  * under the terms of either the GPL or the LGPL, and not to allow others to
00031  * use your version of this file under the terms of the MPL, indicate your
00032  * decision by deleting the provisions above and replace them with the notice
00033  * and other provisions required by the GPL or the LGPL. If you do not delete
00034  * the provisions above, a recipient may use your version of this file under
00035  * the terms of any one of the MPL, the GPL or the LGPL.
00036  *
00037  * ***** END LICENSE BLOCK ***** */
00038 
00039 #ifndef _plstr_h
00040 #define _plstr_h
00041 
00042 /*
00043  * plstr.h
00044  *
00045  * This header file exports the API to the NSPR portable library or string-
00046  * handling functions.  
00047  * 
00048  * This API was not designed as an "optimal" or "ideal" string library; it 
00049  * was based on the good ol' unix string.3 functions, and was written to
00050  *
00051  *  1) replace the libc functions, for cross-platform consistency, 
00052  *  2) complete the API on platforms lacking common functions (e.g., 
00053  *     strcase*), and
00054  *  3) to implement some obvious "closure" functions that I've seen
00055  *     people hacking around in our code.
00056  *
00057  * Point number three largely means that most functions have an "strn"
00058  * limited-length version, and all comparison routines have a non-case-
00059  * sensitive version available.
00060  */
00061 
00062 #include "prtypes.h"
00063 
00064 PR_BEGIN_EXTERN_C
00065 /*
00066  * PL_strlen
00067  *
00068  * Returns the length of the provided string, not including the trailing '\0'.
00069  */
00070 
00071 PR_EXTERN(PRUint32)
00072 PL_strlen(const char *str);
00073 
00074 /*
00075  * PL_strnlen
00076  *
00077  * Returns the length of the provided string, not including the trailing '\0',
00078  * up to the indicated maximum.  The string will not be examined beyond the
00079  * maximum; if no terminating '\0' is found, the maximum will be returned.
00080  */
00081 
00082 PR_EXTERN(PRUint32)
00083 PL_strnlen(const char *str, PRUint32 max);
00084 
00085 /*
00086  * PL_strcpy
00087  *
00088  * Copies the source string, up to and including the trailing '\0', into the
00089  * destination buffer.  It does not (can not) verify that the destination
00090  * buffer is large enough.  It returns the "dest" argument.
00091  */
00092 
00093 PR_EXTERN(char *)
00094 PL_strcpy(char *dest, const char *src);
00095 
00096 /*
00097  * PL_strncpy
00098  *
00099  * Copies the source string into the destination buffer, up to and including
00100  * the trailing '\0' or up to and including the max'th character, whichever
00101  * comes first.  It does not (can not) verify that the destination buffer is
00102  * large enough.  If the source string is longer than the maximum length,
00103  * the result will *not* be null-terminated (JLRU).
00104  */
00105 
00106 PR_EXTERN(char *)
00107 PL_strncpy(char *dest, const char *src, PRUint32 max);
00108 
00109 /*
00110  * PL_strncpyz
00111  *
00112  * Copies the source string into the destination buffer, up to and including 
00113  * the trailing '\0' or up but not including the max'th character, whichever 
00114  * comes first.  It does not (can not) verify that the destination buffer is
00115  * large enough.  The destination string is always terminated with a '\0',
00116  * unlike the traditional libc implementation.  It returns the "dest" argument.
00117  *
00118  * NOTE: If you call this with a source "abcdefg" and a max of 5, the 
00119  * destination will end up with "abcd\0" (i.e., its strlen length will be 4)!
00120  *
00121  * This means you can do this:
00122  *
00123  *     char buffer[ SOME_SIZE ];
00124  *     PL_strncpyz(buffer, src, sizeof(buffer));
00125  *
00126  * and the result will be properly terminated.
00127  */
00128 
00129 PR_EXTERN(char *)
00130 PL_strncpyz(char *dest, const char *src, PRUint32 max);
00131 
00132 /*
00133  * PL_strdup
00134  *
00135  * Returns a pointer to a malloc'd extent of memory containing a duplicate
00136  * of the argument string.  The size of the allocated extent is one greater
00137  * than the length of the argument string, because of the terminator.  A
00138  * null argument, like a zero-length argument, will result in a pointer to
00139  * a one-byte extent containing the null value.  This routine returns null
00140  * upon malloc failure.
00141  */
00142 
00143 PR_EXTERN(char *)
00144 PL_strdup(const char *s);
00145 
00146 /*
00147  * PL_strfree
00148  *
00149  * Free memory allocated by PL_strdup
00150  */
00151 
00152 PR_EXTERN(void)
00153 PL_strfree(char *s);
00154 
00155 /*
00156  * PL_strndup
00157  *
00158  * Returns a pointer to a malloc'd extent of memory containing a duplicate
00159  * of the argument string, up to the maximum specified.  If the argument
00160  * string has a length greater than the value of the specified maximum, the
00161  * return value will be a pointer to an extent of memory of length one
00162  * greater than the maximum specified.  A null string, a zero-length string,
00163  * or a zero maximum will all result in a pointer to a one-byte extent
00164  * containing the null value.  This routine returns null upon malloc failure.
00165  */
00166 
00167 PR_EXTERN(char *)
00168 PL_strndup(const char *s, PRUint32 max);
00169 
00170 /*
00171  * PL_strcat
00172  *
00173  * Appends a copy of the string pointed to by the second argument to the
00174  * end of the string pointed to by the first.  The destination buffer is
00175  * not (can not be) checked for sufficient size.  A null destination
00176  * argument returns null; otherwise, the first argument is returned.
00177  */
00178 
00179 PR_EXTERN(char *)
00180 PL_strcat(char *dst, const char *src);
00181 
00182 /*
00183  * PL_strncat
00184  *
00185  * Appends a copy of the string pointed to by the second argument, up to
00186  * the maximum size specified, to the end of the string pointed to by the
00187  * first.  The destination buffer is not (can not be) checked for sufficient
00188  * size.  A null destination argument returns null; otherwise, the first 
00189  * argument is returned.  If the maximum size limits the copy, then the
00190  * result will *not* be null-terminated (JLRU).  A null destination
00191  * returns null; otherwise, the destination argument is returned.
00192  */
00193 
00194 PR_EXTERN(char *)
00195 PL_strncat(char *dst, const char *src, PRUint32 max);
00196 
00197 /*
00198  * PL_strcatn
00199  *
00200  * Appends a copy of the string pointed to by the third argument, to the
00201  * end of the string pointed to by the first.  The second argument specifies
00202  * the maximum size of the destination buffer, including the null termination.
00203  * If the existing string in dst is longer than the max, no action is taken.
00204  * The resulting string will be null-terminated.  A null destination returns
00205  * null; otherwise, the destination argument is returned.
00206  */
00207 
00208 PR_EXTERN(char *)
00209 PL_strcatn(char *dst, PRUint32 max, const char *src);
00210 
00211 /*
00212  * PL_strcmp
00213  *
00214  * Returns an integer, the sign of which -- positive, zero, or negative --
00215  * reflects the lexical sorting order of the two strings indicated.  The
00216  * result is positive if the first string comes after the second.  The
00217  * NSPR implementation is not i18n.
00218  */
00219 
00220 PR_EXTERN(PRIntn)
00221 PL_strcmp(const char *a, const char *b);
00222 
00223 /*
00224  * PL_strncmp
00225  * 
00226  * Returns an integer, the sign of which -- positive, zero, or negative --
00227  * reflects the lexical sorting order of the two strings indicated, up to
00228  * the maximum specified.  The result is positive if the first string comes 
00229  * after the second.  The NSPR implementation is not i18n.  If the maximum
00230  * is zero, only the existance or non-existance (pointer is null) of the
00231  * strings is compared.
00232  */
00233 
00234 PR_EXTERN(PRIntn)
00235 PL_strncmp(const char *a, const char *b, PRUint32 max);
00236 
00237 /*
00238  * PL_strcasecmp
00239  *
00240  * Returns an integer, the sign of which -- positive, zero or negative --
00241  * reflects the case-insensitive lexical sorting order of the two strings
00242  * indicated.  The result is positive if the first string comes after the 
00243  * second.  The NSPR implementation is not i18n.
00244  */
00245 
00246 PR_EXTERN(PRIntn)
00247 PL_strcasecmp(const char *a, const char *b);
00248 
00249 /*
00250  * PL_strncasecmp
00251  *
00252  * Returns an integer, the sign of which -- positive, zero or negative --
00253  * reflects the case-insensitive lexical sorting order of the first n characters
00254  * of the two strings indicated.  The result is positive if the first string comes 
00255  * after the second.  The NSPR implementation is not i18n.
00256  */
00257 
00258 PR_EXTERN(PRIntn)
00259 PL_strncasecmp(const char *a, const char *b, PRUint32 max);
00260 
00261 /*
00262  * PL_strchr
00263  *
00264  * Returns a pointer to the first instance of the specified character in the
00265  * provided string.  It returns null if the character is not found, or if the
00266  * provided string is null.  The character may be the null character.
00267  */
00268 
00269 PR_EXTERN(char *)
00270 PL_strchr(const char *s, char c);
00271 
00272 /*
00273  * PL_strrchr
00274  *
00275  * Returns a pointer to the last instance of the specified character in the
00276  * provided string.  It returns null if the character is not found, or if the
00277  * provided string is null.  The character may be the null character.
00278  */
00279 
00280 PR_EXTERN(char *)
00281 PL_strrchr(const char *s, char c);
00282 
00283 /*
00284  * PL_strnchr
00285  * 
00286  * Returns a pointer to the first instance of the specified character within the
00287  * first n characters of the provided string.  It returns null if the character
00288  * is not found, or if the provided string is null.  The character may be the
00289  * null character.
00290  */
00291 
00292 PR_EXTERN(char *)
00293 PL_strnchr(const char *s, char c, PRUint32 n);
00294 
00295 /*
00296  * PL_strnrchr
00297  *
00298  * Returns a pointer to the last instance of the specified character within the
00299  * first n characters of the provided string.  It returns null if the character is
00300  * not found, or if the provided string is null.  The character may be the null
00301  * character.
00302  */
00303 
00304 PR_EXTERN(char *)
00305 PL_strnrchr(const char *s, char c, PRUint32 n);
00306 
00307 /*
00308  * NOTE: Looking for strcasechr, strcaserchr, strncasechr, or strncaserchr?
00309  * Use strpbrk, strprbrk, strnpbrk or strnprbrk.
00310  */
00311 
00312 /*
00313  * PL_strpbrk
00314  *
00315  * Returns a pointer to the first instance in the first string of any character
00316  * (not including the terminating null character) of the second string.  It returns
00317  * null if either string is null.
00318  */
00319 
00320 PR_EXTERN(char *)
00321 PL_strpbrk(const char *s, const char *list);
00322 
00323 /*
00324  * PL_strprbrk
00325  *
00326  * Returns a pointer to the last instance in the first string of any character
00327  * (not including the terminating null character) of the second string.  It returns
00328  * null if either string is null.
00329  */
00330 
00331 PR_EXTERN(char *)
00332 PL_strprbrk(const char *s, const char *list);
00333 
00334 /*
00335  * PL_strnpbrk
00336  *
00337  * Returns a pointer to the first instance (within the first n characters) of any
00338  * character (not including the terminating null character) of the second string.
00339  * It returns null if either string is null.
00340  */
00341 
00342 PR_EXTERN(char *)
00343 PL_strnpbrk(const char *s, const char *list, PRUint32 n);
00344 
00345 /*
00346  * PL_strnprbrk
00347  *
00348  * Returns a pointer to the last instance (within the first n characters) of any
00349  * character (not including the terminating null character) of the second string.
00350  * It returns null if either string is null.
00351  */
00352 
00353 PR_EXTERN(char *)
00354 PL_strnprbrk(const char *s, const char *list, PRUint32 n);
00355 
00356 /*
00357  * PL_strstr
00358  *
00359  * Returns a pointer to the first instance of the little string within the
00360  * big one.  It returns null if either string is null.
00361  */
00362 
00363 PR_EXTERN(char *)
00364 PL_strstr(const char *big, const char *little);
00365 
00366 /*
00367  * PL_strrstr
00368  *
00369  * Returns a pointer to the last instance of the little string within the big one.
00370  * It returns null if either string is null.
00371  */
00372 
00373 PR_EXTERN(char *)
00374 PL_strrstr(const char *big, const char *little);
00375 
00376 /*
00377  * PL_strnstr
00378  *
00379  * Returns a pointer to the first instance of the little string within the first
00380  * n characters of the big one.  It returns null if either string is null.  It
00381  * returns null if the length of the little string is greater than n.
00382  */
00383 
00384 PR_EXTERN(char *)
00385 PL_strnstr(const char *big, const char *little, PRUint32 n);
00386 
00387 /*
00388  * PL_strnrstr
00389  *
00390  * Returns a pointer to the last instance of the little string within the first
00391  * n characters of the big one.  It returns null if either string is null.  It
00392  * returns null if the length of the little string is greater than n.
00393  */
00394 
00395 PR_EXTERN(char *)
00396 PL_strnrstr(const char *big, const char *little, PRUint32 max);
00397 
00398 /*
00399  * PL_strcasestr
00400  *
00401  * Returns a pointer to the first instance of the little string within the big one,
00402  * ignoring case.  It returns null if either string is null.
00403  */
00404 
00405 PR_EXTERN(char *)
00406 PL_strcasestr(const char *big, const char *little);
00407 
00408 /*
00409  * PL_strcaserstr
00410  *
00411  * Returns a pointer to the last instance of the little string within the big one,
00412  * ignoring case.  It returns null if either string is null.
00413  */
00414 
00415 PR_EXTERN(char *)
00416 PL_strcaserstr(const char *big, const char *little);
00417 
00418 /*
00419  * PL_strncasestr
00420  *
00421  * Returns a pointer to the first instance of the little string within the first
00422  * n characters of the big one, ignoring case.  It returns null if either string is 
00423  * null.  It returns null if the length of the little string is greater than n.
00424  */
00425 
00426 PR_EXTERN(char *)
00427 PL_strncasestr(const char *big, const char *little, PRUint32 max);
00428 
00429 /*
00430  * PL_strncaserstr
00431  *
00432  * Returns a pointer to the last instance of the little string within the first
00433  * n characters of the big one, ignoring case.  It returns null if either string is
00434  * null.  It returns null if the length of the little string is greater than n.
00435  */
00436 
00437 PR_EXTERN(char *)
00438 PL_strncaserstr(const char *big, const char *little, PRUint32 max);
00439 
00440 /*
00441  * PL_strtok_r
00442  *
00443  * Splits the string s1 into tokens, separated by one or more characters
00444  * from the separator string s2.  The argument lasts points to a
00445  * user-supplied char * pointer in which PL_strtok_r stores information
00446  * for it to continue scanning the same string.
00447  *
00448  * In the first call to PL_strtok_r, s1 points to a string and the value
00449  * of *lasts is ignored.  PL_strtok_r returns a pointer to the first
00450  * token, writes '\0' into the character following the first token, and
00451  * updates *lasts.
00452  *
00453  * In subsequent calls, s1 is null and lasts must stay unchanged from the
00454  * previous call.  The separator string s2 may be different from call to
00455  * call.  PL_strtok_r returns a pointer to the next token in s1.  When no
00456  * token remains in s1, PL_strtok_r returns null.
00457  */
00458 
00459 PR_EXTERN(char *)
00460 PL_strtok_r(char *s1, const char *s2, char **lasts);
00461 
00462 /*
00463  * Things not (yet?) included: strspn/strcspn, strsep.
00464  * memchr, memcmp, memcpy, memccpy, index, rindex, bcmp, bcopy, bzero.
00465  * Any and all i18n/l10n stuff.
00466  */
00467 
00468 PR_END_EXTERN_C
00469 
00470 #endif /* _plstr_h */