1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/lib/libc/include/plstr.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,437 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef _plstr_h
1.10 +#define _plstr_h
1.11 +
1.12 +/*
1.13 + * plstr.h
1.14 + *
1.15 + * This header file exports the API to the NSPR portable library or string-
1.16 + * handling functions.
1.17 + *
1.18 + * This API was not designed as an "optimal" or "ideal" string library; it
1.19 + * was based on the good ol' unix string.3 functions, and was written to
1.20 + *
1.21 + * 1) replace the libc functions, for cross-platform consistency,
1.22 + * 2) complete the API on platforms lacking common functions (e.g.,
1.23 + * strcase*), and
1.24 + * 3) to implement some obvious "closure" functions that I've seen
1.25 + * people hacking around in our code.
1.26 + *
1.27 + * Point number three largely means that most functions have an "strn"
1.28 + * limited-length version, and all comparison routines have a non-case-
1.29 + * sensitive version available.
1.30 + */
1.31 +
1.32 +#include "prtypes.h"
1.33 +
1.34 +PR_BEGIN_EXTERN_C
1.35 +/*
1.36 + * PL_strlen
1.37 + *
1.38 + * Returns the length of the provided string, not including the trailing '\0'.
1.39 + */
1.40 +
1.41 +PR_EXTERN(PRUint32)
1.42 +PL_strlen(const char *str);
1.43 +
1.44 +/*
1.45 + * PL_strnlen
1.46 + *
1.47 + * Returns the length of the provided string, not including the trailing '\0',
1.48 + * up to the indicated maximum. The string will not be examined beyond the
1.49 + * maximum; if no terminating '\0' is found, the maximum will be returned.
1.50 + */
1.51 +
1.52 +PR_EXTERN(PRUint32)
1.53 +PL_strnlen(const char *str, PRUint32 max);
1.54 +
1.55 +/*
1.56 + * PL_strcpy
1.57 + *
1.58 + * Copies the source string, up to and including the trailing '\0', into the
1.59 + * destination buffer. It does not (can not) verify that the destination
1.60 + * buffer is large enough. It returns the "dest" argument.
1.61 + */
1.62 +
1.63 +PR_EXTERN(char *)
1.64 +PL_strcpy(char *dest, const char *src);
1.65 +
1.66 +/*
1.67 + * PL_strncpy
1.68 + *
1.69 + * Copies the source string into the destination buffer, up to and including
1.70 + * the trailing '\0' or up to and including the max'th character, whichever
1.71 + * comes first. It does not (can not) verify that the destination buffer is
1.72 + * large enough. If the source string is longer than the maximum length,
1.73 + * the result will *not* be null-terminated (JLRU).
1.74 + */
1.75 +
1.76 +PR_EXTERN(char *)
1.77 +PL_strncpy(char *dest, const char *src, PRUint32 max);
1.78 +
1.79 +/*
1.80 + * PL_strncpyz
1.81 + *
1.82 + * Copies the source string into the destination buffer, up to and including
1.83 + * the trailing '\0' or up but not including the max'th character, whichever
1.84 + * comes first. It does not (can not) verify that the destination buffer is
1.85 + * large enough. The destination string is always terminated with a '\0',
1.86 + * unlike the traditional libc implementation. It returns the "dest" argument.
1.87 + *
1.88 + * NOTE: If you call this with a source "abcdefg" and a max of 5, the
1.89 + * destination will end up with "abcd\0" (i.e., its strlen length will be 4)!
1.90 + *
1.91 + * This means you can do this:
1.92 + *
1.93 + * char buffer[ SOME_SIZE ];
1.94 + * PL_strncpyz(buffer, src, sizeof(buffer));
1.95 + *
1.96 + * and the result will be properly terminated.
1.97 + */
1.98 +
1.99 +PR_EXTERN(char *)
1.100 +PL_strncpyz(char *dest, const char *src, PRUint32 max);
1.101 +
1.102 +/*
1.103 + * PL_strdup
1.104 + *
1.105 + * Returns a pointer to a malloc'd extent of memory containing a duplicate
1.106 + * of the argument string. The size of the allocated extent is one greater
1.107 + * than the length of the argument string, because of the terminator. A
1.108 + * null argument, like a zero-length argument, will result in a pointer to
1.109 + * a one-byte extent containing the null value. This routine returns null
1.110 + * upon malloc failure.
1.111 + */
1.112 +
1.113 +PR_EXTERN(char *)
1.114 +PL_strdup(const char *s);
1.115 +
1.116 +/*
1.117 + * PL_strfree
1.118 + *
1.119 + * Free memory allocated by PL_strdup
1.120 + */
1.121 +
1.122 +PR_EXTERN(void)
1.123 +PL_strfree(char *s);
1.124 +
1.125 +/*
1.126 + * PL_strndup
1.127 + *
1.128 + * Returns a pointer to a malloc'd extent of memory containing a duplicate
1.129 + * of the argument string, up to the maximum specified. If the argument
1.130 + * string has a length greater than the value of the specified maximum, the
1.131 + * return value will be a pointer to an extent of memory of length one
1.132 + * greater than the maximum specified. A null string, a zero-length string,
1.133 + * or a zero maximum will all result in a pointer to a one-byte extent
1.134 + * containing the null value. This routine returns null upon malloc failure.
1.135 + */
1.136 +
1.137 +PR_EXTERN(char *)
1.138 +PL_strndup(const char *s, PRUint32 max);
1.139 +
1.140 +/*
1.141 + * PL_strcat
1.142 + *
1.143 + * Appends a copy of the string pointed to by the second argument to the
1.144 + * end of the string pointed to by the first. The destination buffer is
1.145 + * not (can not be) checked for sufficient size. A null destination
1.146 + * argument returns null; otherwise, the first argument is returned.
1.147 + */
1.148 +
1.149 +PR_EXTERN(char *)
1.150 +PL_strcat(char *dst, const char *src);
1.151 +
1.152 +/*
1.153 + * PL_strncat
1.154 + *
1.155 + * Appends a copy of the string pointed to by the second argument, up to
1.156 + * the maximum size specified, to the end of the string pointed to by the
1.157 + * first. The destination buffer is not (can not be) checked for sufficient
1.158 + * size. A null destination argument returns null; otherwise, the first
1.159 + * argument is returned. If the maximum size limits the copy, then the
1.160 + * result will *not* be null-terminated (JLRU). A null destination
1.161 + * returns null; otherwise, the destination argument is returned.
1.162 + */
1.163 +
1.164 +PR_EXTERN(char *)
1.165 +PL_strncat(char *dst, const char *src, PRUint32 max);
1.166 +
1.167 +/*
1.168 + * PL_strcatn
1.169 + *
1.170 + * Appends a copy of the string pointed to by the third argument, to the
1.171 + * end of the string pointed to by the first. The second argument specifies
1.172 + * the maximum size of the destination buffer, including the null termination.
1.173 + * If the existing string in dst is longer than the max, no action is taken.
1.174 + * The resulting string will be null-terminated. A null destination returns
1.175 + * null; otherwise, the destination argument is returned.
1.176 + */
1.177 +
1.178 +PR_EXTERN(char *)
1.179 +PL_strcatn(char *dst, PRUint32 max, const char *src);
1.180 +
1.181 +/*
1.182 + * PL_strcmp
1.183 + *
1.184 + * Returns an integer, the sign of which -- positive, zero, or negative --
1.185 + * reflects the lexical sorting order of the two strings indicated. The
1.186 + * result is positive if the first string comes after the second. The
1.187 + * NSPR implementation is not i18n.
1.188 + */
1.189 +
1.190 +PR_EXTERN(PRIntn)
1.191 +PL_strcmp(const char *a, const char *b);
1.192 +
1.193 +/*
1.194 + * PL_strncmp
1.195 + *
1.196 + * Returns an integer, the sign of which -- positive, zero, or negative --
1.197 + * reflects the lexical sorting order of the two strings indicated, up to
1.198 + * the maximum specified. The result is positive if the first string comes
1.199 + * after the second. The NSPR implementation is not i18n. If the maximum
1.200 + * is zero, only the existance or non-existance (pointer is null) of the
1.201 + * strings is compared.
1.202 + */
1.203 +
1.204 +PR_EXTERN(PRIntn)
1.205 +PL_strncmp(const char *a, const char *b, PRUint32 max);
1.206 +
1.207 +/*
1.208 + * PL_strcasecmp
1.209 + *
1.210 + * Returns an integer, the sign of which -- positive, zero or negative --
1.211 + * reflects the case-insensitive lexical sorting order of the two strings
1.212 + * indicated. The result is positive if the first string comes after the
1.213 + * second. The NSPR implementation is not i18n.
1.214 + */
1.215 +
1.216 +PR_EXTERN(PRIntn)
1.217 +PL_strcasecmp(const char *a, const char *b);
1.218 +
1.219 +/*
1.220 + * PL_strncasecmp
1.221 + *
1.222 + * Returns an integer, the sign of which -- positive, zero or negative --
1.223 + * reflects the case-insensitive lexical sorting order of the first n characters
1.224 + * of the two strings indicated. The result is positive if the first string comes
1.225 + * after the second. The NSPR implementation is not i18n.
1.226 + */
1.227 +
1.228 +PR_EXTERN(PRIntn)
1.229 +PL_strncasecmp(const char *a, const char *b, PRUint32 max);
1.230 +
1.231 +/*
1.232 + * PL_strchr
1.233 + *
1.234 + * Returns a pointer to the first instance of the specified character in the
1.235 + * provided string. It returns null if the character is not found, or if the
1.236 + * provided string is null. The character may be the null character.
1.237 + */
1.238 +
1.239 +PR_EXTERN(char *)
1.240 +PL_strchr(const char *s, char c);
1.241 +
1.242 +/*
1.243 + * PL_strrchr
1.244 + *
1.245 + * Returns a pointer to the last instance of the specified character in the
1.246 + * provided string. It returns null if the character is not found, or if the
1.247 + * provided string is null. The character may be the null character.
1.248 + */
1.249 +
1.250 +PR_EXTERN(char *)
1.251 +PL_strrchr(const char *s, char c);
1.252 +
1.253 +/*
1.254 + * PL_strnchr
1.255 + *
1.256 + * Returns a pointer to the first instance of the specified character within the
1.257 + * first n characters of the provided string. It returns null if the character
1.258 + * is not found, or if the provided string is null. The character may be the
1.259 + * null character.
1.260 + */
1.261 +
1.262 +PR_EXTERN(char *)
1.263 +PL_strnchr(const char *s, char c, PRUint32 n);
1.264 +
1.265 +/*
1.266 + * PL_strnrchr
1.267 + *
1.268 + * Returns a pointer to the last instance of the specified character within the
1.269 + * first n characters of the provided string. It returns null if the character is
1.270 + * not found, or if the provided string is null. The character may be the null
1.271 + * character.
1.272 + */
1.273 +
1.274 +PR_EXTERN(char *)
1.275 +PL_strnrchr(const char *s, char c, PRUint32 n);
1.276 +
1.277 +/*
1.278 + * NOTE: Looking for strcasechr, strcaserchr, strncasechr, or strncaserchr?
1.279 + * Use strpbrk, strprbrk, strnpbrk or strnprbrk.
1.280 + */
1.281 +
1.282 +/*
1.283 + * PL_strpbrk
1.284 + *
1.285 + * Returns a pointer to the first instance in the first string of any character
1.286 + * (not including the terminating null character) of the second string. It returns
1.287 + * null if either string is null.
1.288 + */
1.289 +
1.290 +PR_EXTERN(char *)
1.291 +PL_strpbrk(const char *s, const char *list);
1.292 +
1.293 +/*
1.294 + * PL_strprbrk
1.295 + *
1.296 + * Returns a pointer to the last instance in the first string of any character
1.297 + * (not including the terminating null character) of the second string. It returns
1.298 + * null if either string is null.
1.299 + */
1.300 +
1.301 +PR_EXTERN(char *)
1.302 +PL_strprbrk(const char *s, const char *list);
1.303 +
1.304 +/*
1.305 + * PL_strnpbrk
1.306 + *
1.307 + * Returns a pointer to the first instance (within the first n characters) of any
1.308 + * character (not including the terminating null character) of the second string.
1.309 + * It returns null if either string is null.
1.310 + */
1.311 +
1.312 +PR_EXTERN(char *)
1.313 +PL_strnpbrk(const char *s, const char *list, PRUint32 n);
1.314 +
1.315 +/*
1.316 + * PL_strnprbrk
1.317 + *
1.318 + * Returns a pointer to the last instance (within the first n characters) of any
1.319 + * character (not including the terminating null character) of the second string.
1.320 + * It returns null if either string is null.
1.321 + */
1.322 +
1.323 +PR_EXTERN(char *)
1.324 +PL_strnprbrk(const char *s, const char *list, PRUint32 n);
1.325 +
1.326 +/*
1.327 + * PL_strstr
1.328 + *
1.329 + * Returns a pointer to the first instance of the little string within the
1.330 + * big one. It returns null if either string is null.
1.331 + */
1.332 +
1.333 +PR_EXTERN(char *)
1.334 +PL_strstr(const char *big, const char *little);
1.335 +
1.336 +/*
1.337 + * PL_strrstr
1.338 + *
1.339 + * Returns a pointer to the last instance of the little string within the big one.
1.340 + * It returns null if either string is null.
1.341 + */
1.342 +
1.343 +PR_EXTERN(char *)
1.344 +PL_strrstr(const char *big, const char *little);
1.345 +
1.346 +/*
1.347 + * PL_strnstr
1.348 + *
1.349 + * Returns a pointer to the first instance of the little string within the first
1.350 + * n characters of the big one. It returns null if either string is null. It
1.351 + * returns null if the length of the little string is greater than n.
1.352 + */
1.353 +
1.354 +PR_EXTERN(char *)
1.355 +PL_strnstr(const char *big, const char *little, PRUint32 n);
1.356 +
1.357 +/*
1.358 + * PL_strnrstr
1.359 + *
1.360 + * Returns a pointer to the last instance of the little string within the first
1.361 + * n characters of the big one. It returns null if either string is null. It
1.362 + * returns null if the length of the little string is greater than n.
1.363 + */
1.364 +
1.365 +PR_EXTERN(char *)
1.366 +PL_strnrstr(const char *big, const char *little, PRUint32 max);
1.367 +
1.368 +/*
1.369 + * PL_strcasestr
1.370 + *
1.371 + * Returns a pointer to the first instance of the little string within the big one,
1.372 + * ignoring case. It returns null if either string is null.
1.373 + */
1.374 +
1.375 +PR_EXTERN(char *)
1.376 +PL_strcasestr(const char *big, const char *little);
1.377 +
1.378 +/*
1.379 + * PL_strcaserstr
1.380 + *
1.381 + * Returns a pointer to the last instance of the little string within the big one,
1.382 + * ignoring case. It returns null if either string is null.
1.383 + */
1.384 +
1.385 +PR_EXTERN(char *)
1.386 +PL_strcaserstr(const char *big, const char *little);
1.387 +
1.388 +/*
1.389 + * PL_strncasestr
1.390 + *
1.391 + * Returns a pointer to the first instance of the little string within the first
1.392 + * n characters of the big one, ignoring case. It returns null if either string is
1.393 + * null. It returns null if the length of the little string is greater than n.
1.394 + */
1.395 +
1.396 +PR_EXTERN(char *)
1.397 +PL_strncasestr(const char *big, const char *little, PRUint32 max);
1.398 +
1.399 +/*
1.400 + * PL_strncaserstr
1.401 + *
1.402 + * Returns a pointer to the last instance of the little string within the first
1.403 + * n characters of the big one, ignoring case. It returns null if either string is
1.404 + * null. It returns null if the length of the little string is greater than n.
1.405 + */
1.406 +
1.407 +PR_EXTERN(char *)
1.408 +PL_strncaserstr(const char *big, const char *little, PRUint32 max);
1.409 +
1.410 +/*
1.411 + * PL_strtok_r
1.412 + *
1.413 + * Splits the string s1 into tokens, separated by one or more characters
1.414 + * from the separator string s2. The argument lasts points to a
1.415 + * user-supplied char * pointer in which PL_strtok_r stores information
1.416 + * for it to continue scanning the same string.
1.417 + *
1.418 + * In the first call to PL_strtok_r, s1 points to a string and the value
1.419 + * of *lasts is ignored. PL_strtok_r returns a pointer to the first
1.420 + * token, writes '\0' into the character following the first token, and
1.421 + * updates *lasts.
1.422 + *
1.423 + * In subsequent calls, s1 is null and lasts must stay unchanged from the
1.424 + * previous call. The separator string s2 may be different from call to
1.425 + * call. PL_strtok_r returns a pointer to the next token in s1. When no
1.426 + * token remains in s1, PL_strtok_r returns null.
1.427 + */
1.428 +
1.429 +PR_EXTERN(char *)
1.430 +PL_strtok_r(char *s1, const char *s2, char **lasts);
1.431 +
1.432 +/*
1.433 + * Things not (yet?) included: strspn/strcspn, strsep.
1.434 + * memchr, memcmp, memcpy, memccpy, index, rindex, bcmp, bcopy, bzero.
1.435 + * Any and all i18n/l10n stuff.
1.436 + */
1.437 +
1.438 +PR_END_EXTERN_C
1.439 +
1.440 +#endif /* _plstr_h */
