michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef _plstr_h
michael@0: #define _plstr_h
michael@0: 
michael@0: /*
michael@0:  * plstr.h
michael@0:  *
michael@0:  * This header file exports the API to the NSPR portable library or string-
michael@0:  * handling functions.  
michael@0:  * 
michael@0:  * This API was not designed as an "optimal" or "ideal" string library; it 
michael@0:  * was based on the good ol' unix string.3 functions, and was written to
michael@0:  *
michael@0:  *  1) replace the libc functions, for cross-platform consistency, 
michael@0:  *  2) complete the API on platforms lacking common functions (e.g., 
michael@0:  *     strcase*), and
michael@0:  *  3) to implement some obvious "closure" functions that I've seen
michael@0:  *     people hacking around in our code.
michael@0:  *
michael@0:  * Point number three largely means that most functions have an "strn"
michael@0:  * limited-length version, and all comparison routines have a non-case-
michael@0:  * sensitive version available.
michael@0:  */
michael@0: 
michael@0: #include "prtypes.h"
michael@0: 
michael@0: PR_BEGIN_EXTERN_C
michael@0: /*
michael@0:  * PL_strlen
michael@0:  *
michael@0:  * Returns the length of the provided string, not including the trailing '\0'.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(PRUint32)
michael@0: PL_strlen(const char *str);
michael@0: 
michael@0: /*
michael@0:  * PL_strnlen
michael@0:  *
michael@0:  * Returns the length of the provided string, not including the trailing '\0',
michael@0:  * up to the indicated maximum.  The string will not be examined beyond the
michael@0:  * maximum; if no terminating '\0' is found, the maximum will be returned.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(PRUint32)
michael@0: PL_strnlen(const char *str, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strcpy
michael@0:  *
michael@0:  * Copies the source string, up to and including the trailing '\0', into the
michael@0:  * destination buffer.  It does not (can not) verify that the destination
michael@0:  * buffer is large enough.  It returns the "dest" argument.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strcpy(char *dest, const char *src);
michael@0: 
michael@0: /*
michael@0:  * PL_strncpy
michael@0:  *
michael@0:  * Copies the source string into the destination buffer, up to and including
michael@0:  * the trailing '\0' or up to and including the max'th character, whichever
michael@0:  * comes first.  It does not (can not) verify that the destination buffer is
michael@0:  * large enough.  If the source string is longer than the maximum length,
michael@0:  * the result will *not* be null-terminated (JLRU).
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strncpy(char *dest, const char *src, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strncpyz
michael@0:  *
michael@0:  * Copies the source string into the destination buffer, up to and including 
michael@0:  * the trailing '\0' or up but not including the max'th character, whichever 
michael@0:  * comes first.  It does not (can not) verify that the destination buffer is
michael@0:  * large enough.  The destination string is always terminated with a '\0',
michael@0:  * unlike the traditional libc implementation.  It returns the "dest" argument.
michael@0:  *
michael@0:  * NOTE: If you call this with a source "abcdefg" and a max of 5, the 
michael@0:  * destination will end up with "abcd\0" (i.e., its strlen length will be 4)!
michael@0:  *
michael@0:  * This means you can do this:
michael@0:  *
michael@0:  *     char buffer[ SOME_SIZE ];
michael@0:  *     PL_strncpyz(buffer, src, sizeof(buffer));
michael@0:  *
michael@0:  * and the result will be properly terminated.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strncpyz(char *dest, const char *src, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strdup
michael@0:  *
michael@0:  * Returns a pointer to a malloc'd extent of memory containing a duplicate
michael@0:  * of the argument string.  The size of the allocated extent is one greater
michael@0:  * than the length of the argument string, because of the terminator.  A
michael@0:  * null argument, like a zero-length argument, will result in a pointer to
michael@0:  * a one-byte extent containing the null value.  This routine returns null
michael@0:  * upon malloc failure.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strdup(const char *s);
michael@0: 
michael@0: /*
michael@0:  * PL_strfree
michael@0:  *
michael@0:  * Free memory allocated by PL_strdup
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(void)
michael@0: PL_strfree(char *s);
michael@0: 
michael@0: /*
michael@0:  * PL_strndup
michael@0:  *
michael@0:  * Returns a pointer to a malloc'd extent of memory containing a duplicate
michael@0:  * of the argument string, up to the maximum specified.  If the argument
michael@0:  * string has a length greater than the value of the specified maximum, the
michael@0:  * return value will be a pointer to an extent of memory of length one
michael@0:  * greater than the maximum specified.  A null string, a zero-length string,
michael@0:  * or a zero maximum will all result in a pointer to a one-byte extent
michael@0:  * containing the null value.  This routine returns null upon malloc failure.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strndup(const char *s, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strcat
michael@0:  *
michael@0:  * Appends a copy of the string pointed to by the second argument to the
michael@0:  * end of the string pointed to by the first.  The destination buffer is
michael@0:  * not (can not be) checked for sufficient size.  A null destination
michael@0:  * argument returns null; otherwise, the first argument is returned.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strcat(char *dst, const char *src);
michael@0: 
michael@0: /*
michael@0:  * PL_strncat
michael@0:  *
michael@0:  * Appends a copy of the string pointed to by the second argument, up to
michael@0:  * the maximum size specified, to the end of the string pointed to by the
michael@0:  * first.  The destination buffer is not (can not be) checked for sufficient
michael@0:  * size.  A null destination argument returns null; otherwise, the first 
michael@0:  * argument is returned.  If the maximum size limits the copy, then the
michael@0:  * result will *not* be null-terminated (JLRU).  A null destination
michael@0:  * returns null; otherwise, the destination argument is returned.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strncat(char *dst, const char *src, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strcatn
michael@0:  *
michael@0:  * Appends a copy of the string pointed to by the third argument, to the
michael@0:  * end of the string pointed to by the first.  The second argument specifies
michael@0:  * the maximum size of the destination buffer, including the null termination.
michael@0:  * If the existing string in dst is longer than the max, no action is taken.
michael@0:  * The resulting string will be null-terminated.  A null destination returns
michael@0:  * null; otherwise, the destination argument is returned.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strcatn(char *dst, PRUint32 max, const char *src);
michael@0: 
michael@0: /*
michael@0:  * PL_strcmp
michael@0:  *
michael@0:  * Returns an integer, the sign of which -- positive, zero, or negative --
michael@0:  * reflects the lexical sorting order of the two strings indicated.  The
michael@0:  * result is positive if the first string comes after the second.  The
michael@0:  * NSPR implementation is not i18n.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(PRIntn)
michael@0: PL_strcmp(const char *a, const char *b);
michael@0: 
michael@0: /*
michael@0:  * PL_strncmp
michael@0:  * 
michael@0:  * Returns an integer, the sign of which -- positive, zero, or negative --
michael@0:  * reflects the lexical sorting order of the two strings indicated, up to
michael@0:  * the maximum specified.  The result is positive if the first string comes 
michael@0:  * after the second.  The NSPR implementation is not i18n.  If the maximum
michael@0:  * is zero, only the existance or non-existance (pointer is null) of the
michael@0:  * strings is compared.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(PRIntn)
michael@0: PL_strncmp(const char *a, const char *b, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strcasecmp
michael@0:  *
michael@0:  * Returns an integer, the sign of which -- positive, zero or negative --
michael@0:  * reflects the case-insensitive lexical sorting order of the two strings
michael@0:  * indicated.  The result is positive if the first string comes after the 
michael@0:  * second.  The NSPR implementation is not i18n.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(PRIntn)
michael@0: PL_strcasecmp(const char *a, const char *b);
michael@0: 
michael@0: /*
michael@0:  * PL_strncasecmp
michael@0:  *
michael@0:  * Returns an integer, the sign of which -- positive, zero or negative --
michael@0:  * reflects the case-insensitive lexical sorting order of the first n characters
michael@0:  * of the two strings indicated.  The result is positive if the first string comes 
michael@0:  * after the second.  The NSPR implementation is not i18n.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(PRIntn)
michael@0: PL_strncasecmp(const char *a, const char *b, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strchr
michael@0:  *
michael@0:  * Returns a pointer to the first instance of the specified character in the
michael@0:  * provided string.  It returns null if the character is not found, or if the
michael@0:  * provided string is null.  The character may be the null character.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strchr(const char *s, char c);
michael@0: 
michael@0: /*
michael@0:  * PL_strrchr
michael@0:  *
michael@0:  * Returns a pointer to the last instance of the specified character in the
michael@0:  * provided string.  It returns null if the character is not found, or if the
michael@0:  * provided string is null.  The character may be the null character.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strrchr(const char *s, char c);
michael@0: 
michael@0: /*
michael@0:  * PL_strnchr
michael@0:  * 
michael@0:  * Returns a pointer to the first instance of the specified character within the
michael@0:  * first n characters of the provided string.  It returns null if the character
michael@0:  * is not found, or if the provided string is null.  The character may be the
michael@0:  * null character.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strnchr(const char *s, char c, PRUint32 n);
michael@0: 
michael@0: /*
michael@0:  * PL_strnrchr
michael@0:  *
michael@0:  * Returns a pointer to the last instance of the specified character within the
michael@0:  * first n characters of the provided string.  It returns null if the character is
michael@0:  * not found, or if the provided string is null.  The character may be the null
michael@0:  * character.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strnrchr(const char *s, char c, PRUint32 n);
michael@0: 
michael@0: /*
michael@0:  * NOTE: Looking for strcasechr, strcaserchr, strncasechr, or strncaserchr?
michael@0:  * Use strpbrk, strprbrk, strnpbrk or strnprbrk.
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * PL_strpbrk
michael@0:  *
michael@0:  * Returns a pointer to the first instance in the first string of any character
michael@0:  * (not including the terminating null character) of the second string.  It returns
michael@0:  * null if either string is null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strpbrk(const char *s, const char *list);
michael@0: 
michael@0: /*
michael@0:  * PL_strprbrk
michael@0:  *
michael@0:  * Returns a pointer to the last instance in the first string of any character
michael@0:  * (not including the terminating null character) of the second string.  It returns
michael@0:  * null if either string is null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strprbrk(const char *s, const char *list);
michael@0: 
michael@0: /*
michael@0:  * PL_strnpbrk
michael@0:  *
michael@0:  * Returns a pointer to the first instance (within the first n characters) of any
michael@0:  * character (not including the terminating null character) of the second string.
michael@0:  * It returns null if either string is null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strnpbrk(const char *s, const char *list, PRUint32 n);
michael@0: 
michael@0: /*
michael@0:  * PL_strnprbrk
michael@0:  *
michael@0:  * Returns a pointer to the last instance (within the first n characters) of any
michael@0:  * character (not including the terminating null character) of the second string.
michael@0:  * It returns null if either string is null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strnprbrk(const char *s, const char *list, PRUint32 n);
michael@0: 
michael@0: /*
michael@0:  * PL_strstr
michael@0:  *
michael@0:  * Returns a pointer to the first instance of the little string within the
michael@0:  * big one.  It returns null if either string is null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strstr(const char *big, const char *little);
michael@0: 
michael@0: /*
michael@0:  * PL_strrstr
michael@0:  *
michael@0:  * Returns a pointer to the last instance of the little string within the big one.
michael@0:  * It returns null if either string is null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strrstr(const char *big, const char *little);
michael@0: 
michael@0: /*
michael@0:  * PL_strnstr
michael@0:  *
michael@0:  * Returns a pointer to the first instance of the little string within the first
michael@0:  * n characters of the big one.  It returns null if either string is null.  It
michael@0:  * returns null if the length of the little string is greater than n.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strnstr(const char *big, const char *little, PRUint32 n);
michael@0: 
michael@0: /*
michael@0:  * PL_strnrstr
michael@0:  *
michael@0:  * Returns a pointer to the last instance of the little string within the first
michael@0:  * n characters of the big one.  It returns null if either string is null.  It
michael@0:  * returns null if the length of the little string is greater than n.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strnrstr(const char *big, const char *little, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strcasestr
michael@0:  *
michael@0:  * Returns a pointer to the first instance of the little string within the big one,
michael@0:  * ignoring case.  It returns null if either string is null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strcasestr(const char *big, const char *little);
michael@0: 
michael@0: /*
michael@0:  * PL_strcaserstr
michael@0:  *
michael@0:  * Returns a pointer to the last instance of the little string within the big one,
michael@0:  * ignoring case.  It returns null if either string is null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strcaserstr(const char *big, const char *little);
michael@0: 
michael@0: /*
michael@0:  * PL_strncasestr
michael@0:  *
michael@0:  * Returns a pointer to the first instance of the little string within the first
michael@0:  * n characters of the big one, ignoring case.  It returns null if either string is 
michael@0:  * null.  It returns null if the length of the little string is greater than n.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strncasestr(const char *big, const char *little, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strncaserstr
michael@0:  *
michael@0:  * Returns a pointer to the last instance of the little string within the first
michael@0:  * n characters of the big one, ignoring case.  It returns null if either string is
michael@0:  * null.  It returns null if the length of the little string is greater than n.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strncaserstr(const char *big, const char *little, PRUint32 max);
michael@0: 
michael@0: /*
michael@0:  * PL_strtok_r
michael@0:  *
michael@0:  * Splits the string s1 into tokens, separated by one or more characters
michael@0:  * from the separator string s2.  The argument lasts points to a
michael@0:  * user-supplied char * pointer in which PL_strtok_r stores information
michael@0:  * for it to continue scanning the same string.
michael@0:  *
michael@0:  * In the first call to PL_strtok_r, s1 points to a string and the value
michael@0:  * of *lasts is ignored.  PL_strtok_r returns a pointer to the first
michael@0:  * token, writes '\0' into the character following the first token, and
michael@0:  * updates *lasts.
michael@0:  *
michael@0:  * In subsequent calls, s1 is null and lasts must stay unchanged from the
michael@0:  * previous call.  The separator string s2 may be different from call to
michael@0:  * call.  PL_strtok_r returns a pointer to the next token in s1.  When no
michael@0:  * token remains in s1, PL_strtok_r returns null.
michael@0:  */
michael@0: 
michael@0: PR_EXTERN(char *)
michael@0: PL_strtok_r(char *s1, const char *s2, char **lasts);
michael@0: 
michael@0: /*
michael@0:  * Things not (yet?) included: strspn/strcspn, strsep.
michael@0:  * memchr, memcmp, memcpy, memccpy, index, rindex, bcmp, bcopy, bzero.
michael@0:  * Any and all i18n/l10n stuff.
michael@0:  */
michael@0: 
michael@0: PR_END_EXTERN_C
michael@0: 
michael@0: #endif /* _plstr_h */